リクエスト
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 文字以上のローカルコードです(849VCW8+R9 は
849VCWC8%2BR9
)。 - 複合コードは、明示的な場所を含む 6 文字以上のローカルコードです(CWC8+R9 Mountain View, CA, USA は
CWC8%2BR9%20Mountain%20View%20CA%20USA
)。
--OR--
components
- 要素をパイプ(|
)で区切ったコンポーネント フィルタ。address
が指定されている場合は、コンポーネント フィルタも省略可能なパラメータとして受け入れられます。 コンポーネント フィルタの各要素はcomponent:value
ペアで構成され、ジオコーダからの結果を完全に制限します。詳しくは、後述のコンポーネントのフィルタリングをご覧ください。- グローバル コードは、4 文字のエリアコードと 6 文字以上のローカルコードです(849VCW8+R9 は
key
- アプリケーションの API キー。このキーでアプリケーションを識別し、割り当てを管理します。キーの取得方法をご確認ください。
詳細なガイダンスについては、よくある質問をご覧ください。
ジオコーディング リクエストのオプション パラメータ:
bounds
- ジオコーディングの結果に大きくバイアスをかけるビューポートの境界ボックス。このパラメータは、ジオコーダからの結果に影響を与えますが、完全に制限するわけではありません。(詳しくは、後述のビューポートのバイアス設定をご覧ください)。language
- 結果を返す言語。- サポートされている言語の一覧をご覧ください。サポート対象言語は頻繁に更新されるため、このリストがすべてを網羅しているとは限りません。
language
が指定されていない場合、ジオコーダは、Accept-Language
ヘッダーで指定された優先言語、またはリクエストの送信元ドメインの母国語の使用を試みます。- ジオコーダは、可能な限り、ユーザーとローカルの両方が判読できる番地を提供します。この目的を達成するために、番地を現地の言語で返し、必要に応じてユーザーが読み取れるスクリプトに文字変換し、希望の言語に従って処理します。その他の住所はすべて優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントから選択した同じ言語で返されます。
- 優先言語で名前を表示できない場合、ジオコーダは最も近い名前を使用します。
- 優先言語は、API が返す結果のセットや、それらが返される順序に小さい影響を及ぼします。ジオコーダでは、道路の種類を表す略語や、ある言語では有効でも別の言語では有効でない類義語など、言語によって略語の解釈が異なります。たとえば、utca と tér はハンガリー語でそれぞれ通りと正方形の同義語です。
region
- ccTLD(「トップレベル ドメイン」)の 2 文字の値として指定される地域コード。このパラメータは、ジオコーダからの結果に影響を与えますが、完全に制限するわけではありません。(詳しくは、後述の地域のバイアスをご覧ください)。このパラメータは、適用される法律に基づいて検索結果に影響する場合もあります。components
- 要素をパイプ(|
)で区切ったコンポーネント フィルタ。リクエストにaddress
が含まれていない場合、コンポーネント フィルタは必須です。コンポーネント フィルタの各要素はcomponent:value
ペアで構成され、ジオコーダからの結果を完全に制限します。詳しくは、後述のコンポーネントのフィルタリングをご覧ください。extra_computations
- このパラメータに指定できる値はADDRESS_DESCRIPTORS
のみです。詳細については、 アドレス記述子をご覧ください。
レスポンス
ジオコーディングのレスポンスは、URL リクエスト内の output
フラグで指定された形式、またはデフォルトの JSON 形式で返されます。
この例では、Geocoding API は、住所「1600 Amphitheatre Parkway, Mountain View, CA」に対するクエリに対する json
レスポンスをリクエストしています。
このリクエストでは、JSON output
フラグを使用しています。
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
このリクエストでは、XML の output
フラグを使用しています。
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "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>
にはリクエストに関するメタデータが含まれます。下記のステータス コードをご覧ください。- 任意の数の
<result>
要素。各要素には、ジオコーディングされた住所情報とジオメトリ情報のセットが 1 つ含まれます。
XML レスポンスは JSON レスポンスよりかなり長くなります。このため、サービスがなんらかの理由で xml
を必要とする場合を除き、優先出力フラグとして json
を使用することをおすすめします。また、XML ツリーを処理する場合は、適切なノードと要素を参照できるよう、注意が必要です。出力処理の推奨される設計パターンについては、
XPath による XML の解析をご覧ください。
- XML の結果はルートの
<GeocodeResponse>
要素でラップされます。 - JSON は複数の要素を含むエントリを複数配列(
types
)で表し、XML は複数の単数要素(<type>
)でこれらを示します。 - 空白要素は、JSON では空の配列によって示されますが、XML にはそのような要素が存在しないためです。たとえば、結果が生成されないレスポンスは、JSON では空の
results
配列を返しますが、XML では<result>
要素を返しません。
ステータス コード
Geocoding レスポンス オブジェクトの "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 個以上のタグのセットが含まれます。たとえば、「シカゴ」のジオコーディングでは、「シカゴ」が都市であることを示す「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 とプラスコードを参照)は、エンコードされた位置参照で、緯度と経度の座標から導出され、1/8, 000 度から 1/8, 000 度(赤道で約 14 m x 14 m)以下の面積を表します。Plus Codes は、住所が存在しない場所(建物に番号が付いていない場所や、通りに名前が付いていない場所)で、番地の代わりに使用できます。必ずしも Plus Codes を返すわけではありません。サービスが Plus Code を返す場合、そのサービスはグローバル コードと複合コードの形式になります。
global_code
は、4 文字のエリアコードと 6 文字以上のローカルコード(849VCWC8+R9)です。compound_code
は、明示的な場所(CWC8+R9、Mountain View, CA, USA)を含む 6 文字以上のローカルコードです。このコンテンツをプログラムで解析しないでください。
-
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 マップのメイン アプリケーションが正式にリリースされるすべてのドメインでバイアスがかかる可能性があります。なお、バイアスで優先されるのは特定のドメインの結果のみです。このドメインの外により関連性の高い結果がある場合はそれらも含まれる場合があります。
たとえば、Geocoding API のデフォルトのドメインは米国に設定されているため、「Toledo」をジオコーディングするとこの結果が返されます。リクエスト:
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®ion=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 国コードを使用するとフィルタリングが最適に動作します。
次の 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"
}
components=country:ES
を指定して「Santa Cruz」という地域区分のジオコーディング リクエストを行うと、スペインのカナリア諸島のサンタクルス デ テネリフェが返されます。
リクエスト:
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 パラメータを指定せずに有効なクエリを作成できます。(完全な住所をジオコーディングする際、リクエストに建物の名前と数が含まれている場合は 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"
}