此页面由 Cloud Translation API 翻译。

文本搜索（新）

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

该服务对于在自动化系统中进行模糊地址查询特别有用，并且字符串的非地址组成部分可以与商家以及地址匹配。模糊地址查询的示例包括格式错误的地址，或包含商家名称等非地址组成部分的请求。除非设置了地理位置（例如地区、位置限制或位置偏向），否则下表中的前两个示例等请求可能会返回零结果。

“10 High Street, UK”或“123 Main Street, US”	英国有多个“High Street”；美国有多个“Main Street”。除非设置了位置限制，否则查询不会返回所需的结果。
“纽约连锁餐厅”	纽约有多个“ChainRestaurant”分店；没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US”	只有一条位于英国埃舍尔市的“高街”；在美国加利福尼亚州普莱森顿市只有一条“主街”。
“纽约 UniqueRestaurantName”	在纽约只有一家使用此名称的场所；无需使用街道地址进行区分。
“北京烤鸭店”	此查询包含其位置限制，“北京烤鸭”是一种定义明确的地点类型。它会返回多个结果。
“+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.id、places.name^*
  
  ^* places.name 字段包含地点资源名称，格式为：places/PLACE_ID。使用 places.displayName 访问地点的文本名称。
- 以下字段会触发“文本搜索（基本）SKU”：
  places.accessibilityOptions、places.addressComponents、places.adrFormatAddress、places.businessStatus、places.displayName、places.formattedAddress、places.googleMapsUri、places.iconBackgroundColor、places.iconMaskBaseUri、places.location、places.photos、places.plusCode、places.primaryType、places.primaryTypeDisplayName、places.shortFormattedAddress、places.subDestinations、places.types、places.utcOffsetMinutes、{1places.viewport
- 以下字段会触发“文本搜索（高级）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.delivery、 places.delivery、 places.delivery、 places.delivery {2 places.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
textQuery

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

可选参数

includedType

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

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

指定用于识别可用电动汽车 (EV) 充电连接器和充电速率的参数。
- connectorTypes
  
  按地点可用的电动汽车充电连接器类型进行过滤。不支持任何连接器类型的地点将被滤除。支持的电动汽车充电连接器类型包括组合式（交流和直流）充电器、特斯拉充电器、符合 GB/T 标准的充电器（适用于中国的电动汽车快速充电）和墙壁插座充电器。如需了解详情，请参阅参考文档。
- minimumChargingRateKw
  
  按最低电动汽车充电速率进行过滤，以千瓦 (kW) 为单位。如果地点的收费费率低于最低收费费率，则这些地点会被滤除。例如，如需查找充电速率至少为 10 kW 的电动汽车充电器，您可以将此参数设置为“10”。
minRating

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

如果为 true，则仅返回那些在发送查询时开门营业的地点。如果为 false，则返回所有商家，无论其处于营业状态如何。如果将此参数设置为 false，则会返回未在 Google 地点数据库中指定营业时间的地点。
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 代码相同。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（专指“大不列颠及北爱尔兰联合王国”）。该参数可能会影响根据适用法律的结果。
strictTypeFiltering

与 includeType 参数搭配使用。设置为 true 时，系统仅返回与 includeType 指定的指定类型相匹配的地点。默认情况下，如果为 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"
      }
    },
    {
      "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 视为指定结果必须靠近但可以位于该区域之外的区域。

注意：使用 locationBias 时，您可以将区域指定为矩形视口或圆形。对于 locationRestriction，您可以将区域指定为矩形视口。

以下示例展示了针对“辣味素食”的文本搜索请求，并将其自定义调整为位于旧金山市中心某个点的 500 米范围内。此请求仅返回营业地点的前 10 个结果。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 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 搜索配有与您的电动汽车兼容的充电桩的地点。

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

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "maxResultCount": 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
          }
        ]
      }
    }
  ]
}

试试看！

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

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

文本搜索（新）

“文本搜索”请求

文本搜索（新）响应

必需参数

FieldMask

textQuery

可选参数

includedType

languageCode

locationBias

locationRestriction

maxResultCount

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

priceLevels

rankPreference

regionCode

strictTypeFiltering

文本搜索示例

通过查询字符串查找地点

按价位过滤地点

搜索某个区域内的地点

搜索具有最低充电速率的电动汽车充电站

试试看！