此页面由 Cloud Translation API 翻译。

附近搜索（新）

请选择平台： Android iOS JavaScript 网络服务

附近搜索（新）请求可采用一个或多个地点类型，并返回指定区域内匹配地点的列表。必须提供一个字段掩码来指定一个或多个数据类型。附近地点搜索（新）仅支持 POST 请求。

借助 API Explorer，您可以发出实时请求，以便熟悉 API 和 API 选项：

试用交互式演示版，在地图上查看“附近搜索（新）”结果。

“附近搜索（新）”请求

附近地点搜索（新）请求是对以下格式的网址的 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

“附近搜索（新）”响应

“附近搜索”（新）会以 JSON 对象的形式返回响应。在回复中：

places 数组包含所有匹配的地点。
数组中的每个地点都由一个 Place 对象表示。Place 对象包含有关单个地点的详细信息。
请求中传递的 FieldMask 指定了 Place 对象中返回的字段列表。

完整 JSON 对象的格式如下：

{
  "places": [
    {
      object (Place)
    }
  ]
}

必需参数

FieldMask

通过创建响应字段掩码，指定要在响应中返回的字段列表。使用网址参数 $fields 或 fields，或使用 HTTP 标头 X-Goog-FieldMask 将响应字段掩码传递给该方法。响应中没有返回字段的默认列表。如果您省略字段掩码，该方法会返回错误。

字段遮盖是一种良好的设计做法，可确保您不会请求不必要的数据，这有助于避免产生不必要的处理时间和结算费用。

以逗号分隔列表的形式指定要返回的地点数据类型。例如，检索地点的显示名称和地址。
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
注意： 字段列表中的任何位置都不允许出现空格。

使用 * 可以检索所有字段。
```
X-Goog-FieldMask: *
```
通配符“*”会选择所有字段。不过，虽然该通配符在开发环境中可以使用，但 Google 不建议在生产环境中使用通配符 (*) 响应字段掩码，因为系统可能会返回大量数据。

如需有关使用 places.iconMaskBaseUri 和 places.iconBackgroundColor 的进一步指导，请参阅地点图标部分。

指定以下一个或多个字段：
- 以下字段会触发附近搜索（基本）SKU：
  
  places.accessibilityOptions、places.addressComponents、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.photos、places.plusCode、places.primaryType、places.primaryTypeDisplayName、places.pureServiceAreaBusiness、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、places.viewport
  
  ^*places.googleMapsLinks 字段处于正式发布前预览阶段，在预览期间使用不收费，也就是说，结算金额为 0 美元。
  
  ^** places.name 字段包含地点资源名称，格式为：places/PLACE_ID。使用 places.displayName 访问地点的文本名称。
- 以下字段会触发附近搜索（高级）SKU：
  
  places.currentOpeningHours、places.currentSecondaryOpeningHours、places.internationalPhoneNumber、places.nationalPhoneNumber、places.priceLevel、places.priceRange、places.rating、places.regularOpeningHours、places.regularSecondaryOpeningHours、places.userRatingCount、places.websiteUri
- 以下字段会触发附近搜索（首选）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.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 中的值用作过滤条件。

地点只能具有与其关联的表格 A 中一种主要类型。例如，主要类型可能是 "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 中的至少一个项匹配且与 excludedTypes 中的任何项都不匹配的地点。

如果存在任何冲突的类型（例如同时出现在 includedTypes 和 excludedTypes 中的类型），系统会返回 INVALID_REQUEST 错误。

includedPrimaryTypes

表 A 中要包含在搜索中的主地点类型的英文逗号分隔列表。

excludedPrimaryTypes

要从搜索中排除的表 A 中的主要地点类型的逗号分隔列表。

如果存在任何冲突的主要类型（例如同时出现在 includedPrimaryTypes 和 excludedPrimaryTypes 中的类型），系统会返回 INVALID_ARGUMENT 错误。
languageCode

返回结果时使用的语言。
- 请参阅支持的语言列表。Google 会经常更新支持的语言，因此此列表可能并不详尽。
- 如果未提供 languageCode，则 API 默认为 en。如果您指定的语言代码无效，该 API 会返回 INVALID_ARGUMENT 错误。
- API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标，它会以当地语言返回街道地址，然后在必要时按照首选语言将其直译为用户能看懂的文字。所有其他地址均以首选语言返回。地址部分均以同一语言返回，该语言是从第一个组成部分选择的语言。
- 如果名称在首选语言中没有对应项，API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及结果的返回顺序影响较小。地理编码器对缩写词的解读因语言而异，例如街道类型的缩写词，或者在一种语言中有效但在其他语言中无效的同义词。
maxResultCount

指定要返回的地点结果的数量上限。必须介于 1 到 20（默认值）之间。
rankPreference

要使用的排名类型。如果省略此参数，则结果会按热门程度排序。可能是以下某种原因：
- POPULARITY（默认）按热门程度对结果进行排序。
- DISTANCE 按结果与指定地点之间的距离以升序对结果进行排序。
regionCode

用于设置响应格式的地区代码，指定为两个字符的 CLDR 代码值。没有默认值。

如果响应中 formattedAddress 字段的国家/地区名称与 regionCode 匹配，则 formattedAddress 中会省略国家/地区代码。此参数对 adrFormatAddress（始终包含国家/地区名称）或 shortFormattedAddress（从不包含国家/地区名称）没有影响。

大多数 CLDR 代码与 ISO 3166-1 代码相同，但有一些明显的例外。例如，英国的国家代码顶级域名为“uk”(.co.uk)，而其 ISO 3166-1 代码却是“gb”（专指“大不列颠及北爱尔兰联合王国”这一实体）。此参数可能会根据适用法律影响结果。

附近搜索（新）示例

查找某一类地点

以下示例展示了一个“附近搜索（新）”请求，用于查询半径为 500 米（由 circle 定义）范围内的所有餐厅的显示名称：

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 半径 1000 米范围内所有便利店和酒类商店的显示名称：

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" 的所有地点）发出的“附近地点搜索（新）”请求，并按距离对结果进行排名：

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

搜索某个区域附近的所有地点，并按距离对其进行排名

以下示例展示了针对旧金山市中心某个地点附近的地点的“附近搜索（新）”请求。在此示例中，您添加了 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 参数设置为字段掩码。
您可以视需要修改请求正文。
选择执行按钮。在弹出式窗口中，选择您要使用哪个账号发出请求。
在 API Explorer 面板中，选择展开图标以展开 API Explorer 窗口。

附近搜索（新）

“附近搜索（新）”请求

“附近搜索（新）”响应

必需参数

FieldMask

locationRestriction

可选参数

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode