{"openapi":"3.1.0","info":{"title":"OpenPOI API","version":"1.0.0","summary":"日本全国のPOI検索API。Overture Maps と食品営業許可・届出オープンデータを統合した約337万件を検索できるAPIです。","description":"日本全国のPOI検索API。Overture Maps と食品営業許可・届出オープンデータを統合した約337万件を検索できるAPIです。","contact":{"name":"OpenPOI API"},"license":{"name":"MIT (API) / 元データは提供元ごとに異なるライセンス（要出典表示。詳細はurl参照）","url":"https://openpoiapi.com/attribution.html"}},"servers":[{"url":"https://api.openpoiapi.com"}],"paths":{"/v1/search":{"get":{"operationId":"searchFacilities","summary":"施設を検索する","description":"キーワード（q）・現在地（center）・矩形範囲（bbox）で施設を検索します。q / center / bbox はいずれも省略できますが、通常は q を指定してください。範囲は bbox、center+radius の順に優先され、center を指定したときだけ結果が中心に近い順に並びます。","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"検索キーワード。スペース区切りで複数語可（各語をORで検索）。施設名・カナ・都道府県・市区町村・住所を横断検索。例: ラーメン、世田谷区 カフェ","example":"ラーメン"},{"name":"center","in":"query","required":false,"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$"},"description":"中心座標「lng,lat」（経度が先）。指定すると radius 内に絞り、中心に近い順で返す。形式が違う・範囲外（緯度±90・経度±180）のときは400を返す（lat,lng の順で書くと緯度が範囲外になり400になる）。","example":"139.75,35.66"},{"name":"radius","in":"query","required":false,"schema":{"type":"integer","default":50000},"description":"center からの半径（メートル）。center と併用。正の数でないときは400を返す。"},{"name":"bbox","in":"query","required":false,"schema":{"type":"string","pattern":"^(-?\\d+(\\.\\d+)?,){3}-?\\d+(\\.\\d+)?$"},"description":"矩形範囲「minLng,minLat,maxLng,maxLat」。指定時は center+radius より優先。形式が違う・範囲外・minLng>maxLng・minLat>maxLat のときは400を返す。","example":"139.6,35.5,139.9,35.8"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"返す最大件数（1〜200にクランプ）。"}],"responses":{"200":{"description":"検索結果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"クエリの実行エラー、または center / bbox / radius の指定が不正（形式が違う・緯度経度が範囲外・緯度と経度が逆・bbox の大小が逆・radius が正の数でない）。error に直し方を含むメッセージを返す","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suggest":{"get":{"operationId":"suggestFacilities","summary":"入力途中のキーワードから候補を出す（入力補完）","description":"検索ボックスの入力中に呼ぶエンドポイントです。表記ゆれの吸収・重複除去・並び替えを済ませた候補を返すので、受け取った順にそのまま描画できます。施設候補に加えて、カテゴリ・ブランド・地名の語彙（vocabulary）と、入力欄に重ねて表示できる補完文字列（completion）も返します。","x-remarks":["探す範囲は bbox の中が先で、0件のときだけ全国に広げます。どちらを使ったかは scope で分かります。","2文字以下の語だけの入力は、bbox か center を指定したときだけ結果を返します。"],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"入力途中のキーワード。スペース区切りで複数語可（全語をANDで絞る）。施設名・カナ・都道府県・市区町村・住所を横断検索。省略時（空文字含む）は検索を行わず、`{ count: 0, scope: \"view\", suggestions: [], vocabulary: [], completion: null }` を返す（エラーにはならない）。","example":"すたーば"},{"name":"bbox","in":"query","required":false,"schema":{"type":"string","pattern":"^(-?\\d+(\\.\\d+)?,){3}-?\\d+(\\.\\d+)?$"},"description":"地図の表示範囲「minLng,minLat,maxLng,maxLat」。まずこの中から候補を探す。","example":"139.6,35.5,139.9,35.8"},{"name":"center","in":"query","required":false,"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$"},"description":"地図中心「lng,lat」（経度が先）。近い順の並び替えに使う。bbox 省略時は radius と組み合わせて表示範囲を作る。","example":"139.75,35.66"},{"name":"radius","in":"query","required":false,"schema":{"type":"integer","default":50000},"description":"center からの半径（メートル）。bbox が無いときだけ使う。"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":8,"minimum":1,"maximum":20},"description":"返す候補の最大件数（1〜20にクランプ）。"},{"name":"fields","in":"query","required":false,"schema":{"type":"string","enum":["full","minimal"],"default":"full"},"description":"\"minimal\" を指定すると、候補1件ごとの category/business_type/source/licenses/attributions を省いた軽量なレスポンス（MinimalSuggestion。licenses/attributions はレスポンス直下に1回だけ載る）を返す。未指定・\"full\"・不明な値はすべて従来どおりの完全なレスポンスになる（後方互換）。"}],"responses":{"200":{"description":"候補（そのまま一覧に出せる並び）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestResponse"}}}},"400":{"description":"クエリの実行エラー","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Facility":{"type":"object","description":"施設1件。1レコードは1件の営業許可・届出を表す（同一施設が業種違いで複数レコードになることがある）","properties":{"name":{"type":"string","description":"施設名"},"name_kana":{"type":"string","description":"施設名カナ"},"prefecture":{"type":"string","description":"都道府県"},"city":{"type":"string","description":"市区町村（正規化済み）"},"address":{"type":"string","description":"所在地"},"category":{"type":"string","description":"正規化カテゴリ（複数ソース統合後の統一語彙）。取りうる値: restaurant / cafe / fast_food / bakery / bar_izakaya / grocery / convenience_store / retail_other / lodging / tourism / medical / education / public_facility / finance / service_other / station / unknown。データ提供元でカテゴリ情報が乏しいレコードでは \"unknown\" になる。station（鉄道駅）は追加された値で、既存の値は変わらない"},"business_type":{"type":"string","description":"営業許可・届出の業種（例: 飲食店営業）。category と同値（後方互換のため残している）"},"lat":{"type":["number","string"],"description":"緯度（WGS84）。座標が無い施設は空文字"},"lng":{"type":["number","string"],"description":"経度（WGS84）。座標が無い施設は空文字"},"level":{"type":["integer","string","null"],"description":"ジオコーディング精度（1=都道府県 2=市区町村 3=町丁目 8=街区・地番。小さいほど大まか）"},"source":{"type":"string","description":"代表レコードの出所ソース識別子（例: \"jff\" / \"overture\"）。複数ソースが統合された施設でも値は単一の文字列（配列ではない）"},"licenses":{"type":"array","items":{"type":"string"},"description":"出所元のライセンス一覧。複数ソースが統合された施設では和集合（重複除去済み）"},"attributions":{"type":"array","items":{"type":"string"},"description":"出所元の帰属表示（参考情報。画面表示は不要）。統合された施設では全ソース分を含む。保存するときはこの配列も一緒に保存すること。詳細は https://openpoiapi.com/attribution.html"}}},"SearchResponse":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer","description":"返した件数"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Facility"}}}},"Suggestion":{"type":"object","description":"入力補完の候補1件。表示（名前・住所）と地図移動（緯度経度）に必要な項目だけを持ち、座標が無い施設は含まれない","required":["name","address","lat","lng"],"properties":{"name":{"type":"string","description":"施設名"},"address":{"type":"string","description":"住所（都道府県から始まる形にそろえてある。そのまま1行で表示できる）"},"prefecture":{"type":"string","description":"都道府県"},"city":{"type":"string","description":"市区町村（正規化済み）"},"category":{"type":"string","description":"正規化カテゴリ（複数ソース統合後の統一語彙）。取りうる値: restaurant / cafe / fast_food / bakery / bar_izakaya / grocery / convenience_store / retail_other / lodging / tourism / medical / education / public_facility / finance / service_other / station / unknown。データ提供元でカテゴリ情報が乏しいレコードでは \"unknown\" になる。station（鉄道駅）は追加された値で、既存の値は変わらない"},"business_type":{"type":"string","description":"営業許可・届出の業種（例: 飲食店営業）。category と同値（後方互換のため残している）"},"lat":{"type":"number","description":"緯度（WGS84）"},"lng":{"type":"number","description":"経度（WGS84）"},"level":{"type":["integer","null"],"description":"ジオコーディング精度（1=都道府県 2=市区町村 3=町丁目 8=街区・地番。不明は null）"},"source":{"type":"string","description":"代表レコードの出所ソース識別子（例: \"jff\" / \"overture\"）。複数ソースが統合された施設でも値は単一の文字列（配列ではない）"},"licenses":{"type":"array","items":{"type":"string"},"description":"出所元のライセンス一覧。複数ソースが統合された施設では和集合（重複除去済み）"},"attributions":{"type":"array","items":{"type":"string"},"description":"出所元の帰属表示（参考情報。画面表示は不要）。統合された施設では全ソース分を含む。保存するときはこの配列も一緒に保存すること。詳細は https://openpoiapi.com/attribution.html"},"matched":{"type":"array","items":{"type":"string"},"description":"この候補の name に含まれていた入力語（表記ゆれを正規化して判定し、入力された表記のまま返す）。一致部分の強調表示などに使える。辞書の展開語だけで当たった語は含まない"}}},"MinimalSuggestion":{"type":"object","description":"fields=minimal のときの候補1件。category/business_type/source/licenses/attributions を持たない（それらは SuggestResponse 直下の licenses/attributions を参照）","required":["name","address","lat","lng"],"properties":{"name":{"type":"string","description":"施設名"},"address":{"type":"string","description":"住所（都道府県から始まる形にそろえてある。そのまま1行で表示できる）"},"prefecture":{"type":"string","description":"都道府県"},"city":{"type":"string","description":"市区町村（正規化済み）"},"lat":{"type":"number","description":"緯度（WGS84）"},"lng":{"type":"number","description":"経度（WGS84）"},"level":{"type":["integer","null"],"description":"ジオコーディング精度（1=都道府県 2=市区町村 3=町丁目 8=街区・地番。不明は null）"},"matched":{"type":"array","items":{"type":"string"},"description":"この候補の name に含まれていた入力語（表記ゆれを正規化して判定し、入力された表記のまま返す）。一致部分の強調表示などに使える。辞書の展開語だけで当たった語は含まない"}}},"SuggestResponse":{"type":"object","required":["count","scope","suggestions"],"properties":{"count":{"type":"integer","description":"返した候補の件数"},"scope":{"type":"string","enum":["view","nationwide"],"description":"どの範囲で見つけたか。view = 指定された表示範囲の中、nationwide = 表示範囲で0件だったため全国へ広げた"},"suggestions":{"type":"array","description":"候補（良い順に並んでいる。呼び出し側での並び替えは不要）。fields=minimal のときは各要素が MinimalSuggestion になる。","items":{"oneOf":[{"$ref":"#/components/schemas/Suggestion"},{"$ref":"#/components/schemas/MinimalSuggestion"}]}},"vocabulary":{"type":"array","description":"入力に前方一致したカテゴリ・ブランド・地名の語彙（最大5件。良い順）。1文字の入力や suggestions が空のときも返す","items":{"$ref":"#/components/schemas/VocabularyItem"}},"completion":{"type":["string","null"],"description":"入力の続きとして入力欄に薄く重ねて出せる補完文字列（ゴーストテキスト用）。suggestions 先頭の name が入力 q で始まればその name、そうでなく vocabulary 先頭の label が q で始まればその label、どちらも無ければ null。比較は正規化前の文字列のまま行う"},"licenses":{"type":"array","items":{"type":"string"},"description":"fields=minimal のときだけ存在する。返した suggestions 全件分のライセンス一覧（和集合・重複除去済み）"},"attributions":{"type":"array","items":{"type":"string"},"description":"fields=minimal のときだけ存在する。suggestions 全件分の帰属表示（和集合・重複除去済み。参考情報で画面表示は不要）"}}},"VocabularyItem":{"type":"object","description":"語彙1件（カテゴリ・ブランド・地名）。type で形が変わる。place のときだけ prefecture/city/center/bbox/count を持つ","required":["type","label","query"],"properties":{"type":{"type":"string","enum":["category","brand","place"],"description":"category = 業種・カテゴリ（例: ラーメン）/ brand = チェーン店名（例: スターバックス）/ place = 都道府県・市区町村"},"label":{"type":"string","description":"表示名"},"query":{"type":"string","description":"この語彙が選ばれたときに、検索し直すのに使えばよい文字列（q にそのまま渡せる）"},"prefecture":{"type":"string","description":"place のみ。都道府県"},"city":{"type":"string","description":"place のみ。市区町村（都道府県そのものの語彙では空文字）"},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"place のみ。代表点 [lng, lat]（その地名に属する施設座標の平均）"},"bbox":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"description":"place のみ。範囲 [minLng, minLat, maxLng, maxLat]（その地名に属する施設座標の最小・最大。座標の外れ値があると広がることがある）"},"count":{"type":"integer","description":"place のみ。その地名に属する施設（座標あり）の件数"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"エラーメッセージ"}}}}}}