このページは Cloud Translation API によって翻訳されました。

ジオコーディングのリクエストとレスポンス

リクエスト

Geocoding API リクエストの形式は次のとおりです。

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

ここで、outputFormat は次のいずれかの値です。

json（推奨）は、出力が JSON（JavaScript Object Notation）であることを示します。
xml は XML での出力を示します。

HTTPS は必須です。

パラメータには必須のものと省略可能なものがあります。URL の標準と同様に、パラメータはアンパサンド（&）文字を使用して区切ります。

このページの残りの部分では、リクエストのタイプごとに異なるパラメータを使用できるため、ジオコーディングとリバースジオコーディングを個別に説明します。

ジオコーディング（緯度と経度の検索）パラメータ

ジオコーディングリクエストの必須パラメータ:

address - ジオコーディングする番地または + コード。対象国の郵便業務で使用されている形式で住所を指定します。店舗名や部屋番号、部屋番号、階数など、住所の要素を追加しないでください。番地の要素はスペースで区切る必要があります（ここでは %20 に URL エスケープされています）。
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
plus code を次のようにフォーマットします（プラス記号は %2B に URL エスケープされ、スペースは %20 に URL エスケープされます）。
- グローバルコードは、4 文字のエリアコードと 6 文字以上のローカルコードです（849VCWC8+R9 は 849VCWC8%2BR9 です）。
- 複合コードは、明示的な場所を含む 6 文字以上のローカルコードです（CWC8+R9 Mountain View, CA, USA は CWC8%2BR9%20Mountain%20View%20CA%20USA です）。
--OR--
components - 要素がパイプ（|）で区切られたコンポーネントフィルタ。address が指定されている場合は、コンポーネントフィルタもオプションのパラメータとして受け入れられます。コンポーネントフィルタの各要素は、component:value ペアで構成され、ジオコーダからの結果を完全に制限します。詳しくは、後述のコンポーネントのフィルタリングをご覧ください。
key - アプリケーションの API キー。このキーでアプリケーションを識別し、割り当てを管理します。キーを取得する方法をご覧ください。

詳細なガイダンスについては、よくある質問をご覧ください。

ジオコーディングリクエストのオプションパラメータ:

bounds - ジオコーディングの結果に大きくバイアスをかけるビューポートの境界ボックス。このパラメータは、ジオコーダから返される結果にのみ影響しますが、完全に制限するわけではありません。（詳しくは、後述のビューポートのバイアスをご覧ください）。
language - 結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポートされている言語は頻繁に更新されるため、このリストがすべての言語を網羅しているとは限りません。
- language が指定されていない場合、ジオコーダは Accept-Language ヘッダーで指定された優先言語、またはリクエストの送信元ドメインのネイティブ言語を使用します。
- ジオコーダは、ユーザーと地域の双方が判読できる番地を提供するよう最善を尽くします。この目標を達成するため、この関数では住所をローカル言語で返し、使用言語を監視しながら、必要に応じてユーザーが読み取れるスクリプトに文字変換します。その他の住所はすべて優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントから選択された同じ言語で返されます。
- 優先言語で名前を取得できない場合、ジオコーダは最も近い言語を使用します。
- 優先言語は、API が返す結果のセットや、返される順序にわずかな影響を及ぼします。ジオコーダは、言語によって略語の解釈が異なる場合があります。たとえば、通りの略語や、ある言語では有効な同義語は別の言語では使用できない同義語などがこれに該当します。たとえば、utca と tér は、ハンガリー語では、それぞれ Street（Street）とスクエア（Square）の同義語です。
region - ccTLD（「トップレベルドメイン」）の 2 文字の値として指定される地域コード。このパラメータは、ジオコーダからの結果に影響を与えますが、完全に制限するわけではありません。（詳しくは、後述の地域のバイアスをご覧ください）。このパラメータは、適用される法律に基づいて結果に影響を与える可能性もあります。
components - パイプ（|）で区切られた要素を含むコンポーネントフィルタ。リクエストに address が含まれていない場合、コンポーネントフィルタは必須です。コンポーネントフィルタの各要素は、component:value ペアで構成され、ジオコーダからの結果を完全に制限します。詳しくは、後述のコンポーネントのフィルタリングをご覧ください。

レスポンス

ジオコーディングのレスポンスは、URL リクエスト内の output フラグで指定された形式か、デフォルトで JSON 形式で返されます。

