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

Nearby Search（新規）

プラットフォームを選択: Android iOS JavaScript ウェブサービス

欧州経済領域（EEA）のデベロッパー

はじめに

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

すべてのパラメータを 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（新版）のレスポンス

Nearby Search（新版）は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:

places 配列には、一致するすべての場所が含まれます。
配列内の各場所は、Place オブジェクトで表されます。Place オブジェクトには、単一の場所に関する詳細情報が含まれます。
リクエストで渡される 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 Pro SKU をトリガーします。
  
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.attributions
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.id
  places.location
  places.name^**
  places.movedPlace
  places.movedPlaceId
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* アドレス記述子は、インドのお客様には一般提供されていますが、他の地域では試験運用中です。
  
  ^** places.name フィールドには、places/PLACE_ID の形式で場所のリソース名が含まれています。places.displayName を使用して、場所のテキスト名にアクセスします。
- 次のフィールドは、Nearby Search Enterprise SKU をトリガーします。
  
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.userRatingCount
  places.websiteUri
- 次のフィールドは、Nearby Search Enterprise + Atmosphere SKU をトリガーします。
  
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  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 の範囲で指定する必要があります。デフォルトの半径は 0.0 です。リクエストで 0.0 より大きい値に設定する必要があります。

次に例を示します。
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

オプションパラメータ

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

検索結果のフィルタリングに使用されるタイプ表 A のタイプの一覧を指定できます。各型制限カテゴリで指定できる型は最大 50 個です。

注: 表 B の値はレスポンスでのみ返されます。テーブル B の値をフィルタとして使用することはできません。
1 つの場所に関連付けることができるプライマリタイプは、表 A のタイプから 1 つのみです。たとえば、プライマリタイプは "mexican_restaurant" または "steak_house" になります。includedPrimaryTypes と excludedPrimaryTypes を使用して、場所のメインタイプで結果をフィルタします。

場所には、テーブル A のタイプから複数のタイプ値を関連付けることもできます。たとえば、レストランには "seafood_restaurant"、"restaurant"、"food"、"point_of_interest"、"establishment" などのタイプがあります。includedTypes と excludedTypes を使用して、場所に関連付けられたタイプのリストで結果をフィルタします。

"restaurant" や "hotel" などの一般的なプライマリタイプを指定すると、レスポンスには、指定したタイプよりも具体的なプライマリタイプを持つ場所が含まれることがあります。たとえば、"restaurant" のプライマリタイプを含めるように指定します。レスポンスには、プライマリタイプが "restaurant" の場所を含めることができますが、"chinese_restaurant" や "seafood_restaurant" などのより具体的なプライマリタイプの場所を含めることもできます。

複数のタイプの制限を指定して検索した場合、すべての制限を満たす場所のみが返されます。たとえば、{"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（新規）の例

特定の種類の場所を探す

次の例は、circle で定義された半径 500 メートル以内のすべてのレストランの表示名を取得する 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 メートル以内のすべてのコンビニエンスストアと酒屋の表示名を取得する 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 を追加して、レスポンスに各場所のタイプ情報を含めることで、結果から適切な場所を選択しやすくしています。

検索から場所のタイプを除外する

次の例は、"school" タイプのすべての場所を検索し、"primary_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

住所記述子を取得する

住所記述子は、近くのランドマークや含まれるエリアなど、場所の位置に関する関係情報を提供します。

注: 住所記述子は、インドのお客様には一般提供されていますが、その他の地域では試験運用中です。フィールドマスクで addressDescriptor のみを使用する Places API リクエストは、SKU: Places API Nearby Search Pro で課金されます。

次の例は、サンノゼのショッピングモール近くの場所に対する Nearby Search（新）リクエストを示しています。この例では、フィールドマスクに addressDescriptors を含めます。

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

レスポンスには、リクエストで指定された場所、近くのランドマークのリストとその場所からの距離、エリアのリストとその場所との包含関係が含まれます。

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

試してみよう:

API Explorer を使用すると、サンプルリクエストを作成して、API と API オプションを理解できます。

ページの右側にある API アイコン api を選択します。
必要に応じてリクエストパラメータを編集します。
[Execute] ボタンを選択します。ダイアログで、リクエストに使用するアカウントを選択します。
API Explorer パネルで、全画面アイコン fullscreen を選択して API Explorer ウィンドウを拡大します。

Nearby Search（新規） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

はじめに

Nearby Search（新規）リクエスト

Nearby Search（新版）のレスポンス

必須パラメータ

FieldMask

locationRestriction

オプション パラメータ

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode