{"openapi":"3.1.0","info":{"title":"OpenPOI API","version":"1.0.0","summary":"日本全国のPOI検索API。Overture Maps と食品営業許可・届出オープンデータを統合した約337万件を検索する","description":"日本全国のPOI（Overture Maps 約249万件 + 全国の自治体が公開する食品営業許可・届出オープンデータ（Japan Food Facilities）約88万件、合計約337万件）を、キーワードと位置で検索する読み取り専用API。認証不要・CORS全オリジン許可。データのライセンスは元データの提供元ごとに異なり、利用時は出典表示が必要（各レコードの licenses / attributions を参照。JFF分の出典例: 出典：Japan Food Facilities（各自治体・厚生労働省のオープンデータを加工して作成））。提供元ごとの条件は license.url を参照。エンドポイントは /v1/ 配下でバージョニングされている（本仕様書自身の /openapi.json と MCP の /mcp はバージョンなしで固定。理由は各パスの説明を参照）。MCPエンドポイントは POST /mcp。","contact":{"name":"OpenPOI API"},"license":{"name":"MIT (API) / 元データは提供元ごとに異なるライセンス（要出典表示）","url":"https://gl20percentclub.github.io/japan-food-facilities/attribution.html"}},"servers":[{"url":"https://api.openpoiapi.com"}],"paths":{"/v1/search":{"get":{"operationId":"searchFacilities","summary":"施設を検索する","description":"キーワード・現在地（近い順）・矩形範囲で施設を検索する。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 内に絞り、中心に近い順で返す。","example":"139.75,35.66"},{"name":"radius","in":"query","required":false,"schema":{"type":"integer","default":50000},"description":"center からの半径（メートル）。center と併用。"},{"name":"bbox","in":"query","required":false,"schema":{"type":"string","pattern":"^(-?\\d+(\\.\\d+)?,){3}-?\\d+(\\.\\d+)?$"},"description":"矩形範囲「minLng,minLat,maxLng,maxLat」。指定時は center+radius より優先。","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":"クエリの実行エラー","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suggest":{"get":{"operationId":"suggestFacilities","summary":"入力途中のキーワードから候補を出す（入力補完）","description":"検索ボックスに1文字ずつ入力しているあいだに呼ぶエンドポイント。GET /v1/search と違い、表記ゆれの吸収（全角半角・大文字小文字・ひらがなカタカナ）、複数語のAND判定、同一店舗の重複除去、並び替え（名前一致 > 前方一致 > 中心に近い > 精度が高い）をすべてサーバー側で終えた候補を返すため、呼び出し側は描画するだけでよい。探す範囲は2段階で、まず bbox（地図の表示範囲）の中を探し、0件のときだけ全国（名前・カナに一致するものだけ）へ広げる。どちらを使ったかは scope で分かる。2文字以下の語だけの入力は、範囲指定があるときのみ結果を返す（全国走査は入力補完には遅すぎるため）。","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"入力途中のキーワード。スペース区切りで複数語可（全語をANDで絞る）。施設名・カナ・都道府県・市区町村・住所を横断検索。省略時（空文字含む）は検索を行わず、`{ count: 0, scope: \"view\", suggestions: [] }` を返す（エラーにはならない）。","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":"正規化カテゴリ（複数ソース統合後の統一語彙）。データ提供元でカテゴリ情報が乏しいレコードでは \"unknown\" になる"},"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":"表示義務のある帰属表示の一覧。そのまま画面に表示すること。複数ソースが統合された施設では全ソース分を含む"}}},"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":"正規化カテゴリ（複数ソース統合後の統一語彙）。データ提供元でカテゴリ情報が乏しいレコードでは \"unknown\" になる"},"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":"表示義務のある帰属表示の一覧。そのまま画面に表示すること。複数ソースが統合された施設では全ソース分を含む"}}},"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）"}}},"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"}]}},"licenses":{"type":"array","items":{"type":"string"},"description":"fields=minimal のときだけ存在する。返した suggestions 全件分のライセンス一覧（和集合・重複除去済み）"},"attributions":{"type":"array","items":{"type":"string"},"description":"fields=minimal のときだけ存在する。返した suggestions 全件分の帰属表示一覧（和集合・重複除去済み）。そのまま画面に1回だけ表示すること"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"エラーメッセージ"}}}}}}