文本搜索（新）

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

欧洲经济区 (EEA) 开发者

简介

文本搜索（新版）可以根据一个字符串（例如，“北京烤鸭”“南京附近的鞋店”或“长安街 8 号”）返回一组地点的相关信息。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。

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

借助 APIs 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.consumerAlert
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

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

      如需查看字段及其关联 SKU 的完整列表，请参阅地点数据字段（新版）。

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

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

      * 地址描述符已面向印度客户正式推出，在其他地区尚处于实验阶段。

      如需查看字段及其关联 SKU 的完整列表，请参阅地点数据字段（新版）。

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

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.transitStation
      places.userRatingCount
      places.websiteUri

      如需查看字段及其关联 SKU 的完整列表，请参阅地点数据字段（新版）。

    • 以下字段会触发文本搜索企业版 + 氛围 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

      * 仅限文本搜索和附近搜索

      如需查看字段及其关联 SKU 的完整列表，请参阅地点数据字段（新版）。

  • 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 near Dallas, Texas”
    具有多种解读方式的模糊查询 “充电器送修”
    不再使用的历史名称 "Middlesex United Kingdom"
    非地理空间元素或意图 “文图拉港有多少艘船？”
    非官方名称或虚荣名称 "The Jenga"
    "The Helter Skelter"
    经纬坐标 "37.422131,-122.084801"

可选参数

  • includeFutureOpeningBusinesses

    如果为 true，则返回预计在未来开业的商家。默认值为 false。

    如需检索营业状态，请在请求字段掩码中添加 places.businessStatus。如需检索商家的预计开业日期，请在请求字段掩码中添加 places.openingDate。

  • 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 和 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 视为指定结果可能位于或靠近但可以位于该区域之外的区域。

  • evOptions

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

    • connectorTypes

      按地点提供的电动汽车充电连接器类型进行过滤。系统会滤除不支持任何连接器类型的地点。 支持的电动汽车充电连接器类型包括组合式（交流和直流）充电器、特斯拉充电器、符合 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 kW 的电动汽车充电桩，您可以将此参数设置为“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，您可以在后续请求中传递该令牌来访问下一页。

    此字段会替换已弃用的 maxResultCount 字段。如果您同时指定 pageSize 和 maxResultCount，API 会使用 pageSize 并忽略 maxResultCount。

  • 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（默认值），则响应可能包含与指定类型不匹配的地点。

文本搜索（新版）示例

通过查询字符串查找地点

以下示例展示了针对“Spicy Vegetarian Food in Sydney, Australia”（澳大利亚悉尼的香辣素食）的文本搜索（新版）请求：

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"
      }
    },
    ...
  ]
}

向字段掩码添加更多数据类型，以返回更多信息。 例如，添加 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 搜索有与您的电动汽车兼容的可用充电桩的地点。

以下示例展示了针对加利福尼亚州山景城内最低充电速率为 10 kW 的 Tesla 和 J1772 1 型电动汽车充电连接器的请求。系统仅返回四个结果。

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"
          },
          ...
        ]
      }
    },
    {
      "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"
          }
        ]
      }
    },
    ...
  ]
}

搜索上门服务商家

使用 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"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "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"
    },
    ...
  ],
  "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"
    },
    ...
  ],
  "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
          },
          ...
        ],
        "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"
          },
          ...
        ]
      }
    },
    ...
  ]
}

查找未来开业的商家

以下示例展示了针对爱达荷州新梅多斯未来开业商家的文本搜索（新版）请求：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

响应中包含未来将开业的商家，以及其营业状态和预计开业日期：

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

获取公共交通站点信息

您可以使用文本搜索（新版）查找公交站点。响应正文包含车站的相关信息，包括车站名称、所属公共交通公司以及服务于该车站的公共交通线路。此外，响应还包含车辆图标和颜色，可用于显示公交站点信息。

以下示例展示了针对“Grand Central Station”的请求：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

响应正文包含半径范围内每个车站的信息、车站服务的线路、公共交通公司在该车站发出的提醒以及出发信息：

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

获取入口和导航点

您可以请求目的地的入口和导航点。入口定义了地点的出入口（例如机场或购物中心的不同大门）。导航点定义了导航应结束的路边位置，这有助于将用户引导至正确的路边或特定的下车点。

导航点会返回 navigationPointToken。您可以将此令牌传递给 Navigation SDK（适用于 Android 或 iOS）或 Routes API，以引导司机前往该特定位置。如需了解详情，请参阅导航点令牌。

以下示例展示了针对“旧金山国际机场”的文本搜索（新版）请求，其中字段掩码中包含 entrances 和 navigationPoints：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

响应中包含该地点的入口和导航点：

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

试试看！

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

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

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

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

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