此页面由 Cloud Translation API 翻译。

附近搜索（新）

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

附近搜索（新）请求采用一个或多个地点类型，并返回资源。指定一种或多种数据类型的字段掩码为必填字段。附近搜索（新）仅支持 POST 请求。

利用 API Explorer，您可以发出实时请求，从而熟悉 API 和 API 选项：

尝试互动式演示，查看地图上显示的“附近搜索（新）”结果。

“附近搜索（新）”请求

“附近搜索（新）”请求是对表单：

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

“附近搜索（新）”回复

附近搜索（新）会返回 <ph type="x-smartling-placeholder"></ph> 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.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, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* places.name 字段包含地点资源名称 格式为 places/PLACE_ID。使用places.displayName 来访问地点的文本名称。
- 以下字段会触发附近搜索（高级）SKU：
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, 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.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 和 50000.0）。默认半径为 0.0。您必须请在请求中将其设置为大于 0.0 的值。

例如：
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

可选参数

includeTypes/excludedTypes，containsPrimaryTypes/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（默认值），包括 1 和 20。
rankPreference

要使用的排名类型。如果省略此参数，则结果将按热门程度排名。可以是以下其中一项：
- POPULARITY（默认）：根据热门程度对结果进行排序。
- DISTANCE，根据结果与指定位置。
regionCode

用于设置响应格式的地区代码，指定为 <ph type="x-smartling-placeholder"></ph> 两个字符的 CLDR 代码值。没有默认值。

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

大多数 CLDR 代码都与 ISO 3166-1 代码但有一些值得注意的例外情况。例如，英国的 ccTLD 为 "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"
      }
    },
...
}

查找多种类型的地点

以下示例展示了针对周围 1000 米半径范围内所有便利店和酒类商店的显示名称指定的 circle：

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

可选参数

includeTypes/excludedTypes，containsPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode