此页面由 Cloud Translation API 翻译。

文本搜索（新）

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

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

该服务在自动化系统中进行地址模糊查询时尤其有用，字符串的非地址组成部分可能与商家以及地址匹配。举例来说，格式不正确的地址，或者包含商家名称等非地址组件的请求可以使用地址模糊查询。除非设置了位置（例如地区、位置限制或位置偏好），否则以下表格中前两个示例的请求可能会返回零个结果。

“10 High Street, UK”或“123 Main Street, US”	英国有多个“High Street”；美国有多个“Main Street”。除非设置了位置限制，否则查询不会返回所需的结果。
“纽约连锁餐馆”	纽约有多个“ChainRestaurant”地点，但没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US”	英国埃舍尔市只有一条“High Street”；美国加利福尼亚州普莱森顿市只有一条“Main Street”。
“UniqueRestaurantName New York”	在纽约只有一个具有此名称的场所；无需区分街道地址。
“北京烤鸭店”	此查询包含其位置限制，“北京烤鸭”是一个明确定义的地点类型。该方法会返回多个结果。
“+1 514-670-8700”	此查询包含电话号码。它会针对与该电话号码关联的地点返回多个结果。注意：如需按电话号码搜索时获得最佳结果，请添加国家/地区代码后跟一个空格，并将 `regionCode` 参数设置为与国家/地区代码相对应。

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

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

指定以下一个或多个字段：
- 以下字段会触发文本搜索（仅 ID）SKU：
  places.attributions、places.id、places.name^*、nextPageToken
  
  ^* places.name 字段包含地点资源名称，格式为：places/PLACE_ID。使用 places.displayName 访问地点的文本名称。
- 以下字段会触发文本搜索（基本）SKU：
  places.accessibilityOptions、places.addressComponents、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.primaryType、places.primaryTypeDisplayName、places.pureServiceAreaBusiness、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、places.viewport
  
  ^*places.googleMapsLinks 字段处于正式发布前预览阶段，在预览期间使用不会产生费用，也就是说，结算金额为 0 美元。
- 以下字段会触发文本搜索（高级）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.delivery、2、places.dineIn、places.editorialSummary、places.evChargeOptions、places.fuelOptions、places.goodForChildren、places.fuelOptions、places.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviewsplaces.routingSummariesplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
textQuery

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

可选参数

includedType

将结果限制为与表 A 中定义的指定类型匹配的地点。只能指定一种类型。例如：
- "includedType":"bar"
- "includedType":"pharmacy"
注意：表 B 中的值仅在响应中返回。您不能将表 B 中的值用作过滤条件。
includePureServiceAreaBusinesses

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

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

指定要搜索的区域。此位置是一种偏差，这意味着可以返回指定位置周围的结果，包括指定区域以外的结果。

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

注意：如果您同时省略 locationBias 和 locationRestriction，则该 API 默认使用 IP 偏向。启用 IP 偏向后，API 会使用设备的 IP 地址来偏向结果。

注意： 如果 textQuery 包含显式位置（例如 Market in Barcelona），则可以替换 locationBias 参数。在这种情况下，系统会忽略 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 视为指定结果可能位于其中或附近但可以位于该区域之外的区域。

注意：如果您同时省略 locationBias 和 locationRestriction，则该 API 默认使用 IP 偏向。使用 IP 偏向时，API 会使用设备的 IP 地址来偏向结果。
maxResultCount（已废弃）

已废弃：此字段已废弃，取而代之的是 pageSize。如果同时指定了 maxResultCount 和 pageSize，系统会使用 pageSize 并忽略 maxResultCount。

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

注意：如果 maxResultCount 为 0 或未指定，则 API 默认每页返回 20 个结果。如果 maxResultCount 大于 20，则 API 每页返回的结果数不超过 20 个。
evOptions

指定用于识别可用电动汽车 (EV) 充电连接器和充电费率的参数。
- connectorTypes
  
  按某个地点可用的电动汽车充电连接器类型进行过滤。不支持任何连接器类型的地点将被滤除。支持的电动汽车充电连接器类型包括组合式（交流和直流）充电器、特斯拉充电器、符合 GB/T 标准的充电器（适用于中国境内的电动汽车快速充电）和墙壁插座充电器。如需了解详情，请参阅参考文档。
- 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，您可以将其传递给后续请求以访问下一页。

注意：如果 pageSize 为 0 或未指定，则该 API 将默认每页返回 20 个结果。如果 pageSize 大于 20，则 API 每页返回的结果数不超过 20 个。
pageToken

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

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

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

注意： 请求中不允许使用 PRICE_LEVEL_FREE。它仅用于填充响应。

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

与 includedType 参数搭配使用。设置为 true 时，系统仅返回与 includeType 指定的指定类型匹配的地点。如果为 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 时，您只能将区域指定为矩形视口。使用 locationBias 时，您可以将区域指定为矩形视口或圆形。

使用 locationRestriction 限制区域

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

以下示例展示了在纽约市搜索“素食”的 Text Search 请求。此请求仅返回正在营业的地点的前 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 偏向于某个区域

以下示例展示了一个针对“vegetarian 食品”的文本搜索请求，该请求偏向于旧金山市区某个点的 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 电动汽车充电连接器的请求。系统仅返回 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"
}

试试看！

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

选择页面右侧的 API 图标。
（可选）展开显示标准参数 (Show standard parameters)，并将 fields 参数设置为字段掩码。
（可选）修改请求正文。
选择执行按钮。在弹出的对话框中，选择您要用于发出请求的账号。
在 API Explorer 面板中，选择展开图标以展开 API Explorer 窗口。

文本搜索（新）

“文本搜索”请求

文本搜索（新）响应

必需参数

FieldMask

textQuery

可选参数

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount（已废弃）

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering

文本搜索示例

通过查询字符串查找地点

按价格水平过滤地点

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

使用 locationRestriction 限制区域

使用 locationBias 偏向于某个区域

搜索最低充电费率的电动车辆充电桩

搜索上门服务商家

指定每页返回的结果数

试试看！