Destination は、ユーザーが到達または移動しようとしている重要なスポットまたは特定の場所を指します。Destination には、ナビゲーション ポイント、ランドマーク、入り口、建物の輪郭などの情報を含めることができます。
Geocoding API の SearchDestinations エンドポイントを使用すると、住所、プレイス ID、緯度と経度の座標など、さまざまな入力条件に基づいて、さまざまなデスティネーションに関する詳細情報を取得できます。
送信先検索リクエスト
検索候補リクエストは、次の形式の URL への HTTP POST リクエストです。
https://geocode.googleapis.com/v4beta/geocode/destinations
すべてのパラメータを JSON リクエスト本文またはヘッダーで POST リクエストの一部として渡します。次に例を示します。
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations
目的地を検索する場所は、次の 3 つの方法のいずれかで指定できます。
- 住所
- プレイス ID
- 緯度と経度の座標
住所で目的地を検索する
アドレスは非構造化文字列として指定できます。住所ジオコーディングでは、緯度と経度の座標や、住所を表さない他の構造化されていない文字列は解決されません。このような文字列を使用するリクエストはサポートされておらず、エラー レスポンスや未指定の動作につながる可能性があります。サポートされていないクエリの例を次に示します。
| クエリタイプ | 例 |
|---|---|
| 緯度と経度の座標。代わりに位置情報クエリを使用してください。 | "37.422131,-122.084801" |
| 1 つのクエリに複数の場所、道路、都市の名前など、コンセプトや制約が多すぎる | 「マーケット ストリート サンフランシスコ サンノゼ空港」 |
| Google マップに表示されない住所の要素 |
「C/O John Smith 123 Main Street」 「P.O. Box 13 San Francisco」 |
| ビジネス、チェーン、カテゴリの名前と、それらのエンティティが利用できない場所の組み合わせ | 「テキサス州ダラスの Tesco」 |
| 複数の解釈が可能な曖昧なクエリ | 「充電器の返却」 |
| 使用されなくなった過去の名前 | "Middlesex United Kingdom" |
| 地理空間以外の要素またはインテント | 「ベンチュラ ハーバーには何隻のボートがありますか？」 |
| 非公式な名前や虚栄心から付けられた名前 |
「ジェンガ」 「ヘルタースケルター」 |
| 大規模な政治的エンティティ（都市、州、国） |
"New York City" "California" "USA" |
| 特定の住所のないルート |
"1st Ave., NYC, NY" "I-95" |
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations
または postalAddress として:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations
通常、postalAddress 形式は、HTML フォームで取得した住所コンポーネントを処理するときに使用します。
プレイス ID で目的地を検索する
プレイス ID を指定して、目的地を取得できます。
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations
サポートされているプレイス ID
検索候補のエンドポイントは、特定の移動可能な目的地を表すプレイス ID で最も効果を発揮します。
通常、establishment、point_of_interest、premise、street_address、subpremise などのタイプのプレイス ID はサポートされています。
番地範囲（「10-20 Main St」など）、特定の番号のないルートの区間、Plus Codes など、個別の場所を表さないプレイス ID はサポートされていません。
Place Autocomplete を使用してプレイス ID を検索する際の互換性を確保するには、タイプで結果をフィルタすることを検討してください。Autocomplete リクエストで includedPrimaryTypes パラメータを使用すると、上記のサポートされているタイプのみを含めることができます。
"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]
これにより、Place Autocomplete から返される Place ID が Search Destinations メソッドと最も互換性のあるものになります。establishment 型は広範囲に及ぶことに注意してください。このフィルタは、多くのビジネスの所在地をキャプチャするために必要ですが、検索の目的地でサポートが限定されている natural_feature タイプのプレイス オートコンプリートの結果も含まれる可能性があります。
場所で目的地を検索する
緯度と経度の座標を指定して目的地を検索できます。
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations
OAuth を使用してリクエストを行う
Geocoding API v4 は、認証に OAuth 2.0 をサポートしています。Geocoding API で OAuth を使用するには、OAuth トークンに正しいスコープが割り当てられている必要があります。ジオコーディング API は、目的地エンドポイントで使用する次のスコープをサポートしています。
https://www.googleapis.com/auth/maps-platform.geocode— すべての Geocoding API エンドポイントで使用します。
また、すべての Geocoding API エンドポイントに一般的な https://www.googleapis.com/auth/cloud-platform スコープを使用することもできます。このスコープは、すべてのエンドポイントへのアクセスを許可する一般的なスコープであるため、開発時には便利ですが、本番環境では使用できません。
詳細と例については、OAuth を使用するをご覧ください。
送信先検索のレスポンス
Search Destinations レスポンスは、場所に関するリッチでハイパーローカルなコンテキストを提供します。
このセクションでは、主なレスポンス フィールドについて説明します。すべてのレスポンス フィールドの詳細については、API リファレンスをご覧ください。
primary
リクエスト内のクエリで特定されたメインの場所。
containingPlaces
メインの目的地が属するより大きなエンティティ（店舗が入っているショッピング モールなど）。
subDestinations
主な目的地内のより具体的な場所（建物内のアパートなど）。
entrances
entrances[] 配列内のオブジェクトには次のフィールドがあります。
location場所への出入り口の位置を定義する単一の緯度/経度座標ペア。
entrance_tags[]入り口の特徴を説明する入り口タグの配列。次の値を使用できます。
"PREFERRED"この入り口から、返された場所に物理的にアクセスできる可能性が高いことを示します。1 つのスポットに複数の推奨入り口を設定できます。このタグがない入り口は、物理的には同じ建物にあるものの、必ずしもその場所へのアクセスを提供しているとは限りません。
たとえば、返された場所が商店街のレストランの場合、
"PREFERRED"の入り口はレストラン自体につながる入り口になり、返された他の入り口は、商店街の他のレストランの入り口など、建物の他の入り口になります。返された場所が建物自体である場合、
"PREFERRED"の入り口は建物の「メイン」部分につながる入り口になります。たとえば、ショッピング センターでは、メインのホワイエ エリアにアクセスできる入り口が"PREFERRED"の入り口になります。ただし、建物の側面にある店舗にのみアクセスできる入り口は、"PREFERRED"の入り口にはなりません。
structureType
この場所が表す構造物のタイプ。
POINTポイントの場所。
SECTION建物のサブセクション。
BUILDING建物。
GROUNDS通常、大学のキャンパス、アパートの複合施設、ショッピング モールなど、複数の建物を含む広いエリア。
navigationPoints
ジオコーディング レスポンス内の navigationPoints フィールドには、場所への移動に役立つポイントのリストが含まれています。具体的には、場所から道路網を介して経路を設定する場合、または場所へ道路網を介して経路を設定する場合の始点または終点として使用する必要があります。各ナビゲーション ポイントには次の値が含まれます。
navigationPointTokenは、navigationPointsフィールドにコンテキスト情報を含むトークンです。このトークンをルーティング API とナビゲーション API に送信して、アプリのルーティングと川の体験を改善できます。詳しくは、ナビゲーション ポイント トークンを使用したルート設定をご覧ください。locationには、ナビゲーション ポイントの緯度と経度の値が含まれます。この位置は常に道路網のすぐ近くにあり、場所へのナビゲーションの理想的な出発点または到着点となります。このポイントは、場所がある道路の側を明確に示すため、道路の中心線から意図的にわずかにオフセットされています。travelModesは、ナビゲーション ポイントにアクセスできる交通手段のリストです。"DRIVE"は、運転ルートに対応する交通手段です。"WALK"は、徒歩経路に対応する交通手段です。
usagesは、ナビゲーション ポイントでサポートされている使用状況のリストです。使用方法は次のとおりです。"DROPOFF""PICKUP""PARKING"
arrivalSummary
AI を活用した分析情報で到着をサポートします。AI を活用した要約をご覧ください。
landmarks
ユーザーが目的地の周辺を把握するのに役立つ、付近の有名な場所。
回答の形式
SearchDestinations は、次の JSON 形式の SearchDestinationsResponse を返します。
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "meal_takeaway", "food_delivery", "american_restaurant", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 61.182193756103516, "travelDistanceMeters": 63.075645446777344 }, { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "butcher_shop", "florist", "deli", "supermarket", "bakery", "food_delivery", "market", "manufacturer", "food_store", "store", "food", "service", "point_of_interest", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "tags": [ "ARRIVAL", "ADDRESS" ], "straightLineDistanceMeters": 158.65606689453125, "travelDistanceMeters": 131.1669921875 }, { "place": { "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk", "displayName": { "text": "Oil Changers", "languageCode": "en" }, "types": [ "car_repair", "service", "point_of_interest", "establishment" ], "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1240 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743054, "longitude": -122.0584272 } }, "relationalDescription": { "text": "Down the road from Oil Changers", "languageCode": "en" }, "tags": [ "ARRIVAL" ], "straightLineDistanceMeters": 140.52459716796875, "travelDistanceMeters": 143.24220275878906 }, { "place": { "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0", "displayName": { "text": "Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "cake_shop", "supermarket", "asian_grocery_store", "indian_restaurant", "meal_takeaway", "bakery", "manufacturer", "wholesaler", "restaurant", "food_store", "store", "food", "point_of_interest", "establishment" ], "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1056", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1111 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3737199, "longitude": -122.0522958 } }, "relationalDescription": { "text": "Near Apni Mandi Farmers Market Sunnyvale", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 410.37435913085938, "travelDistanceMeters": 479.49893188476562 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "primaryType": "chicken_restaurant", "types": [ "chicken_restaurant", "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ], "type": "Polygon" } }, "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "tags": [ "ADDRESS" ], "straightLineDistanceMeters": 87.348007202148438, "travelDistanceMeters": 214.08084106445312 } ], "entrances": [ { "location": { "latitude": 37.3735328, "longitude": -122.05694879999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4", "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "PARKING" ] } ] } ] }
必須パラメータ
- API リクエストには、次の 3 つのパラメータのいずれかを含める必要があります。これらのパラメータは、目的地の検索対象となる住所、場所、位置を指定します。
addressQuery- 検索するアドレス。place- 検索する場所のプレイス ID。locationQuery- 検索する場所の緯度と経度の座標。
FieldMask
レスポンス フィールド マスクを作成して、レスポンスで返すフィールドのリストを指定します。レスポンス フィールド マスクをメソッドに渡すには、URL パラメータ
$fieldsまたはfieldsを使用するか、HTTP ヘッダーX-Goog-FieldMaskを使用します。たとえば、次のリクエストでは、メインの目的地の入り口、ナビゲーション ポイント、場所 ID のみが返されます。curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \ -H "X-Goog-Api-Key: API_KEY" \ -H "Content-Type: application/json" \ -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \ https://geocode.googleapis.com/v4beta/geocode/destinationsレスポンスで返されるフィールドのデフォルト リストはありません。フィールド マスクを省略すると、メソッドはエラーを返します。すべてのフィールドを返すには、フィールド マスクを
*に設定します。詳細については、返すフィールドの選択をご覧ください。
オプション パラメータ
-
travelModes
返す
navigationPointsのタイプを指定します。他の移動手段のナビゲーション ポイントは除外されます。travelModesが設定されていない場合、すべての交通手段のナビゲーション ポイントを返すことができます。 languageCode
結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
-
languageCodeが指定されていない場合、API はデフォルトでenになります。無効な言語コードを指定すると、API はINVALID_ARGUMENTエラーを返します。 - API は、ユーザーと地元住民の両方が読める番地を可能な限り提供します。この目標を達成するため、優先言語を考慮し、必要に応じてユーザーが読める文字に音訳して、現地の言語で住所を返します。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は最初のコンポーネントから選択されます。
- 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
- 優先言語は、API が返す結果のセットと、それらが返される順序にわずかな影響を与えます。ジオコーダは、言語によって略語の解釈が異なります。たとえば、通りの種類の略語や、ある言語では有効でも別の言語では有効でない同義語などです。
regionCode
2 文字の CLDR コード値で表される地域コード。デフォルト値はありません。ほとんどの CLDR コードは ISO 3166-1 コードと同一です。
住所のジオコーディング（フォワード ジオコーディング）を行う場合、このパラメータはサービスから返される結果に影響を与えますが、指定された地域に完全に制限するわけではありません。位置情報または場所のジオコーディング、リバース ジオコーディング、場所のジオコーディングを行う際に、このパラメータを使用して住所の形式を指定できます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響を与える可能性があります。
-
placeFilter
locationQuery検索の結果をフィルタして、建物のみ、住所が明確な場所のみを返すなど、要件を満たすことができます。構造の粒度でフィルタする
structureTypeフィルタを使用すると、クエリによって返される構造体の種類を指定できます。- 建物を分離する:
"structureType": "BUILDING"を使用して、地図上に建物の輪郭を表示したり、特定の構造物の詳細を取得したりできます。 - 複合体の理解:
"structureType": "GROUNDS"を使用して、主な結果が全体的な根拠であることを確認します。これは、大学のキャンパスやショッピング モールなどの広いエリアをクエリする場合に便利です。 - ユニット/セクションに焦点を当てる:
"structureType": "SECTION"を使用して、建物内のセクションを特定します。
有用なアドレスを確保する
すべての場所に明確な番地レベルの住所があるわけではありません。
addressabilityフィルタを使用すると、結果のアドレスの品質を管理できます。- 明確なメインの住所を必須にする: メインの検索結果に常に通りの住所または名前が表示されるようにするには、
"addressability": "PRIMARY"を使用します。これは、明確な住所が重要なナビゲーションや表示の目的に役立ちます。 - サブデスティネーションでの住所の許可: メインの場所には住所がないが、その中のユニットには住所がある場合（建物内のアパートなど）、
"addressability": "WEAK"は、メインの場所またはそのサブデスティネーションのいずれかに住所があることを確認します。 - 任意の結果: アドレスの存在がユースケースに関係ない場合は、
"addressability": "ANY"を使用します。
例: 住所のある建物をフィルタする
curl -X POST -d '{ "locationQuery": { "location": { "latitude": 37.37348780, "longitude": -122.05678064 }, "placeFilter": { "structureType": "BUILDING", "addressability": "PRIMARY" } }, "languageCode": "en" }' \\ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\ -H "X-Goog-FieldMask: place" \\ https://geocode.googleapis.com/v4beta/geocode/destinations - 建物を分離する:
フィードバック
これは Geocoding API の試験運用版のエンドポイントです。フィードバックは geocoding-feedback-channel@google.com までお寄せください。