查找地点(旧版)

欧洲经济区 (EEA) 开发者

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

“查找地点”(旧版)请求

“查找地点”(旧版)请求采用以下形式的 HTTP 网址:

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

其中,output 可以是以下任一值:

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

您需要提供某些参数才能发起“查找地点(旧版)”请求。依照网址的标准,所有参数都使用“与”符号 (&) 分隔。

必需参数

  • 输入

    要用作搜索条件的文本字符串,例如“餐馆”或“长安街 123 号”。该参数必须是地点名称、地址或场所类别。任何其他类型的输入都可能产生错误,并且不能保证返回有效结果。Places API 将根据此字符串返回候选匹配结果,并按照其判断的相关性对结果进行排序。

  • inputtype

    输入类型。可以是 textqueryphonenumber 中的一个。电话号码必须采用国际电话号码格式(以加号 [“+”] 为前缀,后跟国家/地区代码,然后是电话号码本身)。如需了解详情,请参阅 E.164 ITU 建议书

可选参数

  • 字段

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

    使用 fields 参数指定一个逗号分隔列表,其中包含要返回的地点数据类型。例如 fields=formatted_address,name,geometry。指定复合值时,请使用正斜线。例如:opening_hours/open_now

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

    基本版

    “基本”类别包括以下字段: address_componentsadr_addressbusiness_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed已弃用)、photoplace_idplus_codetypeurlutc_offsetvicinitywheelchair_accessible_entrance

    联系

    “联系人”类别包括以下字段: current_opening_hoursformatted_phone_numberinternational_phone_numberopening_hourssecondary_opening_hourswebsite

    氛围

    “氛围”类别包括以下字段: curbside_pickupdeliverydine_ineditorial_summaryprice_levelratingreservablereviewsserves_beerserves_breakfastserves_brunchserves_dinnerserves_lunchserves_vegetarian_foodserves_winetakeoutuser_ratings_total

    注意:无论是否针对此字段发出请求,每次调用都会返回提供方数据 (html_attributions)。
  • language

    返回结果所用的语言。

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

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

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

查找地点(旧版)示例

以下示例展示了查找“澳大利亚当代艺术博物馆”的查找地点(旧版)请求,包含的字段有 photosformatted_addressnameratingopening_hoursgeometry

curl

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'

HTTP

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

以下示例展示了针对“蒙古烤肉”的“查找地点”(旧版)请求,该请求使用 locationbias 参数来优先显示指定坐标 2000 米范围内的结果:

curl

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'

HTTP

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

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'

HTTP

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。以下示例展示了针对“澳大利亚当代艺术博物馆”的查找地点(旧版)请求的响应,其中包含 formatted_addressgeometrynameopening_hoursphotosrating 字段。

JSON

{
  "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

<?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

字段 必需 类型 说明
required 数组<地点>

包含候选地点的数组。

“地点搜索”请求会返回“地点详情”请求返回的部分字段。如果“地点搜索”未返回您所需的字段,您可以使用“地点搜索”获取 place_id,然后使用该地点 ID 发出“地点详情”请求。

如需了解详情,请参阅地点

required PlacesSearchStatus

包含请求的状态,可能还包含调试信息,以帮助您跟踪请求失败的原因。

如需了解详情,请参阅 PlacesSearchStatus

可选 字符串

当服务返回的状态代码不是 OK< 时,响应对象中可能包含额外的 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息。此字段并非始终会返回,并且其内容可能会发生变化。

可选 数组<string>

当服务返回有关请求规范的其他信息时,响应对象中可能会包含额外的 info_messages 字段。此字段仅针对成功请求返回。它可能并不总是返回,并且其内容可能会发生变化。

PlacesSearchStatus

服务返回的状态代码。

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

地点

描述地点的属性。并非所有属性都适用于所有地点类型。

字段 必需 类型 说明
可选 Array<AddressComponent>

一个数组,其中包含适用于相应地址的各个组成部分。

如需了解详情,请参阅 AddressComponent

可选 字符串

adr 微格式表示的地点地址。

可选 字符串

表示地点的营业状态(如果该地点为商家)。 如果不存在任何数据,将不会返回 business_status

The allowed values include: OPERATIONAL, CLOSED_TEMPORARILY, and CLOSED_PERMANENTLY
可选 布尔值

指定商家是否支持路边取货。

可选 PlaceOpeningHours

包含未来 7 天(包括今天)的营业时间。时间段从请求当天的午夜开始,到六天后的晚上 11:59 结束。此字段包含所有营业时间的 special_days 子字段,适用于营业时间特殊的日期。

如需了解详情,请参阅 PlaceOpeningHours

可选 布尔值

指定商家是否支持配送。

可选 布尔值

指定商家是否支持室内或室外座位选项。

可选 PlaceEditorialSummary

包含地点的摘要。摘要包含文本概览,如果适用,还包含这些文本概览的语言代码。摘要文字必须按原样呈现,不得修改或更改。

如需了解详情,请参阅 PlaceEditorialSummary

可选 字符串

一个字符串,包含此地点直观易懂的地址。

此地址通常相当于邮政地址。请注意,由于许可限制,某些国家/地区(例如英国)不允许发布真实的邮政地址。

设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下组成部分:“111”(门牌号)、“8th Avenue”(路由)、“New York”(城市)和“NY”(美国州名)。

请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分,API 响应除了包含设有格式的地址字段外,还包含这些组成部分。

可选 字符串

包含地点的电话号码(采用本地格式)。

可选 Geometry

包含相应位置的位置和视口。

如需了解详情,请参阅 Geometry

可选 字符串

包含建议的图标的网址,该图标可能会在地图上显示此结果时向用户显示。

可选 字符串

包含地点类别的默认十六进制颜色代码。

可选 字符串

包含建议图标的网址,但不含 .svg.png 文件类型扩展名。

可选 字符串

包含地点的电话号码(采用国际电话号码格式)。 国际电话号码格式包含国家/地区代码,并且带有一个加号 (+) 前缀。例如,Google 澳大利亚悉尼办事处的 international_phone_number 为 +61 2 9374 4000

可选 字符串

包含返回结果的简单易懂的名称。对于 establishment 结果,这通常是规范化的商家名称。

可选 PlaceOpeningHours

包含正常营业时间。

如需了解详情,请参阅 PlaceOpeningHours

可选 布尔值

使用 business_status 获取商家的营业状态。

可选 数组<PlacePhoto>

照片对象数组,每个对象都包含对图片的引用。 一个请求最多可返回 10 张照片。如需详细了解地点照片以及如何在应用中使用这些图片,请参阅地点照片文档。

如需了解详情,请参阅 PlacePhoto

可选 字符串

唯一标识地点的文本标识符。如需检索地点的相关信息,请在 Places API 请求的 place_id 字段中传递此标识符。如需详细了解地点 ID,请参阅地点 ID 概览

可选 PlusCode

经过编码的位置引用,衍生自纬度和经度坐标,表示面积不超过 1/8, 000 度 x 1/8, 000 度(在赤道处约为 14 米 x 14 米)的区域。 在没有街道地址的地点(例如建筑物未编号,或者街道未命名),Plus Code 可替代街道地址使用。请参阅 Open Location CodePlus Code

如需了解详情,请参阅 PlusCode

可选 数值

相应地点的价格水平,范围为 0 到 4。具体金额会因地区而异。价格水平的解读如下:

  • 0 免费
  • 1 便宜
  • 2 中度
  • 3 偏贵
  • 4 非常昂贵
可选 数值

包含根据用户总体评价得出的地点评分(从 1.0 到 5.0)。

可选 字符串
可选 布尔值

指定相应地点是否支持预订。

可选 Array<PlaceReview>

一个最多包含五条评价的 JSON 数组。默认情况下,评价会按相关性排序。使用 reviews_sort 请求参数来控制排序。

  • 对于 most_relevant(默认),评价按相关性排序;该服务会偏向于返回最初以首选语言撰写的评价。
  • 对于 newest,评价按时间顺序排序;首选语言不会影响排序顺序。

Google 建议向用户指明结果是按 most_relevant 还是 newest 排序的。

如需了解详情,请参阅 PlaceReview

可选 字符串
可选 Array<PlaceOpeningHours>

包含未来 7 天的条目数组,其中包括有关商家次要营业时间的信息。次要营业时间与商家的主要营业时间不同。例如,餐厅可以将外卖自取时间或送餐时间指定为次要营业时间。此字段会填充 type 子字段,该子字段会根据地点的类型从预定义的营业时间类型列表(例如 DRIVE_THROUGHPICKUPTAKEOUT)中提取数据。此字段包含所有小时的 special_days 子字段,针对具有特殊营业时间的日期设置。

如需了解详情,请参阅 PlaceOpeningHours

可选 布尔值

指定相应场所是否供应啤酒。

可选 布尔值

指定相应场所是否供应早餐。

可选 布尔值

指定营业地点是否供应早午餐。

可选 布尔值

指定相应场所是否提供晚餐。

可选 布尔值

指定相应场所是否提供午餐。

可选 布尔值

指定相应场所是否供应素食。

可选 布尔值

指定相应场所是否供应葡萄酒。

可选 布尔值

指定商家是否支持外卖。

可选 数组<string>

包含一个描述指定结果的地图项类型数组。请参阅支持的类型列表。

可选 字符串

包含相应地点的官方 Google 页面的网址。这是由 Google 拥有的页面,其中包含有关该地点的实用信息。在任何向用户显示该地点详细结果的界面上,应用必须提供此页面的链接或者嵌入此页面。

可选 数值

此地点的评价总数(无论是否包含文字)。

可选 数值

包含相应地点当前时区与世界协调时间 (UTC) 的分钟偏移量。例如,对于澳大利亚悉尼在夏令时期间的地点,此值为 660(比世界协调时间 (UTC) 快 11 小时);对于加利福尼亚州在非夏令时期间的地点,此值为 -480(比世界协调时间 (UTC) 慢 8 小时)。

可选 字符串

对于商家 (types:["establishment", ...])) 结果,vicinity 字段包含地点的简化地址,包括街道名称、门牌号和市行政区,但不包括省/州、邮政编码或国家/地区。

