このページは Cloud Translation API によって翻訳されました。

Nearby Search（新規）

Nearby Search（New）リクエストは 1 つ以上の場所のタイプを受け取り、指定した領域内で一致する場所のリストを返します。1 つ以上のデータ型を指定するフィールドマスクが必要です。Nearby Search（New）は POST リクエストのみに対応しています。

API Explorer を使用すると、ライブリクエストを行って、API と API オプションについての理解を深めることができます。

試してみる

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: *
```
ワイルドカード「*」を使用すると、すべてのフィールドが選択されます。ただし、開発ではワイルドカードを使用できますが、本番環境で返されるデータの量が大量であるため、ワイルドカード（*）レスポンスフィールドマスクの使用はおすすめしません。
places.iconMaskBaseUri と places.iconBackgroundColor の使用方法について詳しくは、場所アイコンのセクションをご覧ください。

以下のフィールドを 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.nameplaces.typesplaces.utcOffsetMinutesplaces.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.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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 タイプを指定できます。

注: 表 B の値はレスポンスでのみ返されます。表 B の値はフィルタとして使用できません。
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、excludedTypes、includedPrimaryTypes、excludedPrimaryTypes を省略すると、検索制限の境界内にあるすべてのタイプの場所が返されます。
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] ウィンドウを展開します。

Nearby Search（新規）

Nearby Search（新規）リクエスト

Nearby Search（New）のレスポンス

必須パラメータ

FieldMask

locationRestriction

省略可能なパラメータ

includeTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode