ジオコーディング

テキストを座標に変換します。完全な住所、部分的な住所、郵便番号、地名、スポットを、どの言語でも受け付けます。

GEThttps://api.mygeocode.com/v1/forward

パラメータ

パラメータ	型	説明
`q`必須*	文字列	ジオコーディングする自由形式のテキスト。最大256文字。
`street`, `city`, `state`, `postcode`, `country`	文字列	*`q`の代わりに使う構造化形式。住所がすでにフィールドに分かれている場合に使用します。`q`がない場合は少なくとも1つが必須です。ここでの`country`はISO 3166-1 alpha-2コードです。
`place_id`	文字列	*オートコンプリートで得た`place_id`。その1つの場所を、すべての構成要素と範囲付きで返します。`q`より優先されます。
`limit`任意	整数	結果の最大数。1から10。既定値は5。
`countries`任意	文字列	カンマ区切りのISO 3166-1 alpha-2コード。これらの国の結果だけが返されます。例：`gb,ie`。
`bounds`任意	文字列	10進数の度で`south,west,north,east`。範囲内の結果が上位に表示されます。範囲外の結果を除外するには`strict=1`を追加します。
`proximity`任意	文字列	`lat,lon`。この地点に近い結果が上位に表示されます。
`lang`任意	文字列	レスポンス内の名前に使うISO 639-1コード。既定値は`en`。
`key`任意	文字列	`X-API-Key`ヘッダーで送信しない場合のAPIキー。

例

curlJavaScriptPython

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=Dam+1,+Amsterdam&countries=nl&limit=1"

const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "Dam 1, Amsterdam");
url.searchParams.set("countries", "nl");
url.searchParams.set("limit", "1");

const data = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(data.results[0]);

import requests

r = requests.get("https://api.mygeocode.com/v1/forward",
                 params={"q": "Dam 1, Amsterdam", "countries": "nl", "limit": 1}, headers={"X-API-Key": "YOUR_KEY"}, timeout=10)
print(r.json()["results"][0])

レスポンス

{
  "status": "ok",
  "query": "Dam 1, Amsterdam",
  "results": [
    {
      "formatted": "Dam 1, 1012 JS Amsterdam, Netherlands",
      "lat": 52.373119,
      "lon": 4.893604,
      "type": "address",
      "precision": "house",
      "confidence": 0.98,
      "place_id": "nl.addr.c21d40e8",
      "components": {
        "house_number": "1",
        "road": "Dam",
        "neighbourhood": "Centrum",
        "city": "Amsterdam",
        "state": "North Holland",
        "state_code": "NH",
        "postcode": "1012 JS",
        "country": "Netherlands",
        "country_code": "nl"
      },
      "bounds": { "north": 52.373519, "south": 52.372719, "east": 4.894204, "west": 4.893004 }
    }
  ]
}

レスポンスフィールド

フィールド	型	説明
`query`	文字列	前後の空白を除去した後に解釈したテキスト。
`results`	配列	一致した結果（最も良いものが先頭）。何も一致しない場合は空です。
`results[].formatted`	文字列	その国の慣例的な書式による完全な住所。
`results[].lat`, `lon`	数値	WGS 84の10進数の度。
`results[].type`	文字列	`address`, `street`, `postcode`, `city`, `region`, `country`, `poi`.
`results[].precision`	文字列	`house`、`street`、`postcode`、`admin`。その地点が何を表しているか。カバレッジをご覧ください。
`results[].confidence`	数値	0から1。結果がクエリにどの程度一致しているか。0.5未満は推測を意味します。
`results[].place_id`	文字列	この場所の安定した識別子。
`results[].components`	オブジェクト	住所の構成要素。下記をご覧ください。
`results[].bounds`	オブジェクト	一致した地物の`north`、`south`、`east`、`west`。

構成要素のキー

該当するキーだけが含まれます。どの国でも同じキーが使われます。