この例では、Geocoding API は、プレイス ID「ChIJeRpOeF67j4AR9ydy_PIzPuM」のクエリに対して json レスポンスをリクエストしています。この場所 ID は、1600 Amphitheatre Parkway, Mountain View, CA にある建物のものである。

このリクエストでは、JSON output フラグを使用する方法を示します。

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

このリクエストでは、XML output フラグを使用する方法を示します。

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

下のタブを選択すると、JSON と XML のサンプルレスポンスが表示されます。

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

JSON レスポンスには、2 つのルート要素が含まれる点に注意してください。

"status" にはリクエストのメタデータが含まれます。下記のステータスコードをご覧ください。
"results" には、ジオコーディングされた住所情報とジオメトリ情報の配列が格納されます。

通常、住所検索に対して "results" 配列内のエントリは 1 つだけ返されますが、住所クエリがあいまいな場合、ジオコーダは複数の結果を返すことがあります。

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

XML レスポンスは、1 つの <GeocodeResponse> と 2 つの最上位要素で構成されます。

<status> にはリクエストのメタデータが含まれます。下記のステータスコードをご覧ください。
0 個以上の <result> 要素。各要素には、ジオコーディングされた住所情報とジオメトリ情報のセットが 1 つ含まれます。

XML レスポンスは JSON レスポンスよりもかなり長くなっています。このため、サービスが xml を必要とする場合を除き、優先出力フラグとして json を使用することをおすすめします。また、XML ツリーを処理する場合は、適切なノードと要素を参照できるように、ある程度の注意が必要です。出力処理で推奨される設計パターンについては、 XPath による XML の解析をご覧ください。

XML の結果はルートの <GeocodeResponse> 要素でラップされます。
複数の要素を含むエントリは、JSON では複数の配列（types）で示されますが、XML では複数の単数要素（<type>）で示されます。
空白の要素は、JSON では空の配列として示されますが、XML ではそのような要素がないことを意味します。たとえば、結果が生成されなかったレスポンスは、JSON では空の results 配列を返しますが、XML では <result> 要素を返しません。

ステータスコード

ジオコーディングレスポンスオブジェクトの "status" フィールドには、リクエストのステータスが格納されます。ジオコーディングが機能しない理由を追跡できるようにデバッグ情報が含まれる場合もあります。"status" フィールドには、次の値が含まれることがあります。

"OK" は、エラーが発生せず、住所が正常に解析され、少なくとも 1 件のジオコードが返されたことを示します。
"ZERO_RESULTS" は、検索は成功したものの結果が返されなかったことを示します。これは、実在しない address がジオコーダに渡された場合に発生することがあります。
OVER_DAILY_LIMIT は次のいずれかを示します。
- API キーがないか、無効です。
- アカウントで課金が有効になっていません。
- ご自身で設定した使用量の上限を超えています。
- 指定したお支払い方法が無効になっている（クレジットカードの有効期限が切れている場合など）
この問題の解決方法については、マップに関するよくある質問をご覧ください。
"OVER_QUERY_LIMIT" はリクエストが割り当て量を超えていることを示します。
"REQUEST_DENIED" はリクエストが拒否されたことを示します。
"INVALID_REQUEST" は一般的に、クエリ（address、components、latlng）が不足していることを示します。
"UNKNOWN_ERROR" はサーバーエラーでリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

エラーメッセージ

ジオコーダが OK 以外のステータスコードを返す場合、ジオコーディングレスポンスオブジェクト内に error_message フィールドが追加されている場合があります。このフィールドには、指定されたステータスコードの背後にある理由に関する詳細情報が含まれます。

結果

ジオコーダは、結果を（JSON）results 配列に入れて返します。住所が存在しないなど、結果が返されない場合でも、空の results 配列が返されます。（XML レスポンスは、ゼロ個以上の <result> 要素で構成されます）。

一般的な結果には、次のフィールドが含まれます。

types[] 配列は、返された結果のタイプを示します。この配列には、結果で返される対象物のタイプを示す 0 個以上のタグのセットが含まれます。たとえば、「Chicago」のジオコードは「Chicago」が都市であることを示す「locality」と、行政区画であることを示す「political」を返します。住所コンポーネントに既知のタイプがない場合、コンポーネントのタイプ配列は空の場合があります。API では、必要に応じて新しい型の値が追加されることがあります。詳しくは、住所の種類と住所コンポーネントをご覧ください。
formatted_address は、人が読める形式のこの場所の住所を含む文字列です。
ほとんどの場合、この住所は「郵便の宛先」と同一ですイギリスなど一部の国では、ライセンス上の制限があるため実際の郵便の宛先は配信できません。

