附近搜索(新)

附近搜索(新)请求采用一个或多个地点类型,并返回指定区域内匹配地点的列表。必须提供用于指定一种或多种数据类型的字段掩码。附近搜索(新)仅支持 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

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

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

    指定要返回的地点数据类型的逗号分隔列表。例如,用于检索地点的显示名称和地址。

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    使用 * 检索所有字段。

    X-Goog-FieldMask: *

    指定以下一个或多个字段:

    • 以下字段会触发附近搜索(基本)SKU

      places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.businessStatusplaces.displayNameplaces.formattedAddressplaces.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.idplaces.locationplaces.name*places.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

      *places.name 字段包含地点资源名称,格式为:places/PLACE_ID使用 places.displayName 访问地点的文本名称。

    • 以下字段会触发附近搜索(高级)SKU

      places.currentOpeningHoursplaces.currentSecondaryOpeningHoursplaces.internationalPhoneNumberplaces.nationalPhoneNumberplaces.priceLevelplaces.ratingplaces.regularOpeningHoursplaces.regularSecondaryOpeningHoursplaces.userRatingCountplaces.websiteUri

    • 以下字段会触发附近搜索(首选)SKU

      places.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.delivery、 {2 / }、 places.delivery {2 / } {2 / } {2 / } {2 / } {2 / { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2places.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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/excludedType、includedPrimaryTypes/excludedPrimaryTypes

    允许您指定表 A 中用于过滤搜索结果的类型的列表。在每个类型限制类别中,最多可以指定 50 种类型。

    一个地点只能具有与其关联的表 A 类型中的一个主要类型。例如,主要类型可能是 "mexican_restaurant""steak_house"。使用 includedPrimaryTypesexcludedPrimaryTypes 按地点主要类型过滤结果。

    一个地点还可以具有与之关联的表 A 类型的多个类型值。例如,餐馆可能具有以下类型:"seafood_restaurant""restaurant""food""point_of_interest""establishment"。使用 includedTypesexcludedTypes 过滤与地点相关联的类型列表中的结果。

    如果搜索指定了多种类型限制,系统仅返回满足所有限制的地点。例如,如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]},则返回的地点会提供与 "restaurant" 相关的服务,但不会主要作为 "steak_house" 运行。

    includedTypes

    表 A 中要搜索的地点类型列表(以英文逗号分隔)。如果省略此参数,则返回所有类型的地点。

    excludedTypes

    表 A 中要从搜索中排除的地点类型列表(以英文逗号分隔)。

    如果您在请求中同时指定了 includedTypes(例如 "school")和 excludedTypes(例如 "primary_school"),响应会包含归类为 "school" 而非 "primary_school" 的地点。响应包含与 includedTypes至少一个匹配但与 excludedTypes 都不匹配的地点。

    如果存在任何冲突的类型(例如 includedTypesexcludedTypes 中出现的某个类型),则会返回 INVALID_REQUEST 错误。

    includedPrimaryTypes

    表 A 中要添加到搜索中的主要地点类型的逗号分隔列表。

    excludedPrimaryTypes

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

    如果主要类型(例如 includedPrimaryTypesexcludedPrimaryTypes 都存在某个类型)存在任何冲突,系统会返回 INVALID_ARGUMENT 错误。

  • languageCode

    返回结果时使用的语言。

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

    指定要返回的地点结果的数量上限。必须介于 1 和 20(默认值)之间,包括 1 和 20。

  • rankPreference

    要使用的排名类型。如果省略此参数,则结果会按热门程度排名。可能为以下其中一项:

    • POPULARITY(默认)根据结果的热门程度对结果进行排序。
    • DISTANCE:按结果与指定位置的距离以升序对结果进行排序。
  • regionCode

    用于设置响应格式的地区代码,以 双字符 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"
      }
    },
...
}

查找多种类型的地点

以下示例展示了一个“附近搜索(新)”请求,该请求需要获取指定 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.primaryTypeplaces.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 选项。

  1. (可选)展开显示标准参数,并将 fields 参数设置为字段掩码
  2. (可选)修改请求正文
  3. 选择执行按钮。在弹出式窗口中,选择要用于发出请求的帐号。