Nearby Search(新版)リクエストは 1 つ以上の場所タイプを受け取り、指定されたエリア内で一致する場所のリストを返します。1 つ以上のデータ型を指定するフィールド マスクが必要です。Nearby Search(新版)は POST リクエストのみをサポートしています。
API Explorer を使用すると、ライブ リクエストを発行できるため、API と API オプションについて理解を深めることができます。
試してみるインタラクティブなデモをお試しください。Nearby Search(新版)の結果を地図上に表示できます。
Nearby Search(新版)リクエスト
Nearby Search(新版)リクエストは、次の形式の URL に対する HTTP POST リクエストです。
https://places.googleapis.com/v1/places:searchNearby
すべてのパラメータを POST リクエストの一部として、JSON リクエスト本文またはヘッダーで渡します。次に例を示します。
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(新版)の回答
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.attributions
,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.primaryTypeDisplayName
,places.adrFormatAddress
, を含むplaces.primaryTypeDisplayName
, 、、、、 を含むplaces.name
places.subDestinations
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
, {2, , , , , /////places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
検索する地域を円として指定します。中心点と半径(メートル単位)で定義します。 半径は 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 個のタイプを指定できます。
場所には、関連付けられているタイプ Table A から 1 つのプライマリ タイプのみを指定できます。たとえば、プライマリ タイプは
"mexican_restaurant"
や"steak_house"
です。includedPrimaryTypes
とexcludedPrimaryTypes
を使用すると、場所のメインタイプに基づいて結果をフィルタリングできます。場所には、関連するタイプの Table A の複数のタイプ値を含めることもできます。たとえば、レストランのタイプは
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
です。includedTypes
とexcludedTypes
を使用して、場所に関連付けられたタイプのリストの結果をフィルタリングします。複数のタイプ制限を指定して検索を指定した場合は、すべての制限を満たす場所のみが返されます。たとえば
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
を指定した場合、返される場所は"restaurant"
関連のサービスを提供しますが、主に"steak_house"
として動作するわけではありません。includedTypes
Table A から検索する場所タイプのカンマ区切りのリスト。 このパラメータを省略すると、すべてのタイプの場所が返されます。
excludedTypes
検索から除外する Table A の場所タイプのカンマ区切りリスト。
リクエストで
includedTypes
("school"
など)とexcludedTypes
("primary_school"
など)の両方を指定した場合、レスポンスには"school"
に分類されるが"primary_school"
には分類されない場所が含まれます。レスポンスには、includedTypes
の少なくとも 1 つに一致し、excludedTypes
のいずれにも一致しない場所が含まれます。includedTypes
とexcludedTypes
の両方に指定されているタイプなど、競合するタイプがある場合は、INVALID_REQUEST
エラーが返されます。includedPrimaryTypes
検索に含める、Table A の主要な場所タイプのカンマ区切りのリスト。
excludedPrimaryTypes
検索から除外する Table 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(新版)の例
同じ種類の場所を検索する
次の例は、半径 500 m 以内(circle
で定義)内のすべてのレストランの表示名を Nearby Search(新版)リクエストする例を示しています。
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(新版)リクエストを示しています。
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
を追加して、レスポンスに各場所のタイプ情報が含まれるようにし、結果から適切な場所を選択しやすくしています。
検索から場所のタイプを除外する
次の例は、"primary_school"
タイプのすべての場所を除外し、"school"
タイプのすべての場所に対する Nearby Search(新版)リクエストを示しています。結果は距離に基づいてランク付けされます。
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(新版)リクエストを示しています。この例では、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] ウィンドウを展開します。