ジオコーディングは、住所を地図上の地点に変換します。住所をジオコーディングすると、レスポンスに次の情報が含まれます。
ジオコード リクエスト
ジオコーディング リクエストは HTTP GET リクエストです。アドレスは、非構造化文字列として指定できます。
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
または、クエリ パラメータで表される住所コンポーネントの構造化されたセットとして指定します。
https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS
通常、構造化形式は HTML フォームで取得された住所コンポーネントを処理するときに使用します。
その他のパラメータはすべて、URL パラメータとして渡すか、API キーやフィールド マスクなどのパラメータの場合は、GET リクエストの一部としてヘッダーで渡します。
構造化されていない住所文字列を渡す
構造化されていない住所は、文字列または Plus Code としてフォーマットされた住所です。住所のジオコーディングでは、緯度と経度の座標や、住所や Plus Code を表さない他の構造化されていない文字列は解決されません。このような文字列を使用するリクエストはサポートされておらず、エラー レスポンスや未指定の動作につながる可能性があります。サポートされていないクエリの例を次に示します。
| クエリタイプ | 例 |
|---|---|
| 緯度と経度の座標。代わりにリバース ジオコーディングを使用してください。 | "37.422131,-122.084801" |
| 1 つのクエリに複数の場所、道路、都市の名前など、コンセプトや制約が多すぎる | 「マーケット ストリート サンフランシスコ サンノゼ空港」 |
| Google マップに表示されない住所の要素 |
「C/O John Smith 123 Main Street」 「P.O. Box 13 San Francisco」 |
| ビジネス、チェーン、カテゴリの名前と、それらのエンティティが利用できない場所の組み合わせ | 「テキサス州ダラスの Tesco」 |
| 複数の解釈が可能な曖昧なクエリ | 「充電器の返却」 |
| 使用されなくなった過去の名前 | "Middlesex United Kingdom" |
| 地理空間以外の要素または意図 | 「ベンチュラ ハーバーには何隻のボートがありますか？」 |
| 非公式な名前や虚栄心から付けられた名前 |
「ジェンガ」 「ヘルタースケルター」 |
たとえば、次の例では、URL エンコードされたアドレス文字列「1600 Amphitheatre Parkway, Mountain View, CA」を渡します。
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY
URL の「+」文字がスペースに変換されていることに注意してください。
curl コマンドを使用してリクエストを行うこともできます。
curl -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
住所には、さまざまな種類の特殊文字を含めることができます。たとえば、「7/1 King St, Concord West」の「/」などです。「/」を %2F として URL エンコードします。
https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
もう 1 つの一般的な例は、「9500 W Bryn Mawr Ave #650, Rosemont」のように「#」文字を使用することです。「#」を %2FE として URL エンコードします。
https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
次の例では、非構造化アドレス文字列をプラスコード 849VCWC8+R4 として指定します。「+」文字が %2B として URL エンコードされていることを確認します。
https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY
構造化された住所を渡す
構造化された住所を指定するには、address クエリ パラメータ（型: PostalAddress）を使用します。PostalAddress オブジェクトを使用すると、リクエスト内の住所コンポーネントの一部またはすべてを個々のクエリ パラメータとして指定できます。
たとえば、住所の郵便番号のみを指定するには、PostalAddress.postalCode を使用します。
https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY
HTML フォームでキャプチャされた住所コンポーネントなど、複数の住所コンポーネントを指定するには、複数のクエリ パラメータを使用します。
https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View &address.administrativeArea=CA &key=API_KEY
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.address— 順方向ジオコーディングでGeocodeAddressとのみ使用します。
また、すべての Geocoding API メソッドに一般的な https://www.googleapis.com/auth/cloud-platform スコープを使用することもできます。このスコープは、すべてのメソッドへのアクセスを許可する一般的なスコープであるため、開発時には便利ですが、本番環境では使用できません。
詳細と例については、OAuth を使用するをご覧ください。
ジオコード レスポンス
ジオコーディングは、GeocodeResult オブジェクトの results 配列を含む GeocodeAddressResponse オブジェクトを返します。各 GeocodeResult オブジェクトは 1 つの場所を表します。
Geocoding API のレスポンスには、GeocodeResult 内の次の 2 つの主要な場所に types 配列が含まれています。
GeocodeResult.types: この配列は、結果の全体的なタイプを示します。指定できる値は、場所タイプ（新版）ページの表 A と表 B に記載されています。GeocodeResult.addressComponents[].types: 各住所コンポーネントには、住所の特定の部分のタイプを示すtypes配列があります。これらの値は、[場所タイプ（新機能）] ページの住所タイプと住所コンポーネントのタイプの表から取得されます。
完全な JSON オブジェクトは次の形式です。
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "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" }, ... ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCWC8+R4", "compoundCode": "CWC8+R4 Mountain View, CA, USA" } } ] }
必須パラメータ
address- ジオコーディングする住所または Plus Code。注: 住所のジオコーディングでは、緯度と経度の座標、または住所や Plus Code を表さない他の構造化されていない文字列は解決されません。サポートされていないクエリの詳細と例については、非構造化アドレス文字列を渡すをご覧ください。対象国の郵便業務で使用されている形式で住所を指定します。店名、組織名、部屋番号、階数などの住所の追加要素は指定しないでください。番地の要素はスペースで区切り、URL エンコードして%20にします。たとえば、「24 Sussex Drive Ottawa ON」という住所を次のように渡します。24%20Sussex%20Drive%20Ottawa%20ON
%2Bに URL エンコードされ、スペースは%20に URL エンコードされます。- グローバル コードは、4 文字のエリアコードと 6 文字以上のローカルコードです。たとえば、「849VCWC8+R9」は
849VCWC8%2BR9としてエンコードされます。 - 複合コードは、明示的な場所を含む 6 文字以上のローカルコードです。たとえば、「CWC8+R9 Mountain View, CA, USA」は
CWC8%2BR9%20Mountain%20View%20CA%20USAとしてエンコードします。
- グローバル コードは、4 文字のエリアコードと 6 文字以上のローカルコードです。たとえば、「849VCWC8+R9」は
オプション パラメータ
locationBias
検索する領域を
Viewportとして指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺の結果（エリアの近くにあるがエリア外の結果を含む）が返される可能性があります。リージョンを矩形のビューポートとして指定します。長方形は、対角線上の 2 つの低点と高点として表される緯度経度のビューポートです。低点は長方形の南西の角を示し、高点は長方形の北東の角を示します。
ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の境界は -90 ～ 90 度（両端を含む）、経度の境界は -180 ～ 180 度（両端を含む）の範囲で指定する必要があります。
low=highの場合、ビューポートはその単一点で構成されます。low.longitude>high.longitudeの場合、経度の範囲は反転します（ビューポートが経度 180 度の線を越えます）。low.longitude= -180 度、high.longitude= 180 度の場合は、ビューポートにすべての経度が含まれます。low.longitude= 180 度、high.longitude= -180 度の場合、経度の範囲は空になります。low.latitude>high.latitudeの場合、緯度範囲は空です。
下限値と上限値の両方を入力する必要があります。また、表示されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。
たとえば、次のクエリ文字列は、ニューヨーク市を完全に囲むビューポートを定義します。
?locationBias.rectangle.low.latitude=40.477398
&locationBias.rectangle.low.longitude=-74.259087 &locationBias.rectangle.high.latitude=40.91618 &locationBias.rectangle.high.longitude=-73.70018 languageCode
結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
-
languageCodeが指定されていない場合、API はデフォルトでenになります。無効な言語コードを指定すると、API はINVALID_ARGUMENTエラーを返します。 - API は、ユーザーと地元住民の両方が読める番地を可能な限り提供します。この目標を達成するため、優先言語を考慮し、必要に応じてユーザーが読める文字に音訳して、現地の言語で住所を返します。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は最初のコンポーネントから選択されます。
- 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
- 優先言語は、API が返す結果のセットと、それらが返される順序にわずかな影響を与えます。ジオコーダは、言語によって略語の解釈が異なります。たとえば、通りの種類の略語や、ある言語では有効でも別の言語では有効でない同義語などです。
regionCode
2 文字の CLDR コード値で表される地域コード。デフォルト値はありません。ほとんどの CLDR コードは ISO 3166-1 コードと同一です。
住所のジオコーディング（フォワード ジオコーディング）を行う場合、このパラメータはサービスから返される結果に影響を与えますが、指定された地域に完全に制限するわけではありません。位置情報または場所のジオコーディング、リバース ジオコーディング、場所のジオコーディングを行う際に、このパラメータを使用して住所の形式を指定できます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響を与える可能性があります。
-
FieldMask
レスポンス フィールド マスクを作成して、レスポンスで返すフィールドを指定します。レスポンス フィールド マスクをメソッドに渡すには、URL パラメータ
$fieldsまたはfieldsを使用するか、HTTP ヘッダーX-Goog-FieldMaskを使用します。たとえば、次のリクエストはレスポンスのplaceIDフィールドのみを返します。curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
詳細については、返すフィールドの選択をご覧ください。
位置情報のバイアス
locationBias パラメータを使用して、ジオコーディング サービスに特定のビューポート（境界ボックスとして表現）内の結果を優先するように指示します。locationBias パラメータは、この境界ボックスの南西と北東の角の緯度と経度の座標を定義します。
たとえば、「ワシントン」という住所のジオコード リクエストでは、ワシントン D.C. と米国ワシントン州の結果が返されることがあります。
https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY
レスポンスの形式は次のとおりです。
{ "results": [ { "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "location": { "latitude": 38.9071923, "longitude": -77.0368707 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "bounds": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "formattedAddress": "Washington, DC, USA", "addressComponents": [ { "longText": "Washington", "shortText": "Washington", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "location": { "latitude": 47.7510741, "longitude": -120.7401386 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024945, "longitude": -116.91607109999998 } }, "bounds": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024442, "longitude": -116.91607109999998 } }, "formattedAddress": "Washington, USA", "addressComponents": [ { "longText": "Washington", "shortText": "WA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, ... ], "types": [ "administrative_area_level_1", "political" ] } ] }
ただし、locationBias パラメータを追加して米国北東部の境界ボックスを定義すると、このジオコードはワシントン D.C. のみを返します。
https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72 &locationBias.rectangle.high.latitude=43.39 &locationBias.rectangle.high.longitude=-65.90 &key=API_KEY
地域バイアス
ジオコーディング リクエストでは、regionCode パラメータを使用して、ジオコーディング サービスの結果で特定の地域を優先するように指定できます。このパラメータは、地域バイアスを指定する
2 文字の CLDR コードの値を受け取ります。ほとんどの CLDR コードは ISO 3166-1 コードと同一です。
regionCode にデフォルト値はありません。たとえば、「Toledo」をジオコーディングすると、米国とスペインの結果が返されます。
https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY
対応:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "location": { "latitude": 41.652805199999996, "longitude": -83.5378674 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "bounds": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "formattedAddress": "Toledo, OH, USA", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM", "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM", "location": { "latitude": 39.8628296, "longitude": -4.0273067 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "bounds": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "formattedAddress": "Toledo, España", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "administrative_area_level_4", "political" ], "languageCode": "es" }, ... ], "types": [ "administrative_area_level_4", "political" ] }, ... ] }
regionCode=es（スペイン）を指定して「Toledo」をジオコーディングすると、スペインの結果のみが返されます。
https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY