“查找地点(旧版)”会根据用户输入的文本返回地点。输入可以是任意类型的地点文本数据,例如名称、地址或电话号码。请求必须是字符串。使用非字符串数据(例如经纬度坐标或 Plus 代码)的“查找地点(旧版)”请求会生成错误。
“查找地点”(旧版)请求
“查找地点”(旧版)请求采用以下形式的 HTTP 网址:
https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters
其中,output 可以是以下任一值:
json(推荐)表示以 JavaScript 对象表示法 (JSON) 格式输出xml表示以 XML 格式输出
您需要提供某些参数才能发起“查找地点(旧版)”请求。依照网址的标准,所有参数都使用“与”符号 (&) 分隔。
必需参数
-
输入
要用作搜索条件的文本字符串,例如“餐馆”或“长安街 123 号”。该参数必须是地点名称、地址或场所类别。任何其他类型的输入都可能产生错误,并且不能保证返回有效结果。Places API 将根据此字符串返回候选匹配结果,并按照其判断的相关性对结果进行排序。
-
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 的范围内。
-
IP 偏差:指示 API 使用 IP 地址偏差。传递字符串
查找地点(旧版)示例
以下示例展示了查找“澳大利亚当代艺术博物馆”的查找地点(旧版)请求,包含的字段有 photos、formatted_address、name、rating、opening_hours 和 geometry:
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_address、geometry、name、opening_hours、photos、rating 字段。
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。 |
|
可选 | 字符串 |
当服务返回的状态代码不是 |
|
可选 | 数组<string> |
当服务返回有关请求规范的其他信息时,响应对象中可能会包含额外的 |
PlacesSearchStatus
服务返回的状态代码。
OK:表示 API 请求成功。-
ZERO_RESULTS表示搜索成功,但未返回任何结果。如果搜索传递了远程位置中的latlng,就可能会发生这种情况。 -
INVALID_REQUEST表示 API 请求格式有误,通常是因为缺少必需的查询参数(location或radius)。 -
OVER_QUERY_LIMIT表示以下任一情况:- 您已超出 QPS 限额。
- 您的账号尚未启用结算功能。
- 超出了每月 200 美元的赠金或您设定的用量上限。
- 提供的付款方式不再有效(例如,信用卡已过期)。
-
REQUEST_DENIED表示您的请求已遭拒,通常是因为:- 请求中缺少 API 密钥。
key参数无效。
UNKNOWN_ERROR:表示出现未知错误。
地点
描述地点的属性。并非所有属性都适用于所有地点类型。
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
|
可选 |
Array<AddressComponent>
|
一个数组,其中包含适用于相应地址的各个组成部分。
如需了解详情,请参阅 |
|
可选 | 字符串 |
以 adr 微格式表示的地点地址。 |
|
可选 | 字符串 |
表示地点的营业状态(如果该地点为商家)。
如果不存在任何数据,将不会返回
The allowed values include:
OPERATIONAL,
CLOSED_TEMPORARILY, and CLOSED_PERMANENTLY
|
|
可选 | 布尔值 |
指定商家是否支持路边取货。 |
|
可选 | PlaceOpeningHours |
包含未来 7 天(包括今天)的营业时间。时间段从请求当天的午夜开始,到六天后的晚上 11:59 结束。此字段包含所有营业时间的 如需了解详情,请参阅 PlaceOpeningHours。 |
|
可选 | 布尔值 |
指定商家是否支持配送。 |
|
可选 | 布尔值 |
指定商家是否支持室内或室外座位选项。 |
|
可选 | PlaceEditorialSummary |
包含地点的摘要。摘要包含文本概览,如果适用,还包含这些文本概览的语言代码。摘要文字必须按原样呈现,不得修改或更改。 如需了解详情,请参阅 PlaceEditorialSummary。 |
|
可选 | 字符串 |
一个字符串,包含此地点直观易懂的地址。 此地址通常相当于邮政地址。请注意,由于许可限制,某些国家/地区(例如英国)不允许发布真实的邮政地址。 设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下组成部分:“111”(门牌号)、“8th Avenue”(路由)、“New York”(城市)和“NY”(美国州名)。 请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分,API 响应除了包含设有格式的地址字段外,还包含这些组成部分。 |
|
可选 | 字符串 |
包含地点的电话号码(采用本地格式)。 |
|
可选 | Geometry |
包含相应位置的位置和视口。 如需了解详情,请参阅 |
|
可选 | 字符串 |
包含建议的图标的网址,该图标可能会在地图上显示此结果时向用户显示。 |
|
可选 | 字符串 |
包含地点类别的默认十六进制颜色代码。 |
|
可选 | 字符串 |
包含建议图标的网址,但不含 |
|
可选 | 字符串 |
包含地点的电话号码(采用国际电话号码格式)。
国际电话号码格式包含国家/地区代码,并且带有一个加号 (+) 前缀。例如,Google 澳大利亚悉尼办事处的 international_phone_number 为 |
|
可选 | 字符串 |
包含返回结果的简单易懂的名称。对于 |
|
可选 | PlaceOpeningHours |
包含正常营业时间。 如需了解详情,请参阅 PlaceOpeningHours。 |
|
可选 | 布尔值 |
使用 |
|
可选 | 数组<PlacePhoto> |
照片对象数组,每个对象都包含对图片的引用。 一个请求最多可返回 10 张照片。如需详细了解地点照片以及如何在应用中使用这些图片,请参阅地点照片文档。 如需了解详情,请参阅 PlacePhoto。 |
|
可选 | 字符串 |
唯一标识地点的文本标识符。如需检索地点的相关信息,请在 Places API 请求的 |
|
可选 | PlusCode |
经过编码的位置引用,衍生自纬度和经度坐标,表示面积不超过 1/8, 000 度 x 1/8, 000 度(在赤道处约为 14 米 x 14 米)的区域。 在没有街道地址的地点(例如建筑物未编号,或者街道未命名),Plus Code 可替代街道地址使用。请参阅 Open Location Code 和 Plus Code。 如需了解详情,请参阅 |
|
可选 | 数值 |
相应地点的价格水平,范围为 0 到 4。具体金额会因地区而异。价格水平的解读如下:
|
|
可选 | 数值 |
包含根据用户总体评价得出的地点评分(从 1.0 到 5.0)。 |
|
可选 | 字符串 | |
|
可选 | 布尔值 |
指定相应地点是否支持预订。 |
|
可选 | Array<PlaceReview> |
一个最多包含五条评价的 JSON 数组。默认情况下,评价会按相关性排序。使用
Google 建议向用户指明结果是按 如需了解详情,请参阅 PlaceReview。 |
|
可选 | 字符串 | |
|
可选 | Array<PlaceOpeningHours> |
包含未来 7 天的条目数组,其中包括有关商家次要营业时间的信息。次要营业时间与商家的主要营业时间不同。例如,餐厅可以将外卖自取时间或送餐时间指定为次要营业时间。此字段会填充 如需了解详情,请参阅 PlaceOpeningHours。 |
|
可选 | 布尔值 |
指定相应场所是否供应啤酒。 |
|
可选 | 布尔值 |
指定相应场所是否供应早餐。 |
|
可选 | 布尔值 |
指定营业地点是否供应早午餐。 |
|
可选 | 布尔值 |
指定相应场所是否提供晚餐。 |
|
可选 | 布尔值 |
指定相应场所是否提供午餐。 |
|
可选 | 布尔值 |
指定相应场所是否供应素食。 |
|
可选 | 布尔值 |
指定相应场所是否供应葡萄酒。 |
|
可选 | 布尔值 |
指定商家是否支持外卖。 |
|
可选 | 数组<string> |
包含一个描述指定结果的地图项类型数组。请参阅支持的类型列表。 |
|
可选 | 字符串 |
包含相应地点的官方 Google 页面的网址。这是由 Google 拥有的页面,其中包含有关该地点的实用信息。在任何向用户显示该地点详细结果的界面上,应用必须提供此页面的链接或者嵌入此页面。 |
|
可选 | 数值 |
此地点的评价总数(无论是否包含文字)。 |
|
可选 | 数值 |
包含相应地点当前时区与世界协调时间 (UTC) 的分钟偏移量。例如,对于澳大利亚悉尼在夏令时期间的地点,此值为 660(比世界协调时间 (UTC) 快 11 小时);对于加利福尼亚州在非夏令时期间的地点,此值为 -480(比世界协调时间 (UTC) 慢 8 小时)。 |
|
可选 | 字符串 |
对于商家 (
对于所有其他结果, 此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。 |
|
可选 | 字符串 |
此地点的权威网站,例如商家主页。 |
|
可选 | 布尔值 |
指定场所是否有无障碍入口。 |
PlaceEditorialSummary
包含地点的摘要。摘要包含文本概览,还包括这些文本概览的语言代码(如适用)。摘要文本必须按原样呈现,不得修改或更改。
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
|
可选 | 字符串 |
上述字段的语言。可能不一定存在。 |
|
可选 | 字符串 |
地点的中等长度文本摘要。 |
PlaceOpeningHours
一个用于描述地点营业时间的对象。
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
|
可选 | 布尔值 |
一个布尔值,用于指示相应地点当前是否正在营业。 |
|
可选 | Array<PlaceOpeningHoursPeriod> |
一个涵盖七天的营业时段数组,从星期日开始,按时间顺序排列。 如需了解详情,请参阅 PlaceOpeningHoursPeriod。 |
|
可选 | 数组<PlaceSpecialDay> |
一个数组,最多包含 7 个条目,分别对应未来 7 天。 如需了解详情,请参阅 PlaceSpecialDay。 |
|
可选 | 字符串 |
用于标识次要营业时间类型的类型字符串(例如 |
|
可选 | 数组<string> |
一个字符串数组,以人类可读的文本描述相应地点的营业时间。 |
PlaceOpeningHoursPeriod
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
|
required | PlaceOpeningHoursPeriodDetail |
包含一对日期和时间对象,用于说明该地点的营业时段。 如需了解详情,请参阅 PlaceOpeningHoursPeriodDetail。 |
|
可选 | PlaceOpeningHoursPeriodDetail |
可能包含一对日期和时间对象,用于说明该地点的休息时段。如果某个地点全天营业,响应中将缺少“关闭”部分。客户端可以通过以下方式表示全天营业:将营业时间段中的日期设置为 如需了解详情,请参阅 PlaceOpeningHoursPeriodDetail。 |
PlaceSpecialDay
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
|
可选 | 字符串 |
以 RFC3339 格式表示的日期,采用相应地点的本地时区,例如 2010-12-31。 |
|
可选 | 布尔值 |
如果当天有特殊营业时间,则为 True。如果值为 |
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 语言代码。如果评价已翻译,则 |
|
可选 | 字符串 |
指向用户个人资料照片的网址(如果有)。 |
|
可选 | 字符串 |
用户的评价。通过 Google 地点评价某个位置时,文本评价被视为可选项。因此,此字段可能为空。请注意,此字段可能包含基本的 HTML 标记。例如,实体引用 |
|
可选 | 布尔值 |
一个布尔值,用于指示评价是否是从撰写时使用的原始语言翻译而来的。如果评价已翻译,则此值为 true,Google 建议您向用户指明这一点。例如,您可以在评价中添加以下字符串:“由 Google 翻译”。 |