フォーマット済み住所は、論理的には 1 つ以上の住所コンポーネントで構成されます。たとえば、「111 8th Avenue, New York, NY」という住所は、「111」（番地）、「8th Avenue」（道路名）、「New York」（都市名）、「NY」（アメリカの州名）で構成されています。

フォーマット済み住所は、プログラムで解析しないでください。その代わりに、フォーマット済み住所のフィールドに加えて、API レスポンスに含まれる個々の住所コンポーネントを使用してください。
address_components[] は、この住所に適用される個別のコンポーネントを含む配列です。
通常、各住所コンポーネントには次のフィールドがあります。
- types[] は住所コンポーネントのタイプを示す配列です。サポートされているタイプのリストをご覧ください。
- long_name は、ジオコーダが返した住所コンポーネントの説明または名前です。
- short_name は、住所コンポーネントの略称です（略称がある場合）。たとえば、アラスカ州の住所コンポーネントの場合は、long_name には「Alaska」が設定され、short_name には 2 文字の郵便略称を使用して「AK」が設定されます。
address_components[] 配列については、次の点に注意してください。
- 住所コンポーネントの配列には、formatted_address よりも多くのコンポーネントが含まれている場合があります。
- この配列には、formatted_address に含まれているもの以外の住所を持つ行政区画が、すべて含まれているとは限りません。特定の住所を含むすべての行政区画を取得するには、リバースジオコーディングを使用して住所の緯度と経度をパラメータとしてリクエストに渡します。
- レスポンスの形式は、リクエスト間で同じになるとは限りません。特に、address_components の数はリクエストされた住所によって異なり、同じ住所でも将来的に変わる可能性があります。コンポーネントは、配列内の位置が変わる場合があります。コンポーネントのタイプは変わる場合があります。特定のコンポーネントが以降のレスポンスに含まれない場合があります。
コンポーネントの配列を処理するには、レスポンスを解析し、式を使用して適切な値を選択する必要があります。レスポンスの解析に関するガイドをご覧ください。
postcode_localities[] は、郵便番号に含まれる地域（最大 100 件）を示す配列です。これは、結果が複数の地域区分を含む郵便番号の場合にのみ存在します。
geometry には次の情報が含まれます。
- location には、ジオコーディングされた緯度と経度の値が含まれます。通常の住所検索では、このフィールドが最も重要になります。
- location_type には、指定した場所に関する追加データが格納されます。現在サポートされている値は次のとおりです。
  - "ROOFTOP" は、返された結果が、番地まで正確かつ正確な位置情報を持つジオコードであることを示します。
  - "RANGE_INTERPOLATED" は、返された結果が（交差点などの）正確な 2 地点間で補間された近似値（通常は道路上）を反映していることを示します。通常、補間された結果が返されるのは、番地に対してルーフトップジオコーディングが使用できない場合です。
  - "GEOMETRIC_CENTER" は、返された結果がポリライン（道路など）やポリゴン（地域）などの幾何学的な中心であることを示します。
  - "APPROXIMATE" は、返された結果が近似値であることを示します。
- viewport には、返された結果の表示に推奨されるビューポートが格納されます。これは、ビューポート境界ボックスの southwest と northeast の角を定義する 2 つの緯度と経度の値として指定されます。通常、ビューポートは、結果をユーザーに表示する際に結果をフレーム処理するために使用されます。
- bounds（必要に応じて返される）には、返された結果を完全に格納できる境界ボックスが格納されます。この境界は、推奨されるビューポートと一致しない場合があります。（たとえば、厳密にはサンフランシスコにはファラロン諸島が含まれますが、これは多くの場合、ビューポートには返されません）。
plus_code（Open Location Code と plus code を参照）は、緯度と経度の座標から導出されるエンコードされた位置情報参照で、1/8, 000 度 1/8, 000 度（赤道では約 14 m x 14 m）以下のエリアを表します。Plus Code は、住所が存在しない場所（建物に番号が付いていない場所や通りに名前がない場所）で、番地の代わりに使用できます。API は常に plus code を返すわけではありません。
サービスが Plus Code を返す場合、形式はグローバルコードと複合コードの形式になります。
- global_code は、4 文字の市外局番と 6 文字以上のローカルコード（849VCWC8+R9）です。
- compound_code は、明示的な場所（CWC8+R9, Mountain View, CA, USA）を含む 6 文字以上のローカルコードです。このコンテンツをプログラムで解析しないでください。
利用可能な場合、API はグローバルコードと複合コードの両方を返します。ただし、検索結果が遠隔地（海や砂漠など）にある場合は、返されるのはグローバルコードのみです。
partial_match は、ジオコーダによって、元のリクエストに完全一致する住所は見つからなかったものの、部分一致する住所は見つかったことを示します。元のリクエストで住所の表記が間違っていたり、不完全である可能性があります。

