Nearby Search(New)リクエストは 1 つ以上の場所のタイプを受け取り、指定した領域内で一致する場所のリストを返します。1 つ以上のデータ型を指定するフィールド マスクが必要です。Nearby Search(New)は POST リクエストのみに対応しています。
API Explorer を使用すると、ライブ リクエストを行って、API と API オプションについての理解を深めることができます。
試してみるインタラクティブなデモで、Nearby Search (New) の結果を地図上に表示してみましょう。
Nearby Search(新規)リクエスト
Nearby Search(新規)リクエストは、次の形式の URL に対する HTTP POST リクエストです。
https://places.googleapis.com/v1/places:searchNearby
すべてのパラメータを JSON リクエスト本文またはヘッダーで POST リクエストの一部として渡します。次に例を示します。
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Nearby Search(New)のレスポンス
Nearby Search(新機能)は、 JSON オブジェクトをレスポンスとして返します。レスポンスの説明:
places
配列には、一致するすべての場所が含まれます。- 配列内の各場所は
Place
オブジェクトで表されます。Place
オブジェクトには、1 つの場所に関する詳細情報が含まれます。 - リクエストで渡される FieldMask は、
Place
オブジェクトで返されるフィールドのリストを指定します。
完全な JSON オブジェクトの形式は次のとおりです。
{ "places": [ { object (Place) } ] }
必須パラメータ
-
FieldMask
レスポンス フィールド マスクを作成して、レスポンスで返すフィールドのリストを指定します。URL パラメータ
$fields
またはfields
を使用するか、HTTP ヘッダーX-Goog-FieldMask
を使用して、レスポンス フィールド マスクをメソッドに渡します。レスポンスには、返されるフィールドのデフォルト リストはありません。フィールド マスクを省略すると、メソッドはエラーを返します。フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計上の方法です。これにより、不要な処理時間と課金を回避できます。
返す場所データの種類をカンマ区切りのリストで指定します。たとえば、場所の表示名と住所を取得できます。
X-Goog-FieldMask: places.displayName,places.formattedAddress
すべてのフィールドを取得するには、
*
を使用します。X-Goog-FieldMask: *
以下のフィールドを 1 つ以上指定します。
次のフィールドによって Nearby Search(Basic)SKU がトリガーされます。
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
, {1/2}, {1/2}, {2/2} フィールド。places.name
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
場所の名前のテキストにアクセスするには、places.displayName
を使用します。以下のフィールドによって Nearby Search(Advanced)SKU がトリガーされます。
places.currentOpeningHours
、places.currentSecondaryOpeningHours
、places.internationalPhoneNumber
、places.nationalPhoneNumber
、places.priceLevel
、places.rating
、places.regularOpeningHours
、places.regularSecondaryOpeningHours
、places.userRatingCount
、places.websiteUri
以下のフィールドに基づいて Nearby Search(Preferred)SKU がトリガーされます。
places.allowsDogs
、places.curbsidePickup
、places.delivery
、places.dineIn
、places.editorialSummary
、places.evChargeOptions
、places.fuelOptions
、places.goodForChildren
、places.goodForGroups
、places.goodForWatchingSports
、places.liveMusic
、places.menuForChildren
、places.parkingOptions
、places.paymentOptions
、places.outdoorSeating
、places.reservable
、places.restroom
、places.reviews
、places.servesBeer
、places.servesBeer
、places.servesBeer
、places.servesBeer
、places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
検索対象の領域を円で指定し、中心点と半径(メートル単位)で定義します。radius は 0.0 ~ 50000.0 の範囲で指定する必要があります。デフォルトの radius は 0.0 です。リクエストでは 0.0 より大きい値に設定する必要があります。
次に例を示します。
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
省略可能なパラメータ
-
includeTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes
検索結果のフィルタリングに使用する Table A タイプのタイプのリストを指定できます。タイプ制限カテゴリごとに最大 50 タイプを指定できます。
1 つの場所には、テーブル A タイプのメインタイプを 1 つのみ関連付けることができます。たとえば、メインのタイプは
"mexican_restaurant"
や"steak_house"
です。includedPrimaryTypes
とexcludedPrimaryTypes
を使用して、場所のメインのタイプで結果をフィルタリングします。1 つの場所に、Table A タイプの複数のタイプの値が関連付けられている場合もあります。たとえば、レストランが
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
の各タイプを持つとします。includedTypes
とexcludedTypes
を使用して、場所に関連付けられているタイプのリストの結果をフィルタリングします。複数のタイプの制限を指定して検索を指定した場合は、すべての制限を満たす場所のみが返されます。たとえば、
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
を指定した場合、返される場所は"restaurant"
関連のサービスを提供しますが、主に"steak_house"
としては機能しません。includedTypes
検索する表 A の場所タイプのカンマ区切りのリスト。 このパラメータを省略すると、すべての型の桁数が返されます。
excludedTypes
検索から除外する表 A の場所タイプのカンマ区切りのリスト。
リクエストで
includedTypes
("school"
など)とexcludedTypes
("primary_school"
など)の両方を指定すると、レスポンスには"school"
に分類される場所が含まれますが、"primary_school"
に分類されない場所が含まれます。レスポンスには、includedTypes
の少なくとも 1 つに一致し、excludedTypes
ののいずれにも一致しない場所が含まれます。includedTypes
とexcludedTypes
の両方に型が競合するなど、競合する型がある場合は、INVALID_REQUEST
エラーが返されます。includedPrimaryTypes
検索に含める表 A の主要な場所タイプをカンマ区切りのリストで指定します。
excludedPrimaryTypes
検索から除外する表 A の主要な場所のタイプをカンマ区切りのリストで指定します。
includedPrimaryTypes
とexcludedPrimaryTypes
の両方に型が競合するなど、競合する型がある場合は、INVALID_ARGUMENT
エラーが返されます。 -
languageCode
結果を返す言語。
- サポートされている言語のリストをご覧ください。サポート対象の言語は頻繁に更新されるため、このリストがすべての言語を網羅しているとは限りません。
languageCode
が指定されていない場合、API はデフォルトでen
になります。無効な言語コードを指定すると、API からINVALID_ARGUMENT
エラーが返されます。- API は、ユーザーとローカルの両方のユーザーにとって判読可能な住所を提供するように最善を尽くします。この目標を達成するため、ローカル言語で番地を返し、必要に応じてユーザーが判読できるスクリプトに文字変換して、優先言語を監視します。その他の住所はすべて優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントから選択された同じ言語で返されます。
- 優先言語で名前を表示できない場合、API は最も近い言語を使用します。
- 優先言語は、API が返す結果のセットや、返される順序にわずかな影響を及ぼします。ジオコーダは、言語によって略語の解釈方法が異なります。たとえば、通りの略語や、ある言語では有効な同義語は別の言語では使用できない同義語などがこれに該当します。
-
maxResultCount
返されるプレイスの結果の最大数を指定します。1 ~ 20(デフォルト)の値にする必要があります。
-
rankPreference
使用するランキングのタイプ。このパラメータを省略すると、結果は人気順にランク付けされます。次のいずれかになります。
POPULARITY
(デフォルト): 検索結果を人気度に基づいて並べ替えます。DISTANCE
指定した場所からの距離に応じて結果を昇順で並べ替えます。
-
regionCode
レスポンスのフォーマットに使用するリージョン コード。 2 文字の CLDR コード値で指定します。デフォルト値はありません。
レスポンスの
formattedAddress
フィールドの国名がregionCode
と一致する場合、formattedAddress
から国コードが省略されます。このパラメータは、常に国名を含むadrFormatAddress
またはshortFormattedAddress
(国名が含まれない)では効果がありません。ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」(厳密には「グレート ブリテンおよび北アイルランド連合王国」の法人を意味します)です。パラメータは、適用される法律に基づいて結果に影響を与える可能性があります。
Nearby Search(New)の例
1 種類の場所を探す
次の例は、circle
によって定義された、半径 500 m 以内のすべてのレストランの表示名に対する Nearby Search(New)リクエストを示しています。
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
X-Goog-FieldMask
ヘッダーにより、レスポンスに places.displayName
のデータ フィールドが含まれることが指定されています。レスポンスは次の形式になります。
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
フィールド マスクにデータ型を追加して、追加情報を返します。たとえば、レスポンスにレストランの住所、種類、ウェブアドレスを含めるには、places.formattedAddress,places.types,places.websiteUri
を追加します。
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
レスポンスの形式は次のようになります。
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
複数のタイプの場所を検索する
次の例は、指定した circle
から半径 1,000 m 以内のすべてのコンビニエンス ストアと酒店の表示名を取得する Nearby Search(New)リクエストを示しています。
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyこの例では、フィールド マスクに
places.primaryType
と places.types
を追加しています。これにより、レスポンスに各場所のタイプ情報が含まれるようになり、結果から適切な場所を簡単に選択できるようになります。
場所のタイプを検索から除外する
次の例は、"school"
タイプのすべての場所("primary_school"
タイプの場所は除く)に対する Nearby Search(New)リクエストを示し、距離によって結果をランク付けしています。
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
地域付近にあるすべての場所を検索(距離順)
次の例は、サンフランシスコのダウンタウンのある地点の付近にある場所に対する Nearby Search(New)リクエストを示しています。この例では、rankPreference
パラメータを含めて、結果を距離別にランク付けしています。
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
試してみよう:
API Explorer では、API と API オプションに慣れるためにサンプル リクエストを行うことができます。
- ページの右側にある API アイコン を選択します。
- 必要に応じて、[標準パラメータを表示] を展開し、
fields
パラメータをフィールド マスクに設定します。 - 必要に応じて、[Request body] を編集します。
- [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
[API Explorer] パネルで展開アイコン を選択して、[API Explorer] ウィンドウを展開します。