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 はサポートされています。
個別の場所を表さないプレイス ID（住所の範囲から推測されるもの（「10-20 Main St」など）、特定の番号のないルートの区間、Plus Codes など）はサポートされていません。
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 を使用するをご覧ください。
送信先検索のレスポンス
場所に関するハイパーローカルなコンテキスト
検索候補のレスポンスは、場所に関するリッチでハイパーローカルなコンテキストを提供します。主なフィールドは次のとおりです。
primary: リクエスト内のクエリで特定されたメインの場所。containingPlaces: メインの目的地が属するより大きなエンティティ（店舗を含むショッピング モールなど）。subDestinations: 主な目的地内のより具体的な場所（建物内のアパートなど）。entrances: 目的地の特定の出入り口。navigationPoints: ナビゲーションの終了に適した道路近くの場所。arrivalSummary: 到着をサポートする AI を活用した分析情報。AI を活用した要約をご覧ください。landmarks: ユーザーが目的地の周辺を把握するのに役立つ、付近の注目すべき場所。
すべてのレスポンス フィールドの詳細については、API リファレンスをご覧ください。
回答の形式
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", "american_restaurant", "meal_takeaway", "restaurant", "food_store", "food", "point_of_interest", "store", "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":}, "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.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 ] ] ] }} ], "landmarks":{ ... }
{ "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 ] ] ] }, "entrances": [ { "location": { "latitude": 37.373531299999996, "longitude": -122.05694519999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "UNKNOWN" ] } ] } ] }[ ... ]
[ { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "florist", "butcher_shop", "deli", "bakery", "food_delivery", "supermarket", "market", "food_store", "food", "point_of_interest", "store", "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 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "straightLineDistanceMeters": 158.65607, "travelDistanceMeters": 131.16699 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "types": [ "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":}, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "straightLineDistanceMeters": 87.34801, "travelDistanceMeters": 214.08084 }, { "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 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "straightLineDistanceMeters": 61.182194, "travelDistanceMeters": 63.075645 }, { "place": { "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk", "displayName": { "text": "Madras Café", "languageCode": "en" }, "primaryType": "indian_restaurant", "types": [ "indian_restaurant", "coffee_shop", "cafe", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1026", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1177 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743, "longitude": -122.0549333 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Madras Café", "languageCode": "en" }, "straightLineDistanceMeters": 204.45102, "travelDistanceMeters": 235.12041 } ]{ ... }
{ "type": "Polygon", "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ] }
必須パラメータ
- API リクエストには、次の 3 つのパラメータのうちの 1 つが含まれている必要があります。このパラメータは、目的地の検索対象となる住所、場所、位置を指定します。
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"は、メインの場所またはそのサブデスティネーションのいずれかに住所があることを確認します。 - Any Result: ユースケースでアドレスの存在が重要でない場合は、
"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 までお寄せください。