多くの場合、リクエストで渡された地域に番地が存在しないために部分一致が発生します。また、同じ地域内に複数の場所があるリクエストを行った場合も部分一致が返されます。たとえば、「Hillpar St, Bristol, UK」の場合は、Henry Street と Henrietta Street の両方の部分一致が返されます。リクエストに表記が間違った住所コンポーネントが含まれている場合、ジオコーディングサービスが別の住所を提示することもある点に注意してください。この場合も、部分一致として結果が返されます。
place_id は、他の Google API で使用できる一意の識別子です。たとえば、Places API リクエストの place_id を使用して、電話番号、営業時間、ユーザーのクチコミなどのローカルビジネスの詳細を取得できます。プレイス ID の概要をご覧ください。

住所タイプと住所コンポーネントタイプ

結果の types[] 配列は、住所タイプを示します。住所タイプの例としては、番地、国、行政区画などがあります。また、address_components[] には住所の各部分のタイプを示す types[] 配列もあります。たとえば、番地や国などです。（以下に、タイプの一覧を示します）。住所には複数のタイプがある場合があります。タイプは「タグ」と考えることができます。たとえば、多くの都市には political タイプと locality タイプのタグが付けられています。

ジオコーダでは、次のタイプは住所タイプと住所コンポーネントタイプの両方の配列でサポートされており、返されます。

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 は名前のある場所の下の 1 次的な存在を示します。通常は共通の名前を持つ建物の集合体内の 1 棟の建物です。
plus_code はエンコードされた場所の参照情報を示します。緯度と経度に基づきます。Plus Codes は、番地がない場所（建物に番号が付いていない場所や、通りに名前がない場所）で、番地の代わりに使用できます。詳しくは https://plus.codes をご覧ください。
postal_code は対象の国内で郵便物の宛先として使用される郵便番号を示します。
natural_feature は特徴的な地勢を示します。
airport は空港を示します。
park は名前付きの公園を示します。
point_of_interest は名前のあるスポットを示します。通常、これらの「スポット」は、その地域で有名な場所のことを指し、「エンパイアステートビル」や「エッフェル塔」など、他のカテゴリにはあまり当てはまらないものです。

タイプリストが空の場合は、特定の住所コンポーネントに対して既知のタイプが存在しないことを意味します。たとえば、フランスのリュディがこれに相当します。

上記に加えて、住所コンポーネントにはここに記載のタイプが含まれる場合があります。このリストはすべてを網羅するものではなく、今後変更される可能性があります。

floor は建物の階数を示します。
establishment は通常、まだ分類されていない場所を示します。
landmark は、ナビゲーションを支援するために参照として使用される付近の場所を示します。
point_of_interest は名前のあるスポットを示します。
parking は、駐車場や立体駐車場を示します。
post_box は特定の郵便ポストを示します。
postal_town は、locality や sublocality など、一部の国で郵送先住所に使用される地域グループを示します。
room は建物の部屋を示します。
street_number は正確な番地を示します。
bus_station、train_station、transit_station は、バス、電車、または公共交通機関の停留所の場所を示します。

ビューポートのバイアス設定

ジオコーディングリクエストでは、（境界ボックスとして表現される）特定のビューポート内の結果を優先するようにジオコーディングサービスに指示できます。そのためには、リクエスト URL 内で bounds パラメータを設定します。

bounds パラメータは、パイプ文字（|）を使用してこの境界ボックスの南西と北東の角の緯度と経度の座標を定義します。

たとえば、「Washington」をジオコーディングすると、通常は米国ワシントン州が返されます。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

