リバース ジオコーディング(住所検索)のリクエストとレスポンス

通常、「ジオコーディング」という用語は、人が判読できる住所を地図上の地点に変換することを意味します。一方、地図上の地点を人が判読できる住所に変換する処理をリバース ジオコーディングと呼びます。

リバース ジオコーディング リクエスト

必須パラメータ

  • latlng - 人が読める形式の最も近い住所を取得する場所を指定する緯度と経度の座標。
  • key - アプリケーションの API キー。このキーでアプリケーションを識別し、割り当てを管理します。キーを取得する方法をご覧ください。

省略可能なパラメータ

リバース ジオコーディング リクエストに含めることができるオプションのパラメータは次のとおりです。

  • language - 結果を返す言語。
    • サポートされている言語の一覧をご覧ください。サポートされている言語は頻繁に更新されるため、このリストがすべての言語を網羅しているとは限りません。
    • language が指定されていない場合、ジオコーダは Accept-Language ヘッダーで指定された優先言語、またはリクエストの送信元ドメインのネイティブ言語を使用します。
    • ジオコーダは、ユーザーと地域の双方が判読できる番地を提供するよう最善を尽くします。この目標を達成するため、この関数では住所をローカル言語で返し、使用言語を監視しながら、必要に応じてユーザーが読み取れるスクリプトに文字変換します。その他の住所はすべて優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントから選択された同じ言語で返されます。
    • 優先言語で名前を取得できない場合、ジオコーダは最も近い言語を使用します。
  • region - ccTLD(「トップレベル ドメイン」)の 2 文字の値として指定される地域コード。このパラメータは、適用される法律に基づいて結果に影響を与える可能性もあります。
  • result_type - 1 つ以上の住所タイプのフィルタをパイプ(|)で区切ります。パラメータに複数の住所タイプが含まれている場合、API はいずれかのタイプに一致するすべてのアドレスを返します。処理に関する注意: result_type パラメータは、検索を指定された住所タイプに制限しません。restrictresult_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_1sublocality_level_5 のいずれかの追加タイプを受け取ります。各下位地区レベルは行政区画で、数が大きいほど区域は小さくなります。
    • neighborhood は名前のある区域を示します。
    • premise は名前のある場所を示します。通常は共通の名前を持つ建物や建物の集合体です。
    • subpremise は名前のある場所の下の 1 次的な存在を示します。通常は共通の名前を持つ建物の集合体内の 1 棟の建物です。
    • plus_code はエンコードされた場所の参照情報を示します。緯度と経度に基づきます。Plus Codes は、番地がない場所(建物に番号が付いていない場所や、通りに名前がない場所)で、番地の代わりに使用できます。詳しくは https://plus.codes をご覧ください。
    • postal_code は対象の国内で郵便物の宛先として使用される郵便番号を示します。
    • natural_feature は特徴的な地勢を示します。
    • airport は空港を示します。
    • park は名前付きの公園を示します。
    • point_of_interest は名前のあるスポットを示します。通常、これらの「スポット」は、その地域で有名な場所のことを指し、「エンパイア ステートビル」や「エッフェル塔」など、他のカテゴリにはあまり当てはまらないものです。
  • location_type - 1 つ以上のビジネス タイプのフィルタをパイプ(|)で区切って指定します。パラメータに複数のビジネス タイプが含まれている場合、API はいずれかのタイプに一致するすべての住所を返します。処理に関する注意: location_type パラメータは、検索を指定されたロケーション タイプに制限しません。restrictlocation_type は検索後のフィルタとして機能します。API は指定された latlng のすべての結果を取得し、指定されたロケーション タイプに一致しない結果を破棄します。サポートされる値は次のとおりです。
    • "ROOFTOP" は、番地まで正確かつ正確な位置情報を Google が保持している住所のみを返します。
    • "RANGE_INTERPOLATED" は、交差点などの正確な 2 地点間で補間された近似値(通常は道路上)を反映した住所のみを返します。通常、補間された範囲は、番地に対してルーフトップ ジオコーディングが利用できないことを示します。
    • "GEOMETRIC_CENTER" は、ポリライン(道路など)やポリゴン(地域)などの場所の幾何学的中心のみを返します。
    • "APPROXIMATE" は、おおよその住所のみを返します。

result_type フィルタと location_type フィルタの両方が存在する場合、API は result_typelocation_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" は通常、次のいずれかを示します。
    • クエリ(addresscomponentslatlng)がありません。
    • 無効な result_type または location_type が指定されました。
  • "UNKNOWN_ERROR" はサーバーエラーでリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

リバース ジオコーディングとコード

ジオコーディング レスポンス内の plus_code フィールドには、クエリされた緯度と経度を最もよく表す plus code が含まれます。また、ほとんどの場合、JSON の結果配列には plus_code 型のジオコーディングの結果全体と plus code を含む住所が含まれます。デコードされた plus code からリクエスト ポイントまでの距離は 10 m 未満が保証されています。