ジオコーディングは、住所を地図上の地点に変換します。住所をジオコーディングすると、レスポンスに次の情報が含まれます。
ジオコード リクエスト
ジオコーディング リクエストは HTTP GET リクエストです。アドレスは、非構造化文字列として指定できます。
https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING
または、クエリ パラメータで表される住所コンポーネントの構造化されたセットとして:
https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS
通常、構造化形式は HTML フォームで取得した住所コンポーネントを処理する場合に使用します。
その他のパラメータはすべて、URL パラメータとして渡すか、API キーやフィールド マスクなどのパラメータの場合は、GET リクエストの一部としてヘッダーで渡します。
構造化されていない住所文字列を渡す
非構造化住所とは、文字列または Plus Code としてフォーマットされた住所です。たとえば、次の例では、URL エンコードされた住所文字列「1600 Amphitheatre Parkway, Mountain View, CA」を渡します。
https://geocode.googleapis.com/v4beta/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/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
住所には、さまざまな種類の特殊文字を含めることができます。たとえば、「7/1 King St, Concord West」の「/」などです。「/」を %2F として URL エンコードします。
https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
一般的な例としては、「9500 W Bryn Mawr Ave #650, Rosemont」のように「#」文字を使用するケースがあります。「#」を %2FE として URL エンコードします。
https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
次の例では、非構造化アドレス文字列をプラスコード 849VCWC8+R4 として指定します。「+」文字が %2B として URL エンコードされていることを確認します。
https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY
構造化された住所を渡す
構造化された住所を指定するには、address クエリ パラメータ（型: PostalAddress）を使用します。PostalAddress オブジェクトを使用すると、リクエスト内の住所コンポーネントの一部またはすべてを個々のクエリ パラメータとして指定できます。
たとえば、住所の郵便番号のみを指定するには、PostalAddress.postalCode を使用します。
https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY
HTML フォームでキャプチャされた住所コンポーネントなど、複数の住所コンポーネントを指定するには、複数のクエリ パラメータを使用します。
https://geocode.googleapis.com/v4beta/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 つの場所を表します。
完全な 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。対象国の郵便業務で使用されている形式で住所を指定します。店名、組織名、部屋番号、階数などの住所要素は指定しないでください。番地の要素はスペースで区切り、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 コードと同一です。
住所のジオコーディング（順方向ジオコーディング）を行う場合、このパラメータは、サービスから返される結果を特定の地域に制限するものではありませんが、その地域を優先して結果を返すように影響を与えることができます。位置情報または場所のジオコーディング、リバース ジオコーディング、場所のジオコーディングを行う際に、このパラメータを使用して住所の形式を指定できます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響を与える可能性があります。
位置情報のバイアス
locationBias パラメータを使用して、ジオコーディング サービスに特定のビューポート（境界ボックスとして表現）内の結果を優先するように指示します。locationBias パラメータは、この境界ボックスの南西と北東の角の緯度と経度の座標を定義します。
たとえば、「Washington」という住所のジオコード リクエストでは、ワシントン D.C. と米国ワシントン州の結果が返されることがあります。
https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/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/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY