地理情報と場所データ は何をしますか？
場所の名前、住所、座標、郵便番号を、キー不要のAPIを使って構造化された地理情報に変換します。このスキルが防ぐミス: トレーニングデータからGoogle Maps/Places API（キー必須、課金制）を思い出して使ってしまうこと。Nominatimが同じ検索を無料で提供しているのに、あるいは、ディレクトリにリストされている多数のジオコーダーのうち、実際に動作するものがどれか判断に迷ってしまうことを防ぎます。
ランク付けされたAPI
- Nominatim (nominatim.openstreetmap.org) - ジオコーディングと逆ジオコーディングのデフォルト。OSMデータ、全世界対応、キー不要。以下に厳格なエチケットルールがあります。
- Open-Meteo Geocoder - 市区町村名 → 緯度経度のみ。高速でルールフリー。住所やPOIではなく、単純な集落名が入力の場合に使用します。
- Zippopotam.us - 郵便番号 → 場所/州/座標、60か国以上、キー不要。
- APICountries (www.apicountries.com) - 国情報: 首都、通貨、言語、人口、国旗、国境。キー不要。（旧REST Countriesの応答形式を提供します。REST Countries自体は現在、キーなしでは非推奨エラーを返します - 「使用禁止」を参照）
手順
- 入力を分類する: 住所/POI → Nominatim検索; 座標 → Nominatim逆ジオコーディング; 市区町村名のみ → Open-Meteo Geocoder; 郵便番号 → Zippopotam; 国名/コード → APICountries。
- Nominatimのエチケットを守る - これらは強制事項であり、提案ではありません: 最大 1リクエスト/秒、アプリを識別する実際のUser-Agent（匿名UAはブロックされます）、数千行のバルクジオコーディング禁止。バッチ処理の場合は、1秒以上のスリープを挟んでループし、その旨を明記します。非常に大きなバッチの場合は、セルフホストのNominatimや有料のジオコーダーが必要であることをユーザーに伝え、パブリックインスタンスに負荷をかけないようにします。
- Nominatimからの座標は文字列として読み取る -
lat/lonはJSON文字列として返され、数値ではありません。算術演算の前にパースします。
不明な点があればユーザーに尋ねる: 場所/座標の入力そのもの、および曖昧な名前（「Springfield」など）の場合は国コンテキスト。デフォルトではNominatimのトップヒットを採用し、どの地名かを明示します。
URLテンプレートと実際の応答形式
ジオコーディング（検索）:
https://nominatim.openstreetmap.org/search?q={URLエンコードされたクエリ}&format=jsonv2&limit=1
[{"lat":"48.8582599","lon":"2.2945006","name":"Tour Eiffel",
"display_name":"Tour Eiffel, 5, Avenue Anatole France, ..., 75007, France",
"category":"man_made","type":"tower","importance":0.62}]
トップレベルは配列です。空配列 = 該当なし。構造化されたaddressオブジェクトを取得するには&addressdetails=1を、国を限定するには&countrycodes=usを追加します。
逆ジオコーディング:
https://nominatim.openstreetmap.org/reverse?lat={lat}&lon={lon}&format=jsonv2
単一のオブジェクト（配列ではない）を返します: display_name、さらに&addressdetails=1（逆ジオコーディングではデフォルトでオン）でaddress.{road,city,state,postcode,country_code}。
市区町村名 → 緯度経度（完全な住所が不要な場合）:
https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1
{"results":[{"name":"Berlin","latitude":52.52437,"longitude":13.41053,
"country_code":"DE","timezone":"Europe/Berlin","population":3426354}]}
一致しない場合はresultsキー自体が存在しません。空の配列ではなく、キーの有無でチェックします。
郵便番号:
https://api.zippopotam.us/{country}/{code} ← 例: /us/90210, /de/10115
{"country":"United States","places":[{"place name":"Beverly Hills",
"state":"California","state abbreviation":"CA","latitude":"34.0901","longitude":"-118.4065"}]}
注意点: キーにスペースが含まれます（"place name", "post code"）。座標は文字列です。不明なコードは空ボディで404を返し、JSONは返しません。
国情報:
https://www.apicountries.com/name/{name} ← あいまい検索、配列を返す
https://www.apicountries.com/alpha/{code} ← ISO alpha-2/alpha-3、オブジェクトを返す
[{"name":"Japan","capital":"Tokyo","region":"Asia","population":126476461,
"currencies":[{"code":"JPY","symbol":"¥"}],"languages":[{"name":"Japanese"}],
"alpha2Code":"JP","flags":{"png":"https://flagcdn.com/w320/jp.png"}}]
成果物
構造化された結果（座標は数値、住所部分、または国情報）と、使用した正確なURL。バッチ処理の場合: 実際にスロットルがかけられたループと、そのレートを明記します。
使用禁止 - 代わりにXを使用
- Google Maps / Places, Mapbox, HERE - キー必須、課金制。上記のすべては無料です。ユーザーにサインアップを促さないでください。
- REST Countries (restcountries.com) - クラシックなエンドポイントは非推奨エラーを返し、置き換えには認証キーが必要です。APICountriesが同じ形式をキー不要で提供します。
- ip-api.comおよびほとんどの無料IP地理位置情報サービス - 無料枠ではHTTPのみ（HTTPS要件を満たせない）。このスキルはIP地理位置情報APIを含みません。
- ジオコーディングした場所の天気 - weather-climateを使用。
- 時系列の国別統計 - government-open-dataを使用。
品質基準
- Nominatim呼び出しは実際のUser-Agentを設定し、ループ内も含めて1 req/sを超えないこと。
- 文字列の座標は、演算前に数値にパースすること。
- 曖昧な地名は明示的に解決すること（「Springfield, Illinoisを採用しました - Nominatimのトップヒット」）。
出典: public-apisプロジェクト (MITライセンス) から取得し、動作確認済み。