通常、「ジオコーディング」という言葉は、人が判読できる住所を地図上の地点に変換することを意味します。一方、地図上の地点を人が判読できる住所に変換する処理を「リバース ジオコーディング」と呼びます。
リバース ジオコーディング リクエスト
必須パラメータ
latlng- 最も近い人間が読み取れる住所を取得する場所を指定する緯度と経度の座標。key- アプリケーションの API キー。このキーを使ってアプリケーションを識別し、割り当て量を管理します。キーを取得する方法を学ぶ。
オプション パラメータ
次に、リバース ジオコーディング リクエストに含めることができる省略可能なパラメータを示します。
language- 結果を返す言語。- サポートされている言語の一覧をご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。
languageが指定されていない場合、ジオコーダは、Accept-Languageヘッダーで指定された優先言語か、リクエストの送信元ドメインの言語の使用を試みます。- ジオコーダは、できるだけユーザーとローカルの両言語で判読可能な番地を返します。そのために、ジオコーダはローカル言語で番地を返し、優先言語も考慮して、必要に応じてユーザーが理解できるスクリプトに書き直します。それ以外の住所はすべて、優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントで選択した言語と同じ言語で返されます。
- 優先言語で名前を表示できない場合、ジオコーダは最も近い言語を使用します。
region- ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定される地域コード。このパラメータは、適用される法律に基づいて結果に影響することもあります。result_type- 1 つ以上の住所タイプのフィルタです。パイプ（|）で区切ります。パラメータに複数の住所タイプが含まれている場合、API はいずれかのタイプに一致するすべての住所を返します。処理に関する注意:result_typeパラメータは、指定された住所タイプに検索を制限しません。result_typeは検索後のフィルタとして機能します。API は指定されたlatlngのすべての結果を取得し、指定された住所タイプと一致しない結果を破棄します。次の値がサポートされています。street_addressは正確な住所を示します。routeは名前のある道路（US 101 など）を示します。intersectionは、主要交差点（通常は 2 つの大通りの交差点）を示します。politicalは行政区画を示します。通常、このタイプは行政区画のポリゴンを示します。countryは国レベルの行政区画を示し、一般的にはジオコーダから返される最上位のタイプです。administrative_area_level_1は国レベルの下の 1 次的な行政区画を示します。米国の場合、州がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。多くの場合、administrative_area_level_1 の省略名は下位区分 ISO 3166-2 とその他の一般的なリストに一致します。ただし、Google のジオコーディングの結果はさまざまな信号と位置情報データに基づいているため、これらの名前が厳密に一致するとは限りません。administrative_area_level_2は国レベルの下の 2 次的な行政区画を示します。米国の場合、郡がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。administrative_area_level_3は国レベルの下の 3 次的な行政区画を示します。このタイプは小規模な行政区域を示します。 すべての国でこの行政区画レベルが存在するわけではありません。administrative_area_level_4は国レベルより下位の 4 次の行政区画を示します。このタイプは小規模な行政区域を示します。 すべての国でこの行政区画レベルが存在するわけではありません。administrative_area_level_5は国レベルの 5 次以下の行政区画を示します。このタイプは小規模な行政区域を示します。 すべての国でこの行政区画レベルが存在するわけではありません。administrative_area_level_6は国レベルの 6 次以下の行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。administrative_area_level_7は国レベルの 7 次以下の行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。colloquial_areaは一般的に使用されている通称を示します。localityは行政区画である都市または町を示します。sublocalityは locality の下の 1 次的な行政区画を示します。一部の場所では、sublocality_level_1かsublocality_level_5のいずれかの追加タイプを受け取ります。各下位地区レベルは行政区画で、数が大きいほど区域は小さくなります。neighborhoodは名前のある地域を示します。premiseは名前のある場所を示します。通常は共通の名前を持つ建物や建物の集合体です。subpremiseは、敷地レベルより下位のアドレス指定可能なエンティティ（アパート、ユニット、スイートなど）を示します。plus_codeはエンコードされた場所の参照情報を示します。緯度と経度に基づきます。Plus Codes は、番地がない場所（建物に番号が付いていない場所や、通りに名前がない場所）で、番地の代わりに使用できます。詳しくは https://plus.codes をご覧ください。postal_codeは対象の国内で郵便物の宛先として使用される郵便番号を示します。natural_featureは特徴的な地勢を示します。airportは空港を示します。parkは名前付きの公園を示します。point_of_interestは名前のあるスポットを示します。通常、これらの「スポット」は、その地域で有名な場所のことを指し、「エンパイア ステートビル」や「エッフェル塔」など、他のカテゴリにはあまり当てはまらないものです。
location_type- 1 つ以上の位置情報タイプのフィルタ（パイプ（|）で区切る）。パラメータに複数の位置情報タイプが含まれている場合、API はいずれかのタイプに一致するすべての住所を返します。処理に関する注意:location_typeパラメータは、指定した場所のタイプに検索を制限しません。location_typeは検索後のフィルタとして機能します。API は指定されたlatlngのすべての結果を取得し、指定された場所のタイプと一致しない結果を破棄します。次の値を使用できます。"ROOFTOP"は、番地までの精度で位置情報が登録されている住所のみを返します。"RANGE_INTERPOLATED"は、2 つの正確な地点（交差点など）間で補間された近似値（通常は道路上）を反映している住所のみを返します。補間された範囲とは、一般的に番地に対してルーフトップ ジオコーディングが使用できないことを示します。"GEOMETRIC_CENTER"は、ポリライン（道路など）やポリゴン（地域）などの位置の幾何学的な中心のみを返します。"APPROXIMATE"は、近似として分類される住所のみを返します。
extra_computations- このパラメータを使用して、レスポンスで次の追加機能を指定します。 同じ API リクエストで複数の機能を有効にするには、各機能のリクエストにextra_computationsパラメータを含めます。次に例を示します。extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
result_type フィルタと location_type フィルタの両方が存在する場合、API は result_type 値と location_type 値の両方に一致する結果のみを返します。どのフィルタ値も使用できない場合、API は ZERO_RESULTS を返します。
リバース ジオコーディングの例
次の照会には、「Brooklyn」にある場所の緯度と経度の値が含まれています。
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
上記の照会を行うと、次の結果が返されます。
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
リバース ジオコーダが複数の結果を返している点に注意してください。"formatted_address" の結果には、郵便の宛て先となる住所だけでなく、その場所の地理的な名称も含まれます。たとえば、シカゴ市のある地点のジオコードを行うと、ジオコードされる地点は国（米国）、州（イリノイ）、都市（シカゴ）、番地などで示されます。ジオコーダは、これらをすべて「住所」として扱います。また、リバース ジオコーダは、これらをすべて有効な結果として返します。
リバース ジオコーダによる検索では、行政区画（国、州、都市および区域）、番地、郵便番号を照合します。
上記の照会を行った際に返される formatted_address の値の完全なリストを次に示します。
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
この API は、最も具体的な番地から、周辺地域、都市、郡、州などの大規模な行政区画まで、さまざまなタイプの住所を返します。一般的には最も正確な住所が最も重要な結果で、それはこのケースにも当てはまります。特定の住所タイプと照合したい場合は、次のタイプによる結果の制限のセクションをご覧ください。このため、結果の位置は互いに異なる場合があります。
タイプ別にフィルタされたリバース ジオコーディング
次の例では、返される住所をフィルタして、位置タイプが ROOFTOP で住所タイプが street_address の住所のみを返します。
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
注: これらのフィルタは、リバース ジオコーディングでのみ有効です。
リバース ジオコーディングのレスポンス
リバース ジオコーディングのレスポンス形式は、ジオコーディングのレスポンスと同様です。ジオコーディングのレスポンスをご覧ください。以下は、リバース ジオコーディングのレスポンスに含まれる可能性があるステータス コードです。
リバース ジオコーディングのステータス コード
ジオコーディング レスポンス オブジェクトの "status" フィールドには、リクエストのステータスが含まれます。リバース ジオコーディングが行えなかった原因を追跡できるようにデバッグ情報が含まれることもあります。"status" フィールドには次の値が含まれることがあります。
"OK"は、エラーが発生せず、少なくとも 1 件の住所が返されたことを示します。"ZERO_RESULTS"は、リバース ジオコーディングは成功したものの結果が返されなかったことを示します。これは、ジオコーダに遠隔地のlatlngが渡された場合に発生することがあります。"OVER_QUERY_LIMIT"は、割り当て量を超えていることを示します。"REQUEST_DENIED"は、リクエストが拒否されたことを示します。リクエストにresult_typeパラメータまたはlocation_typeパラメータが含まれているにもかかわらず、API キーが含まれていない可能性があります。"INVALID_REQUEST"は通常次のいずれかを示します。- クエリ（
address、components、latlng）がありません。 - 無効な
result_typeまたはlocation_typeが指定されています。
- クエリ（
"UNKNOWN_ERROR"はサーバーエラーでリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。
Plus Code のリバース ジオコーディング
Geocoding レスポンスの plus_code フィールドには、クエリされた緯度と経度に最も近いプラスコードが含まれます。また、ほとんどの場合、JSON 結果配列には、plus_code 型の完全なジオコーディング結果とプラスコードを含む住所が含まれます。デコードされたプラスコードとリクエスト地点の距離は 10 メートル未満であることが保証されます。