“查找地点(旧版)”会根据用户输入的文本返回地点。输入可以是任意类型的地点文本数据,例如名称、地址或电话号码。请求必须是字符串。使用非字符串数据(例如经纬度坐标或 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 发出“地点详情”请求。如需详细了解地点搜索请求中不可用的字段,请参阅地点 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 地址偏差。传递字符串
Find Place(旧版)示例
以下示例展示了查找“澳大利亚当代艺术博物馆”的查找地点(旧版)请求,包含的字段有 photos、formatted_address、name、rating、opening_hours 和 geometry:
网址
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
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'
以下示例展示了针对“蒙古烤肉”的“查找地点”(旧版)请求,该请求使用 locationbias 参数来优先显示指定坐标 2000 米范围内的结果:
网址
https://maps.googleapis.com/maps/api/place/findplacefromtext/json ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry &input=mongolian &inputtype=textquery &locationbias=circle%3A2000%4047.6918452%2C-122.2226413 &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=mongolian&inputtype=textquery&locationbias=circle%3A2000%4047.6918452%2C-122.2226413&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'
以下示例展示了针对电话号码的“查找地点(旧版)”请求。请注意,国际长途电话前缀“+”已编码为 %2B,以便此请求成为符合要求的网址。 如果不进行编码,服务器会将 + 前缀解码为空格,从而导致电话号码查找无效。
网址
https://maps.googleapis.com/maps/api/place/findplacefromtext/json ?input=%2B16502530000 &inputtype=phonenumber &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?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
<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
| Field | Required | Type | Description |
|---|---|---|---|
| required | Array<Place> | Contains an array of Place candidates.
Place Search requests return a subset of the fields that are
returned by Place Details requests. If the field you want is not
returned by Place Search, you can use Place Search to get a
place_id, then use that Place ID to make a Place Details request.
See Place for more information. |
| required | PlacesSearchStatus | Contains the status of the request, and may contain debugging information to help you track down why the request failed. See PlacesSearchStatus for more information. |
| optional | string |
When the service returns a status code other than
|
| optional | Array<string> |
When the service returns additional information about the request
specification, there may be an additional
|
PlacesSearchStatus
Status codes returned by service.
OKindicating the API request was successful.ZERO_RESULTSindicating that the search was successful but returned no results. This may occur if the search was passed alatlngin a remote location.INVALID_REQUESTindicating the API request was malformed, generally due to missing required query parameter (locationorradius).OVER_QUERY_LIMITindicating any of the following:- You have exceeded the QPS limits.
- Billing has not been enabled on your account.
- The monthly $200 credit, or a self-imposed usage cap, has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
REQUEST_DENIEDindicating that your request was denied, generally because:- The request is missing an API key.
- The
keyparameter is invalid.
UNKNOWN_ERRORindicating an unknown error.
Place
Attributes describing a place. Not all attributes will be available for all place types.
| Field | Required | Type | Description |
|---|---|---|---|
| optional | Array<AddressComponent> | An array containing the separate components applicable to this address. See AddressComponent for more information. |
| optional | string | A representation of the place's address in the adr microformat. |
| optional | string |
Indicates the operational status of the place, if it is a business.
If no data exists,
The allowed values include: OPERATIONAL,
CLOSED_TEMPORARILY, and CLOSED_PERMANENTLY |
| optional | boolean | Specifies if the business supports curbside pickup. |
| optional | PlaceOpeningHours |
Contains the hours of operation for the next seven days (including
today). The time period starts at midnight on the date of the
request and ends at 11:59 pm six days later. This field includes the
See PlaceOpeningHours for more information. |
| optional | boolean | Specifies if the business supports delivery. |
| optional | boolean | Specifies if the business supports indoor or outdoor seating options. |
| optional | PlaceEditorialSummary | Contains a summary of the place. A summary is comprised of a textual overview, and also includes the language code for these if applicable. Summary text must be presented as-is and can not be modified or altered. See PlaceEditorialSummary for more information. |
| optional | string | A string containing the human-readable address of this place. Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions. The formatted address is logically composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state). Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field. |
| optional | string | Contains the place's phone number in its local format. |
| optional | Geometry | Contains the location and viewport for the location. See Geometry for more information. |
| optional | string | Contains the URL of a suggested icon which may be displayed to the user when indicating this result on a map. |
| optional | string | Contains the default HEX color code for the place's category. |
| optional | string |
Contains the URL of a recommended icon, minus the
|
| optional | string |
Contains the place's phone number in international format.
International format includes the country code, and is prefixed with
the plus, +, sign. For example, the international_phone_number for
Google's Sydney, Australia office is |
| optional | string |
Contains the human-readable name for the returned result. For
|
| optional | PlaceOpeningHours | Contains the regular hours of operation. See PlaceOpeningHours for more information. |
| optional | boolean |
Use |
| optional | Array<PlacePhoto> | An array of photo objects, each containing a reference to an image. A request may return up to ten photos. More information about place photos and how you can use the images in your application can be found in the Place Photos documentation. See PlacePhoto for more information. |
| optional | string |
A textual identifier that uniquely identifies a place. To retrieve
information about the place, pass this identifier in the
|
| optional | PlusCode | An encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See Open Location Code and plus codes. See PlusCode for more information. |
| optional | number | The price level of the place, on a scale of 0 to 4. The exact amount indicated by a specific value will vary from region to region. Price levels are interpreted as follows:
|
| optional | number | Contains the place's rating, from 1.0 to 5.0, based on aggregated user reviews. |
| optional | string | |
| optional | boolean | Specifies if the place supports reservations. |
| optional | Array<PlaceReview> |
A JSON array of up to five reviews. By default, the reviews are
sorted in order of relevance. Use the
Google recommends indicating to users whether results are ordered by
See PlaceReview for more information. |
| optional | string | |
| optional | Array<PlaceOpeningHours> |
Contains an array of entries for the next seven days including
information about secondary hours of a business. Secondary hours are
different from a business's main hours. For example, a restaurant
can specify drive through hours or delivery hours as its secondary
hours. This field populates the See PlaceOpeningHours for more information. |
| optional | boolean | Specifies if the place serves beer. |
| optional | boolean | Specifies if the place serves breakfast. |
| optional | boolean | Specifies if the place serves brunch. |
| optional | boolean | Specifies if the place serves dinner. |
| optional | boolean | Specifies if the place serves lunch. |
| optional | boolean | Specifies if the place serves vegetarian food. |
| optional | boolean | Specifies if the place serves wine. |
| optional | boolean | Specifies if the business supports takeout. |
| optional | Array<string> | Contains an array of feature types describing the given result. See the list of supported types. |
| optional | string | Contains the URL of the official Google page for this place. This will be the Google-owned page that contains the best available information about the place. Applications must link to or embed this page on any screen that shows detailed results about the place to the user. |
| optional | number | The total number of reviews, with or without text, for this place. |
| optional | number | Contains the number of minutes this place’s current timezone is offset from UTC. For example, for places in Sydney, Australia during daylight saving time this would be 660 (+11 hours from UTC), and for places in California outside of daylight saving time this would be -480 (-8 hours from UTC). |
| optional | string |
For establishment (
For all other results, the This content is meant to be read as-is. Do not programmatically parse the formatted address. |
| optional | string | The authoritative website for this place, such as a business' homepage. |
| optional | boolean | Specifies if the place has an entrance that is wheelchair-accessible. |
AddressComponent
| Field | Required | Type | Description |
|---|---|---|---|
| required | string | The full text description or name of the address component as returned by the Geocoder. |
| required | string | An abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation. |
| required | Array<string> | An array indicating the type of the address component. See the list of supported types. |
PlaceEditorialSummary
Contains a summary of the place. A summary is comprised of a textual overview, and also includes the language code for these if applicable. Summary text must be presented as-is and can not be modified or altered.
| Field | Required | Type | Description |
|---|---|---|---|
| optional | string | The language of the previous fields. May not always be present. |
| optional | string | A medium-length textual summary of the place. |
Geometry
An object describing the location.
| Field | Required | Type | Description |
|---|---|---|---|
| required | LatLngLiteral | See LatLngLiteral for more information. |
| required | Bounds | See Bounds for more information. |
LatLngLiteral
An object describing a specific location with Latitude and Longitude in decimal degrees.
| Field | Required | Type | Description |
|---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |
Bounds
A rectangle in geographical coordinates from points at the southwest and northeast corners.
| Field | Required | Type | Description |
|---|---|---|---|
| required | LatLngLiteral | See LatLngLiteral for more information. |
| required | LatLngLiteral | See LatLngLiteral for more information. |
PlaceOpeningHours
An object describing the opening hours of a place.
| Field | Required | Type | Description |
|---|---|---|---|
| optional | boolean | A boolean value indicating if the place is open at the current time. |
| optional | Array<PlaceOpeningHoursPeriod> | An array of opening periods covering seven days, starting from Sunday, in chronological order. See PlaceOpeningHoursPeriod for more information. |
| optional | Array<PlaceSpecialDay> | An array of up to seven entries corresponding to the next seven days. See PlaceSpecialDay for more information. |
| optional | string |
A type string used to identify the type of secondary hours (for
example, |
| optional | Array<string> | An array of strings describing in human-readable text the hours of the place. |
PlaceOpeningHoursPeriod
| Field | Required | Type | Description |
|---|---|---|---|
| required | PlaceOpeningHoursPeriodDetail | Contains a pair of day and time objects describing when the place opens. See PlaceOpeningHoursPeriodDetail for more information. |
| optional | PlaceOpeningHoursPeriodDetail |
May contain a pair of day and time objects describing when the place
closes. If a place is always open, the close section will be missing
from the response. Clients can rely on always-open being represented
as an open period containing day with value See PlaceOpeningHoursPeriodDetail for more information. |
PlaceSpecialDay
| Field | Required | Type | Description |
|---|---|---|---|
| optional | string | A date expressed in RFC3339 format in the local timezone for the place, for example 2010-12-31. |
| optional | boolean |
True if there are exceptional hours for this day. If
|
PlaceOpeningHoursPeriodDetail
| Field | Required | Type | Description |
|---|---|---|---|
| required | number | A number from 0–6, corresponding to the days of the week, starting on Sunday. For example, 2 means Tuesday. |
| required | string | May contain a time of day in 24-hour hhmm format. Values are in the range 0000–2359. The time will be reported in the place’s time zone. |
| optional | string | A date expressed in RFC3339 format in the local timezone for the place, for example 2010-12-31. |
| optional | boolean | True if a given period was truncated due to a seven-day cutoff, where the period starts before midnight on the date of the request and/or ends at or after midnight on the last day. This property indicates that the period for open or close can extend past this seven-day cutoff. |
PlacePhoto
A photo of a Place. The photo can be accesed via the Place Photo API using an url in the following pattern:
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=photo_reference&key=YOUR_API_KEY
See Place Photos for more information.
| Field | Required | Type | Description |
|---|---|---|---|
| required | number | The height of the photo. |
| required | Array<string> | The HTML attributions for the photo. |
| required | string | A string used to identify the photo when you perform a Photo request. |
| required | number | The width of the photo. |
PlusCode
An encoded location reference, derived from latitude and longitude coordinates, that represents an area, 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named).
| Field | Required | Type | Description |
|---|---|---|---|
| required | string |
The |
| optional | string |
The |
PlaceReview
A review of the place submitted by a user.
| Field | Required | Type | Description |
|---|---|---|---|
| required | string | The name of the user who submitted the review. Anonymous reviews are attributed to "A Google user". |
| required | number | The user's overall rating for this place. This is a whole number, ranging from 1 to 5. |
| required | string | The time that the review was submitted in text, relative to the current time. |
| required | number | The time that the review was submitted, measured in the number of seconds since since midnight, January 1, 1970 UTC. |
| optional | string | The URL to the user's Google Maps Local Guides profile, if available. |
| optional | string | An IETF language code indicating the language of the returned review.This field contains the main language tag only, and not the secondary tag indicating country or region. For example, all the English reviews are tagged as 'en', and not 'en-AU' or 'en-UK' and so on.This field is empty if there is only a rating with no review text. |
| optional | string |
An IETF language code indicating the original language of the
review. If the review has been translated, then
|
| optional | string | The URL to the user's profile photo, if available. |
| optional | string |
The user's review. When reviewing a location with Google Places,
text reviews are considered optional. Therefore, this field may be
empty. Note that this field may include simple HTML markup. For
example, the entity reference |
| optional | boolean | A boolean value indicating if the review was translated from the original language it was written in.If a review has been translated, corresponding to a value of true, Google recommends that you indicate this to your users. For example, you can add the following string, “Translated by Google”, to the review. |