ただし、bounds 引数を追加して米国の北東部を囲む境界ボックスを定義すると、次のジオコーディングではワシントン D.C. 市が返されます。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

地域のバイアス

ジオコーディングリクエストで region パラメータを使用すると、ジオコーディングサービスに特定の地域を優先して結果を返すように指示できます。このパラメータは、地域のバイアスを指定する ccTLD（国コードトップレベルドメイン）引数を取ります。ほとんどの ccTLD コードは ISO 3166-1 コードと同じですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレートブリテンおよび北アイルランド連合王国」のエンティティ）です。

ジオコーディングの結果は、メインの Google マップアプリケーションが正式にリリースされているすべてのドメインに対してバイアスされる場合があります。バイアスで優先されるのは特定のドメインの結果のみです。このドメインの外により関連性の高い結果がある場合はそれらも含まれます。

たとえば、「Toledo」をジオコーディングすると、Geocoding API のデフォルトドメインが米国に設定されているため、次の結果が返されます。リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

region=es（スペイン）を指定して「Toledo」のジオコーディングリクエストを行うと、スペインの都市が返されます。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

コンポーネントのフィルタリング

Geocoding API は、ジオコーディングレスポンスで特定のエリアに限定した住所の結果を返すことがあります。制限は、components フィルタを使用して指定できます。フィルタは、パイプ（|）で区切られた component:value ペアのリストで構成されます。フィルタ値では、他のジオコーディングリクエストと同じスペル修正と部分一致がサポートされています。ジオコーダがコンポーネントフィルタと部分一致することが見つかった場合、レスポンスには partial_match フィールドが含まれます。

フィルタリングできる components は次のとおりです。

postal_code は postal_code および postal_code_prefix と一致します。
country は、国名、または 2 文字の ISO 3166-1 国コードを照合します。この API は ISO 標準に従って国を定義しているため、対応する ISO 国コードを使用するとフィルタリングが最適に機能します。
注: 国コードを指定して予期しない結果が返される場合は、指定したコードに、対象の国、従属地域、特別な地理的関心分野が含まれているかどうかを確認してください。コード情報は、Wikipedia: ISO 3166 国コードのリストまたは ISO オンラインブラウジングプラットフォームで確認できます。

次の components は結果に影響を与える可能性はありますが、適用されません。

route は、経路の正式名または略称を照合します。
locality は、locality 型と sublocality 型に一致します。
administrative_area は、すべての administrative_area レベルに一致します。

コンポーネントのフィルタリングに関する注意事項:

リクエストでこれらのコンポーネントフィルタを繰り返さないでください。繰り返さないと、API から Invalid_request: country、postal_code、route が返されます。
リクエストに繰り返しコンポーネントフィルタが含まれている場合、API はそれらのフィルタを OR ではなく AND として評価します。
結果は Google マップと一致しているため、予期しない ZERO_RESULTS レスポンスが返されることがあります。ユースケースによっては、Place Autocomplete を使用した方が良い結果が得られる場合もあります。詳しくは、こちらのよくある質問をご覧ください。
住所コンポーネントごとに、address パラメータまたは components フィルタのいずれかで指定します。両方は指定できません。両方で同じ値を指定すると、ZERO_RESULTS になる可能性があります。

components=country:GB を使用して「High St, Hastings」をジオコーディングすると、米国のヘイスティングスオンハドソンではなく、イングランドのヘイスティングスの結果が返されます。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

地域「Santa Cruz」を components=country:ES でジオコーディングすると、スペインのカナリア諸島の Santa Cruz de Tenerife が返されます。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

互いに除外するフィルタを指定した場合のみ、コンポーネントフィルタリングは ZERO_RESULTS レスポンスを返します。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

回答:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

components フィルタを使用すると、アドレスパラメータなしで有効なクエリを作成できます。（完全な住所をジオコーディングする際、リクエストに建物の名前と番号が含まれている場合は address パラメータが必要です）。

リクエスト:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

回答:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

ジオコーディングのリクエストとレスポンス

リクエスト

ジオコーディング（緯度と経度の検索）パラメータ

レスポンス

JSON

XML

ステータス コード

エラー メッセージ

結果

住所タイプと住所コンポーネント タイプ

ビューポートのバイアス設定

地域のバイアス

コンポーネントのフィルタリング

ステータスコード

エラーメッセージ

住所タイプと住所コンポーネントタイプ