对于所有其他结果,vicinity 字段包含结果地址中最窄的政区地图项 (types:["political", ...]) 的名称。

此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。

可选 字符串

此地点的权威网站,例如商家主页。

可选 布尔值

指定场所是否有无障碍入口。

PlaceEditorialSummary

包含地点的摘要。摘要包含文本概览,还包括这些文本概览的语言代码(如适用)。摘要文本必须按原样呈现,不得修改或更改。

字段 必需 类型 说明
可选 字符串

上述字段的语言。可能不一定存在。

可选 字符串

地点的中等长度文本摘要。

PlaceOpeningHours

一个用于描述地点营业时间的对象。

字段 必需 类型 说明
可选 布尔值

一个布尔值,用于指示相应地点当前是否正在营业。

可选 Array<PlaceOpeningHoursPeriod>

一个涵盖七天的营业时段数组,从星期日开始,按时间顺序排列。

如需了解详情,请参阅 PlaceOpeningHoursPeriod

可选 数组<PlaceSpecialDay>

一个数组,最多包含 7 个条目,分别对应未来 7 天。

如需了解详情,请参阅 PlaceSpecialDay

可选 字符串

用于标识次要营业时间类型的类型字符串(例如 DRIVE_THROUGHHAPPY_HOURDELIVERYTAKEOUTKITCHENBREAKFASTLUNCHDINNERBRUNCHPICKUPSENIOR_HOURS)。仅针对 secondary_opening_hours 设置。

可选 数组<string>

一个字符串数组,以人类可读的文本描述相应地点的营业时间。

PlaceOpeningHoursPeriod

字段 必需 类型 说明
required PlaceOpeningHoursPeriodDetail

包含一对日期和时间对象,用于说明该地点的营业时段。

如需了解详情,请参阅 PlaceOpeningHoursPeriodDetail

可选 PlaceOpeningHoursPeriodDetail

可能包含一对日期和时间对象,用于说明该地点的休息时段。如果某个地点全天营业,响应中将缺少“关闭”部分。客户端可以通过以下方式表示全天营业:将营业时间段中的日期设置为 0,将时间设置为 0000,并且不包含 close

如需了解详情,请参阅 PlaceOpeningHoursPeriodDetail

PlaceSpecialDay

字段 必需 类型 说明
可选 字符串

以 RFC3339 格式表示的日期,采用相应地点的本地时区,例如 2010-12-31。

可选 布尔值

如果当天有特殊营业时间,则为 True。如果值为 true,则表示当天至少存在一个例外情况。异常会导致 current_opening_hourssecondary_opening_hours 的子字段中出现不同的值,例如 periodsweekday_textopen_now。例外情况适用于营业时间,而营业时间用于生成其他字段。

PlaceOpeningHoursPeriodDetail

字段 必需 类型 说明
required 数值

一个介于 0 到 6 之间的数字,对应于星期几(从星期日开始)。例如,2 表示星期二。

required 字符串

可能包含一天中的某个时段,采用 24 小时制 hhmm 格式。值介于 0000 到 2359 之间。系统将按地点的时区报告时间。

可选 字符串

以 RFC3339 格式表示的日期,采用相应地点的本地时区,例如 2010-12-31。

可选 布尔值

如果给定的时间段因七天截止时间而截断,则为 true;其中,时间段的开始时间早于请求日期午夜,并且/或者结束时间为最后一天午夜或之后。此属性表示开放或关闭的期限可以超过此七天截止期限。

PlacePhoto

地点的照片。可以使用 Place Photo API 通过以下格式的网址访问照片:

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=photo_reference&key=YOUR_API_KEY

如需了解详情,请参阅地点照片

字段 必需 类型 说明
required 数值

照片的高度。

required 数组<string>

照片的 HTML 提供方信息。

required 字符串

在执行照片请求时用于标识照片的字符串。

required 数值

照片的宽度。

PlaceReview

用户提交的地点评价。

字段 必需 类型 说明
required 字符串

提交评价的用户的名称。匿名评价的作者统称为“Google 用户”。

required 数值

用户对此地点的总体评分。这是一个整数,范围为 1 至 5。

required 字符串

评价提交时间(以文本形式表示,相对于当前时间)。

required 数值

提交评价的时间,以自世界协调时间 (UTC) 1970 年 1 月 1 日午夜起经过的秒数表示。

可选 字符串

指向用户 Google 地图本地向导个人资料(如果有的话)的网址。

可选 字符串

表示返回的评价所用语言的 IETF 语言代码。此字段仅包含主要语言标记,而不包含表示国家或地区的辅助标记。例如,所有英语评价都标记为“en”,而不是“en-AU”或“en-UK”等。如果只有评分而没有评价文本,则此字段为空。

可选 字符串

表示评价的原始语言的 IETF 语言代码。如果评价已翻译,则 original_language != language。此字段仅包含主要语言标记,而不包含表示国家或地区的辅助标记。例如,所有英语评价都标记为“en”,而不是“en-AU”或“en-UK”等。如果只有评分而没有评价文字,此字段为空。

可选 字符串

指向用户个人资料照片的网址(如果有)。

可选 字符串

用户的评价。通过 Google 地点评价某个位置时,文本评价被视为可选项。因此,此字段可能为空。请注意,此字段可能包含基本的 HTML 标记。例如,实体引用 &amp; 可能表示和号字符。

可选 布尔值

一个布尔值,用于指示评价是否是从撰写时使用的原始语言翻译而来的。如果评价已翻译,则此值为 true,Google 建议您向用户指明这一点。例如,您可以在评价中添加以下字符串:“由 Google 翻译”。