場所をジオコードする

欧州経済領域（EEA）のデベロッパー

プレイス ジオコーディングを使用すると、プレイス ID から住所を取得できます。

プレイス ID は、Google プレイスのデータベースおよび Google マップで特定の場所を一意に識別する ID です。住所をジオコーディングする際にプレイス ID を取得する。プレイス ID は、Place Details（新版）、テキスト検索（新版）、Nearby Search（新版）など、他の多くの API からも取得できます。

プレイス ジオコーディング リクエスト

場所のジオコーディング リクエストは、次の形式の HTTP GET リクエストです。

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

PLACE_ID には、関心対象地域のプレイス ID が含まれます。

他のすべてのパラメータは、URL パラメータとして渡すか、API キーやフィールド マスクなどのパラメータの場合は、GET リクエストの一部としてヘッダーで渡します。次に例を示します。

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

または、curl コマンドで次のように指定します。

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

OAuth を使用してリクエストを行う

Geocoding API v4 は、認証に OAuth 2.0 をサポートしています。Geocoding API で OAuth を使用するには、OAuth トークンに正しいスコープを割り当てる必要があります。Geocoding API は、プレイス ジオコーディングで使用する次のスコープをサポートしています。

  • https://www.googleapis.com/auth/maps-platform.geocode - すべての Geocoding API メソッドで使用します。
  • https://www.googleapis.com/auth/maps-platform.geocode.place — プレイス ジオコーディングで GeocodePlace と組み合わせてのみ使用します。

また、すべての Geocoding API メソッドに一般的な https://www.googleapis.com/auth/cloud-platform スコープを使用することもできます。このスコープは、すべてのメソッドへのアクセスを許可する一般的なスコープであるため、開発時には便利ですが、本番環境では使用できません。

詳細と例については、OAuth を使用するをご覧ください。

プレイス ジオコーディングのレスポンス

プレイス ジオコーディングは、プレイス ID に対応する場所を表す GeocodeResult オブジェクトを返します。

Geocoding API のレスポンスには、GeocodeResult 内の 2 つの主要な場所に types 配列が含まれます。

  1. GeocodeResult.types: この配列は、結果の全体的なタイプを示します。指定できる値は、Places API で使用される場所タイプから取得されます。詳細については、場所のタイプ表 A と表 B をご覧ください。
  2. GeocodeResult.addressComponents[].types: 各住所コンポーネントには、住所の特定の部分のタイプを示す types 配列があります。これらの値は、Places API で使用される住所のタイプと住所コンポーネントのタイプの表から取得されます。

完全な JSON オブジェクトは次の形式になります。

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

必須パラメータ

  • place - 人が読める形式の住所を取得する場所の ID。プレイス ID は、Google の他の API で使用できる一意の識別子です。たとえば、Roads API から返される placeID を使用して、スナップ ポイントの住所を取得できます。プレイス ID について詳しくは、プレイス ID をご覧ください。

オプション パラメータ

  • languageCode

    結果を返す言語。

    • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
    • languageCode が指定されていない場合、API はデフォルトでその場所の現地の言語と文字を使用します。無効な言語コードを指定すると、API は INVALID_ARGUMENT エラーを返します。
    • API は、ユーザーと地元住民の両方が読める番地を提供できるよう最善を尽くします。この目標を達成するため、住所は現地語で返され、必要に応じてユーザーが読める文字に変換されます。このとき、ユーザーが指定した言語が考慮されます。他のすべてのアドレスは、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は、最初のコンポーネントから選択されます。
    • 優先言語で名前が利用できない場合、API は最も近い一致を使用します。
    • 優先言語は、API が返す結果のセットと、それらが返される順序にわずかに影響します。ジオコーダーは、言語によって略語（通りの種類の略語など）や同義語（ある言語では有効だが別の言語では無効な場合がある）を異なる方法で解釈します。

  • regionCode

    2 文字の CLDR コード値としての地域コード。デフォルト値はありません。ほとんどの CLDR コードは ISO 3166-1 コードと同じです。

    住所のジオコーディング（フォワード ジオコーディング）を行う場合、このパラメータは、サービスから返される結果を特定の地域に制限する際に影響を与えますが、完全に制限するわけではありません。場所またはプレイスをジオコーディングする場合（リバース ジオコーディングまたはプレイス ジオコーディング）、このパラメータを使用して住所の形式を設定できます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響を与える可能性があります。

  • FieldMask

    レスポンス フィールド マスクを作成して、レスポンスで返すフィールドを指定します。URL パラメータ $fields または fields を使用するか、HTTP ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクをメソッドに渡します。たとえば、次のリクエストでは、レスポンスの formattedAddress フィールドのみが返されます。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    レスポンスは次のとおりです。 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    詳細については、返すフィールドの選択をご覧ください。