文本搜索（新）

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

欧洲经济区 (EEA) 开发者

简介

文本搜索（新）可以根据一个字符串（例如，“纽约的披萨”“渥太华附近的鞋店”或“长安街 123 号”）返回一组地点的相关信息。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。

除了必需的参数之外，“文本搜索（新）”还支持使用可选参数来优化查询，以获得更好的结果。

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

“文本搜索（新）”请求

文本搜索（新）请求是一种 HTTP POST 请求，其格式如下：

https://places.googleapis.com/v1/places:searchText

在 JSON 请求正文或标头中传递所有参数，作为 POST 请求的一部分。例如：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

文本搜索（新）响应

文本搜索（新）会 以 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: *

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

    • 以下字段会触发文本搜索精简版（仅 ID）SKU：

      places.attributions
      places.id
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

      * places.name 字段包含地点资源名称，格式为：places/PLACE_ID。在 Pro SKU 中使用 places.displayName 访问地点的文本名称。

    • 以下字段会触发文本搜索专业版 SKU：

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.searchUri
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * 地址描述符已面向印度客户正式发布，但在其他国家/地区仍处于实验阶段。

    • 以下字段会触发文本搜索企业版 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.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
      * 仅限文本搜索和附近搜索

  • textQuery

    要搜索的文本字符串。例如，“餐厅”“长安街 123 号”或“旧金山最佳旅游景点”。该 API 会根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。

    文本搜索（新）不适用于模糊查询，包括以下情况：

    查询类型 示例
    概念或限制条件过多，例如在单个查询中包含多个地点、道路或城市的名称 “Market Street San Francisco San Jose Airport”
    Google 地图上未显示的邮政地址元素 "C/O John Smith 123 Main Street"
    "P.O. Box 13 San Francisco"
    商家、连锁店或类别的名称与这些实体不可用的位置的组合 “德克萨斯州达拉斯附近的 Tesco”
    具有多种解读的模糊查询 “充电器送达”
    不再使用的历史名称 "Middlesex United Kingdom"
    非地理空间元素或意图 “Ventura Harbor 有多少艘船？”
    非官方名称或自选名称 "The Jenga"
    "The Helter Skelter"
    经纬坐标 "37.422131,-122.084801"

可选参数

  • includedType

    使结果偏向于与表 A 中定义的指定类型相匹配的地点。 只能指定一种类型。例如：

    • "includedType":"bar"
    • "includedType":"pharmacy"

    文本搜索（新）会根据适用性对某些查询应用类型过滤。例如，类型过滤可能不适用于针对特定地址（“123 Main Street”）的查询，但几乎总是适用于类别查询（“附近的商店”或“购物中心”）。

    如需对所有查询应用类型过滤，请将 strictTypeFiltering 设置为 true。

  • includePureServiceAreaBusinesses

    如果设置为 true，则响应中会包含直接上门或为客户提供送货服务的商家，但这些商家没有实体营业地点。如果设置为 false，API 将仅返回具有实体营业地点的商家。

  • languageCode

    返回结果所用的语言。

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

  • locationBias

    指定要搜索的区域。此位置用作偏差，这意味着可以返回指定位置附近的结果，包括指定区域之外的结果。

    您可以指定 locationRestriction 或 locationBias，但不能同时指定这两者。可以将 locationRestriction 视为指定结果必须位于的区域，而将 locationBias 视为指定结果可能位于或靠近的区域，但结果也可以位于该区域之外。

    将区域指定为矩形视口或圆形。

    • 圆由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含边界值）。默认半径为 0.0。 例如：

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • 矩形是纬度-经度视口，表示为两个对角线相对的低点和高点。低点标记矩形的西南角，高点表示矩形的东北角。

      视口被视为一个闭合区域，这意味着它包含其边界。纬度范围必须介于 -90 度到 90 度之间（含），经度范围必须介于 -180 度到 180 度之间（含）：

      • 如果 low = high，则视口由该单个点组成。
      • 如果 low.longitude > high.longitude，则经度范围会反转（视口会跨越 180 度经度线）。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度，则视口包含所有经度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。
      • 如果 low.latitude > high.latitude，则纬度范围为空。

      必须同时填充下限和上限，并且所表示的框不得为空。空视口会导致错误。

      例如，此视口完全包含纽约市：

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    指定要搜索的区域。系统不会返回指定区域以外的结果。

    将区域指定为矩形视口。如需查看定义视口的示例，请参阅 locationBias 的说明。

    您可以指定 locationRestriction 或 locationBias，但不能同时指定这两者。可以将 locationRestriction 视为指定结果必须位于的区域，而将 locationBias 视为指定结果可能位于或靠近的区域，但结果也可以位于该区域之外。

  • maxResultCount（已弃用）

    指定每页显示的结果数（介于 1 到 20 之间）。 例如，将 maxResultCount 值设置为 5 将在第一页上返回最多 5 个结果。如果查询可以返回更多结果，则响应会包含一个 nextPageToken，您可以将其传递给后续请求以访问下一页。

  • evOptions

    指定用于识别可用电动汽车 (EV) 充电连接器和充电速率的参数。

    • connectorTypes

      按地点提供的电动汽车充电连接器类型进行过滤。不支持任何连接器类型的地点将被过滤掉。 支持的电动汽车充电连接器类型包括组合式（交流和直流）充电器、Tesla 充电器、符合 GB/T 标准的充电器（用于在中国为电动汽车快速充电）和壁式插座充电器。如需了解详情，请参阅参考文档。

      • 如需过滤出特定受支持的连接器的结果，请将 connectorTypes 设置为相应值。例如，如需查找 J1772 类型 1 连接器，请将 connectorTypes 设置为 EV_CONNECTOR_TYPE_J1772。
      • 如需过滤不受支持的连接器的结果，请将 connectorTypes 设置为 EV_CONNECTOR_TYPE_OTHER。
      • 如需过滤结果以查找任何类型的壁式插座连接器，请将 connectorTypes 设置为 EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET。
      • 如需过滤任何连接器类型的结果，请将 connectorTypes 设置为 EV_CONNECTOR_TYPE_UNSPECIFIED，或者不为 connectorTypes 设置值。

    • minimumChargingRateKw

      按最低电动车辆充电速率（以千瓦 [kW] 为单位）过滤地点。系统会过滤掉充电费率低于最低充电费率的任何地点。例如，如需查找充电速率至少为 10 千瓦的电动汽车充电器，您可以将此参数设置为“10”。

  • minRating

    将结果限制为仅包含平均用户评分大于或等于此限制的结果。值必须介于 0.0 到 5.0 之间（含边界值），且以 0.5 为增量。例如：0、0.5、1.0、...、5.0（含）。值向上舍入到最接近的 0.5。例如，值为 0.6 会排除所有评分低于 1.0 的结果。

  • openNow

    如果为 true，则仅返回在发送查询时开门营业的地点。如果值为 false，则返回所有商家，无论其营业状态如何。 如果您将此参数设置为 false，系统会返回那些未在 Google 地点数据库中指定营业时间的地点。

  • pageSize

    指定每页显示的结果数（介于 1 到 20 之间）。 例如，将 pageSize 值设置为 5 将在第一页上返回最多 5 个结果。如果查询可以返回更多结果，则响应会包含一个 nextPageToken，您可以将其传递给后续请求以访问下一页。

  • pageToken

    指定上一个网页的响应正文中的 nextPageToken。

  • priceLevels

    将搜索范围限制为标记为特定价位的地点。 默认情况下，系统会选择所有价位。

    以下类型的地点可能会有价格水平：

    如果指定了 priceLevels，则响应中不会包含不支持的类型的地点。

    指定由 PriceLevel 定义的一个或多个值的数组。

    例如：

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    指定响应中结果的排名方式，具体取决于查询类型：

    • 对于“纽约市的餐厅”等类别查询，默认值为 RELEVANCE（按搜索相关性对结果进行排名）。您可以将 rankPreference 设置为 RELEVANCE 或 DISTANCE（按距离对结果进行排名）。
    • 对于“Mountain View, CA”等非类别查询，我们建议您将 rankPreference 保持未设置状态。

  • regionCode

    用于设置响应格式的地区代码，以 双字符 CLDR 代码值指定。此参数还可能会对搜索结果产生偏差效应。没有默认值。

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

    除了某些明显的例外情况之外，大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。

  • strictTypeFiltering

    与 includedType 参数搭配使用。如果设置为 true，则仅返回与 includedType 指定的类型相匹配的地点。 如果值为 false（默认值），则响应可以包含与指定类型不匹配的地点。

