查找地点（旧版）

“查找地点（旧版）”请求会根据用户输入的文本返回地点。输入可以是任何类型的地点文本数据，例如名称、地址或电话号码。请求必须是字符串。使用非字符串数据（例如纬度/经度坐标或 Plus Code）的 Find Place（旧版）请求会生成错误。

“查找地点（旧版）”请求

“查找地点（旧版）”请求是采用以下格式的 HTTP 网址：

https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters

其中 output 可以是以下任一值：

• json（推荐）表示以 JavaScript 对象表示法 (JSON) 格式输出
• xml 表示输出为 XML

发起“查找地点（旧版）”请求时，必须提供某些参数。依照网址的标准，所有参数都使用“与”符号 (&) 分隔。

必需参数

• 输入

  用于进行搜索的文本字符串。该参数必须是地点名称、地址或电话号码（例如“123 Main Street”或“City Hall”）。

• inputtype

  输入类型。可以是 textquery 或 phonenumber。电话号码必须采用国际电话号码格式（以加号 [“+”] 为前缀，后跟国家/地区代码，然后是电话号码本身）。如需了解详情，请参阅 E.164 ITU 建议书。

可选参数

• 字段

  注意：“地点搜索（旧版）”请求和“地点详情（旧版）”请求不会返回相同的字段。“地点搜索（旧版）”请求会返回“地点详情（旧版）”请求返回的部分字段。如果“地点搜索（旧版）”未返回您所需的字段，您可以使用“地点搜索（旧版）”获取 place_id，然后使用该地点 ID 发出“地点详情（旧版）”请求。如需详细了解地点搜索（旧版）请求中不支持的字段，请参阅 Places API 字段支持。

  使用 fields 参数指定要返回的地点数据类型的逗号分隔列表。例如 fields=formatted_address,name,geometry。指定复合值时，请使用正斜杠。例如：opening_hours/open_now。

  这些字段分为三个结算类别：基本、联系人和氛围。“基本”字段按基本费率结算，“联系人”和“氛围”字段按更高的费率结算。除了触发基本数据、联系人数据和氛围数据 SKU 的请求的基础 SKU（地点详情、查找地点、附近搜索或文本搜索）费用外，您还需要支付这些 SKU 的费用。如需了解详情，请参阅定价表。

  基本版

  “基本”类别包括以下字段：address_components、adr_address、business_status、formatted_address、geometry、icon、icon_mask_base_uri、icon_background_color、name、permanently_closed（已弃用）、photo、place_id、plus_code、type、url、utc_offset、vicinity、wheelchair_accessible_entrance。

  联系

  “联系人”类别包括以下字段：current_opening_hours、formatted_phone_number、international_phone_number、opening_hours、secondary_opening_hours、website

  氛围

  “氛围”类别包括以下字段：curbside_pickup、delivery、dine_in、editorial_summary、price_level、rating、reservable、reviews、serves_beer、serves_breakfast、serves_brunch、serves_dinner、serves_lunch、serves_vegetarian_food、serves_wine、takeout、user_ratings_total。

  注意：无论是否针对此字段发出请求，每次调用都会返回提供方说明 html_attributions。

• language

  返回结果时所用的语言。

  • 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
  • 如果未提供 language，API 会尝试使用 Accept-Language 标头中指定的首选语言。
  • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现此目标，它会以本地语言返回街道地址，并在必要时将其音译为用户可读的文字，同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一种语言返回，该语言是从第一个组成部分中选择的。
  • 如果首选语言中没有名称，API 会使用最接近的匹配项。
  • 首选语言对 API 选择返回的结果集以及返回顺序有轻微影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或可能在一种语言中有效但在另一种语言中无效的同义词。例如，utca 和 tér 在匈牙利语中是“街道”的同义词。

• locationbias

  通过指定半径和纬度/经度，或指定代表矩形点的两对纬度/经度，优先显示指定区域内的结果。如果未指定此参数，则 API 默认使用 IP 地址偏向。

  • IP 偏好：指示 API 使用 IP 地址偏好。传递字符串 ipbias（此选项没有其他参数）。
  • 圆形：一个字符串，用于指定半径（以米为单位）以及纬度/经度（以十进制度为单位）。请使用以下格式：circle:radius@lat,lng。
  • 矩形：一个字符串，以十进制度为单位指定两对纬度/经度，分别表示矩形的西南角和东北角。请使用以下格式：rectangle:south,west|north,east。请注意，东/西值会封装到 -180 到 180 的范围内，而南/北值会限制在 -90 到 90 的范围内。

查找地点（旧版）示例

以下示例展示了针对“Museum of Contemporary Art Australia”（澳大利亚当代艺术博物馆）的查找地点（旧版）请求，其中包含 photos、formatted_address、name、rating、opening_hours 和 geometry 字段：

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

以下示例展示了针对“Mongolian Grill”的查找地点（旧版）请求，该请求使用 locationbias 参数来优先显示指定坐标 2,000 米范围内的结果：

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

以下示例展示了针对电话号码的查找地点（旧版）请求。请注意，国际电话前缀“+”已编码为 %2B，因此此请求是合规的网址。 如果未进行编码，+ 前缀将在服务器上解码为空格，从而导致电话号码查找无效。

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

“查找地点（旧版）”响应

“查找地点（旧版）”响应仅包含使用 fields 参数指定的数据类型，以及 html_attributions。以下示例展示了针对“Museum of Contemporary Art Australia”（澳大利亚当代艺术博物馆）的查找地点（旧版）请求的响应，其中包含 formatted_address、geometry、name、opening_hours、photos、rating 字段。

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

PlacesSearchStatus

服务返回的状态代码。

• OK：表示 API 请求成功。
• ZERO_RESULTS，表示搜索成功，但未返回任何结果。如果向搜索传递了远程位置中的 latlng，就可能会发生这种情况。
• INVALID_REQUEST：表示 API 请求格式不正确，通常是因为缺少必需的查询参数（location 或 radius）。
• OVER_QUERY_LIMIT，表示以下任一情况：
  • 您已超出 QPS 限制。
  • 您的账号尚未启用结算功能。
  • 超出了每月 200 美元的赠金或您设定的用量上限。
  • 提供的付款方式不再有效（例如，信用卡已过期）。
  如需详细了解如何解决此错误，请参阅地图常见问题解答。
• REQUEST_DENIED：表示您的请求已遭拒，通常是因为：
  • 请求中缺少 API 密钥。
  • key 参数无效。
• UNKNOWN_ERROR：表示出现未知错误。

地点

地点搜索响应会返回以下地点字段子集。并非所有属性都适用于所有地点类型。如需检索地点搜索未返回的字段（例如 address_components、formatted_phone_number、reviews 或 website），请在地点详情（旧版）请求中传递返回的 place_id。如需了解各个端点的字段可用性和价格层级，请参阅地点数据字段（旧版）。