キー	意味
`name`	一致したものがスポットや建物の場合、その名前。
`house_number`	文字や範囲を含みます：`221B`、`12-14`。
`road`	種別を含む通りの名前：`Baker Street`、`Avenue Anatole France`。
`neighbourhood`, `suburb`	市内の地区（その国で使われている場合）。
`city`	市、町、村。
`county`	郡または地区。
`state`, `state_code`	州、県、地域と、存在する場合はそのISO 3166-2接尾辞。
`postcode`	郵便事業者の書式に従った郵便番号。
`country`, `country_code`	国名と、小文字のISO 3166-1 alpha-2コード。

注意事項

結果は、信頼度、精度、近さを組み合わせて並べられます。選択肢を表示する場合を除き、最初の結果を使ってください。
既知の通りで番地が見つからない場合、結果はtype: streetとprecision: streetになり、データが許す範囲で番地が補間されます。これが重要な場合はprecisionを確認してください。
郵便番号だけをqに指定しても問題ありません。郵便番号のみを扱う処理では、郵便番号エンドポイントの方が高速で、郵便事業者の地名を返します。
ある場所に対して、その場所とは異なる文字体系でクエリを送っても（たとえば日本の住所をキリル文字で）動作しますが、レスポンスの文字体系はlangで決まります。

他のプロバイダーの形式での同じ検索

これらのプロバイダー向けに書いたコードがすでにある場合は、そのまま使えます。互換ホストは同じパスとパラメータを受け付け、このエンドポイントを背後に使って、そのプロバイダーのレスポンス形式で応答します。互換ホストの仕組みをご覧ください。

プロバイダー	ホスト	パス
Googleマップ・プラットフォーム（Google Maps Platform）	`gapi.mygeocode.com`	`/maps/api/geocode/json?address=...`
Bing Maps RESTサービス	`bing.mygeocode.com`	`/REST/v1/Locations?q=...` `/REST/v1/Locations?countryRegion=...&locality=...&addressLine=...`
HEREジオコーディング・検索（HERE Geocoding and Search）	`here.mygeocode.com`	`/v1/geocode?q=...` `/v1/geocode?qq=street=...;city=...`
Mapbox Geocoding	`mapbox.mygeocode.com`	`/geocoding/v5/mapbox.places/{query}.json` `/search/geocode/v6/forward?q=...`
Geocode.Farm	`farm.mygeocode.com`	`/forward/?addr=...` `/v3/json/forward/?addr=...`
OpenStreetMap Nominatim	`osm.mygeocode.com`	`/search?q=...&format=json` `/search?street=...&city=...&country=...&format=json`
OpenCage	`opencage.mygeocode.com`	`/geocode/v1/json?q=...` `/geocode/v1/geojson?q=...`
LocationIQ	`locationiq.mygeocode.com`	`/v1/search?q=...&format=json`
Geoapify	`geoapify.mygeocode.com`	`/v1/geocode/search?text=...`
TomTom Search	`tomtom.mygeocode.com`	`/search/2/geocode/{query}.json` `/search/2/structuredGeocode.json?countryCode=...&streetName=...`
MapQuest Geocoding	`mapquest.mygeocode.com`	`/geocoding/v1/address?location=...` `/geocoding/v1/batch?location=...&location=...`
Geocodio	`geocodio.mygeocode.com`	`/v1.7/geocode?q=...` `/v1.7/geocode (POST, JSON array)`
PositionStack	`positionstack.mygeocode.com`	`/v1/forward?query=...`

一括検索

同じパスに、最大100件の住所の配列であるqueriesを含むJSON本文をPOSTすると、応答には送信した順序どおりにクエリごとに1エントリを持つresults配列が含まれます。各エントリが1件のリクエストとして数えられ、割り当ての残りを超える一括処理は全体が拒否されます。

$ curl -X POST "https://api.mygeocode.com/v1/forward" -H "Content-Type: application/json" -d '{"queries": ["Brandenburg Gate, Berlin", "Bahnhofstrasse 1, Zurich"]}'

エラー

q、構造化フィールド、place_idのいずれもない場合、limitが1から10の範囲外の場合、またはboundsかproximityが不正な形式の場合は400 invalid_request。その他についてはエラーをご覧ください。