文本搜索（新）示例

通过查询字符串查找地点

以下示例展示了针对“澳大利亚悉尼的辣味素食”的文本搜索（新）请求：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

请注意，X-Goog-FieldMask 标头指定响应包含以下数据字段：places.displayName,places.formattedAddress。然后，响应的格式如下：

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

向字段掩码添加更多数据类型，以返回更多信息。 例如，添加 places.types,places.websiteUri 可在响应中包含餐厅类型和网址：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'

响应现在采用以下格式：

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

按价格水平过滤地点

使用 priceLevel 选项可将结果过滤为价格低廉或中等价位的餐厅：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

此示例还使用 X-Goog-FieldMask 标头将 places.priceLevel 数据字段添加到响应，使其采用以下形式：

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

添加其他选项以优化搜索，例如 includedType、minRating、rankPreference、openNow 以及可选参数中描述的其他参数。

将搜索范围限制在指定区域内

使用 locationRestriction 或 locationBias（但不能同时使用这两者）可将搜索范围限制在某个区域内。您可以将 locationRestriction 视为指定结果必须位于的区域，而将 locationBias 视为指定结果必须靠近但可以位于该区域之外的区域。

使用 locationRestriction 限制区域

使用 locationRestriction 参数可将查询结果限制为指定区域。在请求正文中，指定定义区域边界的 low 和 high 纬度和经度值。

以下示例展示了针对纽约市“素食”的文本搜索（新）请求。此请求仅返回营业场所的前 10 个结果。

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

使用 locationBias 偏向某个区域

以下示例展示了针对“素食”的文本搜索（新）请求，该请求偏向于旧金山市中心某个点 500 米范围内的位置。此请求仅返回营业场所的前 10 个结果。

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "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' \
'https://places.googleapis.com/v1/places:searchText'

搜索最低充电速率的电动汽车充电桩

使用 minimumChargingRateKw 和 connectorTypes 搜索提供与您的电动汽车兼容的可用充电器的地点。

以下示例展示了在加利福尼亚州山景城请求 Tesla 和 J1772 类型 1 EV 充电连接器，且最低充电率为 10 kW。系统仅返回了 4 条结果。

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

请求会返回以下响应：

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

搜索上门服务商家

使用 includePureServiceAreaBusinesses 参数可搜索没有实体服务地址的商家（例如移动清洁服务或餐车）。

以下示例展示了针对旧金山水管工的请求：

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

在响应中，没有实体服务地址的商家不包含 formattedAddress 字段：

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

指定每页返回的结果数

使用 pageSize 参数指定每页要返回的结果数。响应正文中的 nextPageToken 参数提供了一个令牌，可在后续调用中使用该令牌来访问下一页结果。

以下示例展示了对“纽约的披萨店”的请求，其中将每页的结果数限制为 5 个：

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

如需访问下一页结果，请使用 pageToken 在请求正文中传入 nextPageToken：

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

获取地址描述符

地址描述符提供有关地点位置的关系信息，包括附近的标志性建筑和包含的区域。

以下示例展示了针对圣何塞某购物中心附近地点的文本搜索（新）请求。在此示例中，您在字段掩码中添加了 addressDescriptors：

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-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:searchText

响应包含请求中指定的地点、附近地标及其与该地点的距离列表，以及区域及其与该地点的包含关系列表：

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "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": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "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": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

试试看！

借助 API Explorer，您可以发出示例请求，以便熟悉 API 和 API 选项。

  1. 选择页面右侧的 API 图标 api。

  2. （可选）修改请求参数。

  3. 选择执行按钮。在对话框中，选择您要用于提出请求的账号。

  4. 在 APIs Explorer 面板中，选择全屏图标 fullscreen 以展开 APIs Explorer 窗口。