The Places API lets you search for place information using a variety of categories, including establishments, prominent points of interest, and geographic locations. You can search for places either by proximity or a text string. A Place Search returns a list of places along with summary information about each place; additional information is available via a Place Details query.
Find Place requests
A Find Place request takes a text input and returns a place. The input can be any kind of Places text data, such as a name, address, or phone number. The request must be a string. A Find Place request using non-string data such as a lat/lng coordinate or plus code generates an error.
A Find Place request is an HTTP URL of the following form:
https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters
where output
may be either of the following values:
json
(recommended) indicates output in JavaScript Object Notation (JSON)xml
indicates output as XML
Certain parameters are required to initiate a Find Place request. As is
standard in URLs, all parameters are separated using the ampersand
(&
) character.
Required parameters
key
— Your application's API key. This key identifies your application. See Get a key for more information.input
— Text input that identifies the search target, such as a name, address, or phone number. The input must be a string. Non-string input such as a lat/lng coordinate or plus code generates an error.inputtype
— The type of input. This can be one of eithertextquery
orphonenumber
. Phone numbers must be in international format (prefixed by a plus sign ("+"), followed by the country code, then the phone number itself). See E.164 ITU recommendation for more information.
Optional parameters
language
— The language code, indicating in which language the results should be returned, if possible. Searches are also biased to the selected language; results in the selected language may be given a higher ranking. See the list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive.-
fields
— The fields specifying the types of place data to return, separated by a comma. -
locationbias
— Prefer results in a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle. If this parameter is not specified, the API uses IP address biasing by default.- IP bias: Instructs the API to use IP address biasing. Pass the
string
ipbias
(this option has no additional parameters). - Point: A single lat/lng coordinate. Use the following format:
point:lat,lng
. - Circular: A string specifying radius in meters, plus lat/lng in
decimal degrees.
Use the following format:circle:radius@lat,lng
. - Rectangular: A string specifying two lat/lng pairs in decimal
degrees, representing the south/west and north/east points of a
rectangle. Use the following format:
rectangle:south,west|north,east
. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.
- IP bias: Instructs the API to use IP address biasing. Pass the
string
Fields
Use the fields
parameter to specify a comma-separated list of
place data types to return. For example: fields=opening_hours,icon,geometry
.
Use a forward slash when specifying compound values. For example: geometry/location
.
Fields correspond to Place Search results, and are divided
into three billing categories: Basic, Contact, and Atmosphere. Basic fields are
billed at base rate, and incur no additional charges. Contact and Atmosphere
fields are billed at a higher rate. See the pricing sheet
for more information. Attributions (html_attributions
) are always
returned with every call, regardless of whether the field has been
requested.
Basic
The Basic category includes the following fields:
formatted_address
, geometry
, icon
,name
,
permanently_closed
, photos
, place_id
,plus_code
,
types
Contact
The Contact category includes the following field:opening_hours
(Place Search returns only
open_now
; use a Place Details request to get the
full opening_hours
results).
Atmosphere
The Atmosphere category includes the following fields:price_level
, rating
, user_ratings_total
Find Place examples
The following example shows a Find Place request for "Museum of Contemporary
Art Australia", including the photos
,
formatted_address
, name
, rating
,
opening_hours
, and geometry
fields:
https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=photos,formatted_address,name,rating,opening_hours,geometry&key=YOUR_API_KEY
The following example shows a Find Place request for "Mongolian Grill",
using the locationbias
parameter to prefer results within
2000 meters of the specified coordinates:
https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=mongolian%20grill&inputtype=textquery&fields=photos,formatted_address,name,opening_hours,rating&locationbias=circle:2000@47.6918452,-122.2226413&key=YOUR_API_KEY
The following example shows a Find Place request for a phone number. Note that the international call prefix "+" has been encoded to %2B so that this request is a compliant URL. Left unencoded, the + prefix would be decoded to a space on the server, resulting in an invalid phone number lookup.
https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B61293744000&inputtype=phonenumber&fields=place_id&key=YOUR_API_KEY
Nearby Search requests
A Nearby Search lets you search for places within a specified area. You can refine your search request by supplying keywords or specifying the type of place you are searching for.
A Nearby Search request is an HTTP URL of the following form:
https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters
where output
may be either of the following values:
json
(recommended) indicates output in JavaScript Object Notation (JSON)xml
indicates output as XML
Certain parameters are required to initiate a Nearby Search request. As is
standard in URLs, all parameters are separated using the ampersand
(&
) character.
Required parameters
key
— Your application's API key. This key identifies your application. See Get a key for more information.location
— The latitude/longitude around which to retrieve place information. This must be specified as latitude,longitude.radius
— Defines the distance (in meters) within which to return place results. The maximum allowed radius is 50 000 meters. Note thatradius
must not be included ifrankby=distance
(described under Optional parameters below) is specified.- If
rankby=distance
(described under Optional parameters below) is specified, then one or more ofkeyword
,name
, ortype
is required.
Optional parameters
keyword
— A term to be matched against all content that Google has indexed for this place, including but not limited to name, type, and address, as well as customer reviews and other third-party content.language
— The language code, indicating in which language the results should be returned, if possible. See the list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive.minprice
andmaxprice
(optional) — Restricts results to only those places within the specified range. Valid values range between 0 (most affordable) to 4 (most expensive), inclusive. The exact amount indicated by a specific value will vary from region to region.name
— A term to be matched against all content that Google has indexed for this place. Equivalent tokeyword
. Thename
field is no longer restricted to place names. Values in this field are combined with values in thekeyword
field and passed as part of the same search string. We recommend using only thekeyword
parameter for all search terms.opennow
— Returns only those places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query.rankby
— Specifies the order in which results are listed. Note thatrankby
must not be included ifradius
(described under Required parameters above) is specified. Possible values are:prominence
(default). This option sorts results based on their importance. Ranking will favor prominent places within the specified area. Prominence can be affected by a place's ranking in Google's index, global popularity, and other factors.distance
. This option biases search results in ascending order by their distance from the specifiedlocation
. Whendistance
is specified, one or more ofkeyword
,name
, ortype
is required.
type
— Restricts the results to places matching the specified type. Only one type may be specified (if more than one type is provided, all types following the first entry are ignored). See the list of supported types.pagetoken
— Returns up to 20 results from a previously run search. Setting apagetoken
parameter will execute a search with the same parameters used previously — all parameters other thanpagetoken
will be ignored.
Note for Google Maps APIs Premium Plan customers: You must include an
API key in your requests. You should not include a client
or
signature
parameter with your requests.
Nearby search example
The following example is a search request for places of type 'restaurant' within a 1500m radius of a point in Sydney, Australia, containing the word 'cruise':
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY
Note: In this example, you need to replace the key
with your own API key in order for the request to work in your application.
Text Search requests
The Google Places API Text Search Service is a web service that returns information about a set of places based on a string — for example "pizza in New York" or "shoe stores near Ottawa" or "123 Main Street". The service responds with a list of places matching the text string and any location bias that has been set.
The service is especially useful for making ambiguous address queries in an automated system, and non-address components of the string may match businesses as well as addresses. Examples of ambiguous address queries are incomplete addresses, poorly formatted addresses, or a request that includes non-address components such as business names.
The search response will include a list of places. You can send a Place Details request for more information about any of the places in the response.
A Text Search request is an HTTP URL of the following form:
https://maps.googleapis.com/maps/api/place/textsearch/output?parameters
where output
may be either of the following values:
json
(recommended) indicates output in JavaScript Object Notation (JSON)xml
indicates output as XML
Certain parameters are required to initiate a search request. As is
standard in URLs, all parameters are separated using the ampersand
(&
) character.
Required parameters
query
— The text string on which to search, for example: "restaurant" or "123 Main Street". The Google Places service will return candidate matches based on this string and order the results based on their perceived relevance. This parameter becomes optional if thetype
parameter is also used in the search request.key
— Your application's API key. This key identifies your application. See Get a key for Places API to see how to create an API Project and obtain your key.
Optional parameters
region
— The region code, specified as a ccTLD (country code top-level domain) two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some exceptions. This parameter will only influence, not fully restrict, search results. If more relevant results exist outside of the specified region, they may be included. When this parameter is used, the country name is omitted from the resultingformatted_address
for results in the specified region.location
— The latitude/longitude around which to retrieve place information. This must be specified as latitude,longitude. If you specify alocation
parameter, you must also specify aradius
parameter.radius
— Defines the distance (in meters) within which to bias place results. The maximum allowed radius is 50 000 meters. Results inside of this region will be ranked higher than results outside of the search circle; however, prominent results from outside of the search radius may be included.language
— The language code, indicating in which language the results should be returned, if possible. See the list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive.minprice
andmaxprice
(optional) — Restricts results to only those places within the specified price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive), inclusive. The exact amount indicated by a specific value will vary from region to region.opennow
— Returns only those places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query.pagetoken
— Returns up to 20 results from a previously run search. Setting apagetoken
parameter will execute a search with the same parameters used previously — all parameters other thanpagetoken
will be ignored.type
— Restricts the results to places matching the specified type. Only one type may be specified (if more than one type is provided, all types following the first entry are ignored). See the list of supported types.
You may bias results to a specified circle by passing a
location
and a radius
parameter. This will
instruct the Google Places service to prefer showing results within that
circle. Results outside the defined area may still be displayed.
Biasing results to a region or circle is recommended to improve
relevance of results for otherwise ambiguous queries.
Note for Google Maps APIs Premium Plan customers: You must include an
API key in your requests. You should not include a client
or
signature
parameter with your requests.
Text search examples
Note: In these examples, you need to replace the key
with your
own API key in order for the request to work in your application.
Example 1: The following example shows a search for restaurants near Sydney.
https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&key=YOUR_API_KEY
Example 2: The following example shows a search for an incomplete address, in this case, a street address that does not include a city or state or country.
https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&key=YOUR_API_KEY
Example 3: The following example shows a search for the same
incomplete address in sample 2, and includes location
and
radius
parameters to bias the results to a region of interest.
Compare the results of sample 2 to sample 3.
https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&location=42.3675294,-71.186966&radius=10000&key=YOUR_API_KEY
Search responses
Search responses are returned in the format indicated by the
output
flag within the URL request's path.
Find Place responses
A Find Place response contains only the data types that were specified using
the fields parameter, plus
html_attributions
. The following example shows the response for a
Find Place request for "Museum of Contemporary Art Australia", including the
formatted_address
, geometry
, name
,
opening_hours
, photos
, rating
fields.
{ "candidates" : [ { "formatted_address" : "140 George St, The Rocks NSW 2000, Australia", "geometry" : { "location" : { "lat" : -33.8599358, "lng" : 151.2090295 }, "viewport" : { "northeast" : { "lat" : -33.85824767010727, "lng" : 151.2102470798928 }, "southwest" : { "lat" : -33.86094732989272, "lng" : 151.2075474201073 } } }, "name" : "Museum of Contemporary Art Australia", "opening_hours" : { "open_now" : false, "weekday_text" : [] }, "photos" : [ { "height" : 2268, "html_attributions" : [ "\u003ca href=\"https://maps.google.com/maps/contrib/113202928073475129698/photos\"\u003eEmily Zimny\u003c/a\u003e" ], "photo_reference" : "CmRaAAAAfxSORBfVmhZcERd-9eC5X1x1pKQgbmunjoYdGp4dYADIqC0AXVBCyeDNTHSL6NaG7-UiaqZ8b3BI4qZkFQKpNWTMdxIoRbpHzy-W_fntVxalx1MFNd3xO27KF3pkjYvCEhCd--QtZ-S087Sw5Ja_2O3MGhTr2mPMgeY8M3aP1z4gKPjmyfxolg", "width" : 4032 } ], "rating" : 4.3 } ], "debug_log" : { "line" : [] }, "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.8609473</lat> <lng>151.2075474</lng> </southwest> <northeast> <lat>-33.8582477</lat> <lng>151.2102471</lng> </northeast> </viewport> </geometry> <rating>4.3</rating> <opening_hours> <open_now>false</open_now> </opening_hours> <photo> <photo_reference>CmRaAAAAyyESUGLM19Zku11GDDSlh8lUZ_uxTnyg0dRj6q5AOE0ALmEOsYcNHBt3xhkM9A1PLD9D2TtXKX4SoGN2lACxurbRvdDTEbnH_FIrwAXbhLhVAURUHju9r3TZKKxvhMpbEhBnTFUq_91WtUzpDWNds4CBGhRriCKUYVVRa6PhFSoCxCAi0qbSiA</photo_reference> <width>4032</width> <height>2268</height> <html_attribution> <a href="https://maps.google.com/maps/contrib/113202928073475129698/photos">Emily Zimny</a> </html_attribution> </photo> </candidates> <status>OK</status> <debug_log /> </FindPlaceFromTextResponse>
Nearby Search and Text Search responses
The following example shows a Nearby Search response. A Text Search
response is similar, except that it returns a formatted_address
instead of a vicinity
property.
{ "html_attributions" : [], "results" : [ { "geometry" : { "location" : { "lat" : -33.870775, "lng" : 151.199025 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png", "id" : "21a0b251c9b8392186142c798263e289fe45b4aa", "name" : "Rhythmboat Cruises", "opening_hours" : { "open_now" : true }, "photos" : [ { "height" : 270, "html_attributions" : [], "photo_reference" : "CnRnAAAAF-LjFR1ZV93eawe1cU_3QNMCNmaGkowY7CnOf-kcNmPhNnPEG9W979jOuJJ1sGr75rhD5hqKzjD8vbMbSsRnq_Ni3ZIGfY6hKWmsOf3qHKJInkm4h55lzvLAXJVc-Rr4kI9O1tmIblblUpg2oqoq8RIQRMQJhFsTr5s9haxQ07EQHxoUO0ICubVFGYfJiMUPor1GnIWb5i8", "width" : 519 } ], "place_id" : "ChIJyWEHuEmuEmsRm9hTkapTCrk", "reference" : "CoQBdQAAAFSiijw5-cAV68xdf2O18pKIZ0seJh03u9h9wk_lEdG-cP1dWvp_QGS4SNCBMk_fB06YRsfMrNkINtPez22p5lRIlj5ty_HmcNwcl6GZXbD2RdXsVfLYlQwnZQcnu7ihkjZp_2gk1-fWXql3GQ8-1BEGwgCxG-eaSnIJIBPuIpihEhAY1WYdxPvOWsPnb2-nGb6QGhTipN0lgaLpQTnkcMeAIEvCsSa0Ww", "types" : [ "travel_agency", "restaurant", "food", "establishment" ], "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney" }, { "geometry" : { "location" : { "lat" : -33.866891, "lng" : 151.200814 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png", "id" : "45a27fd8d56c56dc62afc9b49e1d850440d5c403", "name" : "Private Charter Sydney Habour Cruise", "photos" : [ { "height" : 426, "html_attributions" : [], "photo_reference" : "CnRnAAAAL3n0Zu3U6fseyPl8URGKD49aGB2Wka7CKDZfamoGX2ZTLMBYgTUshjr-MXc0_O2BbvlUAZWtQTBHUVZ-5Sxb1-P-VX2Fx0sZF87q-9vUt19VDwQQmAX_mjQe7UWmU5lJGCOXSgxp2fu1b5VR_PF31RIQTKZLfqm8TA1eynnN4M1XShoU8adzJCcOWK0er14h8SqOIDZctvU", "width" : 640 } ], "place_id" : "ChIJqwS6fjiuEmsRJAMiOY9MSms", "reference" : "CpQBhgAAAFN27qR_t5oSDKPUzjQIeQa3lrRpFTm5alW3ZYbMFm8k10ETbISfK9S1nwcJVfrP-bjra7NSPuhaRulxoonSPQklDyB-xGvcJncq6qDXIUQ3hlI-bx4AxYckAOX74LkupHq7bcaREgrSBE-U6GbA1C3U7I-HnweO4IPtztSEcgW09y03v1hgHzL8xSDElmkQtRIQzLbyBfj3e0FhJzABXjM2QBoUE2EnL-DzWrzpgmMEulUBLGrtu2Y", "types" : [ "restaurant", "food", "establishment" ], "vicinity" : "Australia" }, { "geometry" : { "location" : { "lat" : -33.870943, "lng" : 151.190311 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png", "id" : "30bee58f819b6c47bd24151802f25ecf11df8943", "name" : "Bucks Party Cruise", "opening_hours" : { "open_now" : true }, "photos" : [ { "height" : 600, "html_attributions" : [], "photo_reference" : "CnRnAAAA48AX5MsHIMiuipON_Lgh97hPiYDFkxx_vnaZQMOcvcQwYN92o33t5RwjRpOue5R47AjfMltntoz71hto40zqo7vFyxhDuuqhAChKGRQ5mdO5jv5CKWlzi182PICiOb37PiBtiFt7lSLe1SedoyrD-xIQD8xqSOaejWejYHCN4Ye2XBoUT3q2IXJQpMkmffJiBNftv8QSwF4", "width" : 800 } ], "place_id" : "ChIJLfySpTOuEmsRsc_JfJtljdc", "reference" : "CoQBdQAAANQSThnTekt-UokiTiX3oUFT6YDfdQJIG0ljlQnkLfWefcKmjxax0xmUpWjmpWdOsScl9zSyBNImmrTO9AE9DnWTdQ2hY7n-OOU4UgCfX7U0TE1Vf7jyODRISbK-u86TBJij0b2i7oUWq2bGr0cQSj8CV97U5q8SJR3AFDYi3ogqEhCMXjNLR1k8fiXTkG2BxGJmGhTqwE8C4grdjvJ0w5UsAVoOH7v8HQ", "types" : [ "restaurant", "food", "establishment" ], "vicinity" : "37 Bank St, Pyrmont" }, { "geometry" : { "location" : { "lat" : -33.867591, "lng" : 151.201196 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png", "id" : "a97f9fb468bcd26b68a23072a55af82d4b325e0d", "name" : "Australian Cruise Group", "opening_hours" : { "open_now" : true }, "photos" : [ { "height" : 242, "html_attributions" : [], "photo_reference" : "CnRnAAAABjeoPQ7NUU3pDitV4Vs0BgP1FLhf_iCgStUZUr4ZuNqQnc5k43jbvjKC2hTGM8SrmdJYyOyxRO3D2yutoJwVC4Vp_dzckkjG35L6LfMm5sjrOr6uyOtr2PNCp1xQylx6vhdcpW8yZjBZCvVsjNajLBIQ-z4ttAMIc8EjEZV7LsoFgRoU6OrqxvKCnkJGb9F16W57iIV4LuM", "width" : 200 } ], "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0", "reference" : "CoQBeQAAAFvf12y8veSQMdIMmAXQmus1zqkgKQ-O2KEX0Kr47rIRTy6HNsyosVl0CjvEBulIu_cujrSOgICdcxNioFDHtAxXBhqeR-8xXtm52Bp0lVwnO3LzLFY3jeo8WrsyIwNE1kQlGuWA4xklpOknHJuRXSQJVheRlYijOHSgsBQ35mOcEhC5IpbpqCMe82yR136087wZGhSziPEbooYkHLn9e5njOTuBprcfVw", "types" : [ "travel_agency", "restaurant", "food", "establishment" ], "vicinity" : "32 The Promenade, King Street Wharf 5, Sydney" } ], "status" : "OK" }
A JSON response contains up to four root elements:
"status"
contains metadata on the request. See Status Codes below."results"
contains an array of places, with information about each. See Search Results for information about these results. The Places API returns up to 20establishment
results per query. Additionally,political
results may be returned which serve to identify the area of the request.html_attributions
may contain a set of attributions about this listing which must be displayed to the user (some listings may not have attribution).next_page_token
contains a token that can be used to return up to 20 additional results. Anext_page_token
will not be returned if there are no additional results to display. The maximum number of results that can be returned is 60. There is a short delay between when anext_page_token
is issued, and when it will become valid.
See Processing JSON with JavaScript for help parsing JSON responses.
<?xml version="1.0" encoding="UTF-8"?> <PlaceSearchResponse> <status>OK</status> <result> <name>Rhythmboat Cruises</name> <vicinity>Pyrmont Bay Wharf Darling Dr, Sydney</vicinity> <type>travel_agency</type> <type>restaurant</type> <type>food</type> <type>establishment</type> <geometry> <location> <lat>-33.8707750</lat> <lng>151.1990250</lng> </location> </geometry> <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon> <place_id>ChIJyWEHuEmuEmsRm9hTkapTCrk</place_id> <reference>CoQBdAAAAChhtoQX_467esHavS0Sj9DrY306W3_uDXKmB2us8Eh7_dX7rDuln18i_uqocF_LmzRptuFr6WZs7aeBSLFq8VFmckxFjsXDaqMdd3gvxi_5dIwPTEugQQYG9oJA-YnYfPBvjGtuoMfNnjyU2GuxGRmJjCO77pEAbsTLq44eBG5jEhAvkKHCGqIzqgC9tdOb1dSqGhRA1hhG4pvILD5OEAq6W8L8sXbkug</reference> <id>21a0b251c9b8392186142c798263e289fe45b4aa</id> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>CnRnAAAAiRA8ls6lx5LTfLuHJtLYvz73LXIMa5EVsHz2OUjh70LBPBnIEULZ57w076gOuyCeJqP041_v-ek3I5C4IkqW7YgA0EBybwywfIcUXsj5W_qiJR2yaXHXI-FmDM6j1zaS0sJQnNJhe4Bl9W42Jx16phIQRmNOWKGIemKLgzNEPcCnmBoUGgr0gWQBwWd8HAseR-5ie3JYuIM</photo_reference> <width>519</width> <height>270</height> </photo> </result> <result> <name>Private Charter Sydney Habour Cruise</name> <vicinity>Australia</vicinity> <type>restaurant</type> <type>food</type> <type>establishment</type> <geometry> <location> <lat>-33.8668910</lat> <lng>151.2008140</lng> </location> </geometry> <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon> <place_id>ChIJqwS6fjiuEmsRJAMiOY9MSms</place_id> <reference>CpQBhQAAAKGKrbbnAW3_eAypKW9bhAzAuSmaqAogs7MTFxsntDqCzt-gKD9nz-zqNsk0uJsl0yCUYpNYjHz_yzmh3J_4TTxpxIqdaq2uDvfoTYtvm8FkxMAkK3cS7k9t3Ze2aHRWnxlN9hczK2xlc5taDE7xAGOHF5Xe5IlVV1wV66sOrWrlHtGh47lqT9Id86eG2OmlVhIQo4djLtRkceg-zaYjULYEjRoUToVEyOUVCFfZMUs_E7ZLSzjFmcg</reference> <id>45a27fd8d56c56dc62afc9b49e1d850440d5c403</id> <photo> <photo_reference>CnRnAAAAUW97jpK2_C2Lh4jLPVKZlhyS84mqZxvVmWFdc6jdl3XxjzKbYdbJpz0PGW5eFRw6kTKYNZM9QvRf-csFegHILZxLCLJ-6ZnbdEXbVM4kBzOb-rhchJx1KC6LHs_vVWP8bK96569lFYRf7Hn8ylQrlhIQb69_dcZVwqQhREsHW6azWhoU0XMWqZMBBzx-hgpduAaeErOFg8E</photo_reference> <width>640</width> <height>426</height> </photo> </result> <result> <name>Bucks Party Cruise</name> <vicinity>37 Bank St, Pyrmont</vicinity> <type>restaurant</type> <type>food</type> <type>establishment</type> <geometry> <location> <lat>-33.8709430</lat> <lng>151.1903110</lng> </location> </geometry> <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon> <place_id>ChIJLfySpTOuEmsRsc_JfJtljdc</place_id> <reference>CoQBdAAAAOMUoYamsekTDxBDVyKZ-E54VQ6HjirVzAZBBwz5gcn5KTfmemmwmOAtLcvRScp1NLQmj-fBYzEO2Gq_cO4Dc12PG0_twzDv9zq3KIyNQVuO-r0n1eQVj8Dlng-n4c1F2hMxufCNVp4-QfjMj81qXJm0invQMUc1xNgZRyiOpLe9EhDLn0KiVWEFKOURYsWrHRouGhR7YMJxYmFs-OXjKyzQKGdQXLrzPw</reference> <id>30bee58f819b6c47bd24151802f25ecf11df8943</id> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>CnRnAAAAjboYP9Ujxe5SmZFN5AJc42AWtpYFX9wYdqjcTXavXJlfoXdHPC2hErdbHcaeYJBNPV6CzoDc2RLw_w9HofGOhCWHtoAl9b3g8TZZjnZobnAHxoljUdgV8PXyd-pCO-QHKOtiKfIdUmF4HRj2QHj6OhIQhLNpoKNKP8MNjk90M4KGrhoUW2NyBgsWjRpUEoWlt0fD48BhEcQ</photo_reference> <width>800</width> <height>600</height> </photo> </result> <result> <name>Australian Cruise Group</name> <vicinity>32 The Promenade, King Street Wharf 5, Sydney</vicinity> <type>travel_agency</type> <type>restaurant</type> <type>food</type> <type>establishment</type> <geometry> <location> <lat>-33.8675910</lat> <lng>151.2011960</lng> </location> </geometry> <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon> <place_id>ChIJrTLr-GyuEmsRBfy61i59si0</place_id> <reference>CoQBeAAAAJZA0WY2pKnZ6nNnxNd_pSDA2NilDLfGDf7pTt7VssxB5tMYE7400w3HZHRav2unpKRhEp7lrh0yKcVdSfKYIz85k1SExoLGmYD8NIf1dPr8KlkRWOYZUTLGp623r5hAzEGk94mPleF4s50pWqLrhAzwvJb1tGj2ak-2PXQORkeTEhAfTj6tMFo_tRWZYOnYCxiVGhQA3n-KV7AW5MvJlGaIDHuLyyEBBA</reference> <id>a97f9fb468bcd26b68a23072a55af82d4b325e0d</id> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>CnRnAAAAhTkpwozMoZx_NXMkIrKdcEGe46BmPy3GPCfS-gkCK5PlR8rFDY9DtD_7wFYAIdhVoZz3I9QguRNbil5y37jTU-03GJ_LqVw_avSxFkT0g2kU0K5z2VYnAsgNsrbsK_EVglhg5PrDybC1tAVKCXSGsRIQOcdlAVnC1Qc46YLWjlqdyxoUL5JGZgczfo1jxLxhDeGs8OvBQCk</photo_reference> <width>200</width> <height>242</height> </photo> </result> </PlaceSearchResponse>
An XML response consists of a single
<PlaceSearchResponse>
and up to four top-level elements:
<status>
contains metadata on the request. See Status Codes below.- Zero or more
<result>
elements, each containing information about a single establishment. See Nearby Search Results for information about these results. The Places API returns up to 20establishment
results per query. Additionally,political
<type>
results, or streets, may be returned which serve to identify the area of the request. next_page_token
contains a token that can be used to return up to 20 additional results. Anext_page_token
will not be returned if there are no additional results to display. The maximum number of results that can be returned is 60. Thenext_page_token
will become active 2 seconds after it is first issued.html_attributions
contain a set of attributions about this listing which must be displayed to the user.
Status Codes
The "status"
field within the search response object
contains the status of the request, and may contain debugging information
to help you track down why the request failed. The
"status"
field may contain the following
values:
OK
indicates that no errors occurred; the place was successfully detected and at least one result was returned.ZERO_RESULTS
indicates that the search was successful but returned no results. This may occur if the search was passed alatlng
in a remote location.OVER_QUERY_LIMIT
indicates that you are over your quota.REQUEST_DENIED
indicates that your request was denied, generally because of lack of an invalidkey
parameter.INVALID_REQUEST
generally indicates that a required query parameter (location
orradius
) is missing.UNKNOWN_ERROR
indicates a server-side error; trying again may be successful.
Error Messages
When the Google Places service returns a status code other than
OK
, there may be an additional error_message
field
within the search response object. This field contains more detailed
information about the reasons behind the given status code.
Search Results
When the Google Places service returns JSON results from a search, it places
them within a results
array. Even if the service returns
no results (such as if the location
is remote) it
still returns an empty results
array. XML responses consist
of zero or more <result>
elements.
Each element of the results
array contains a single result
from the specified area (location
and
radius
), ordered by prominence.
The result may also contain attribution information which must be displayed to the user. This is an example of an attribution in JSON format:
"html_attributions" : [ "Listings by \u003ca href=\"http://www.example.com/\"\u003eExample Company\u003c/a\u003e" ],This is an attribution in XML format:
<html_attribution>Listings by <a href="http://www.example.com/">Example Company</a></html_attribution>
Each result within the results
array may contain
the following fields:
icon
contains the URL of a recommended icon which may be displayed to the user when indicating this result.geometry
contains geometry information about the result, generally including thelocation
(geocode) of the place and (optionally) theviewport
identifying its general area of coverage.plus_code
(see Open Location Code and plus codes) is 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).The plus code is formatted as a global code and a compound code:
global_code
is a 4 character area code and 6 character or longer local code (849VCWC8+R9).compound_code
is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA).
name
contains the human-readable name for the returned result. Forestablishment
results, this is usually the business name.opening_hours
may contain the following information:open_now
is a boolean value indicating if the place is open at the current time.
photos[]
— an array ofphoto
objects, each containing a reference to an image. A Place Search will return at most onephoto
object. Performing a Place Details request on the place 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. Aphoto
object is described as:photo_reference
— a string used to identify the photo when you perform a Photo request.height
— the maximum height of the image.width
— the maximum width of the image.html_attributions[]
— contains any required attributions. This field will always be present, but may be empty.
place_id
— a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in theplaceId
field of a Places API request. For more information about place IDs, see the place ID overview.price_level
— 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:0
— Free1
— Inexpensive2
— Moderate3
— Expensive4
— Very Expensive
rating
contains the place's rating, from 1.0 to 5.0, based on aggregated user reviews.types[]
contains an array of feature types describing the given result. See the list of supported types. XML responses include multiple<type>
elements if more than one type is assigned to the result.vicinity
contains a feature name of a nearby location. Often this feature refers to a street or neighborhood within the given results. Thevicinity
property is only returned for a Nearby Search.formatted_address
is a string containing the human-readable address of this place. Often this address is equivalent to the "postal address".permanently_closed
is a boolean flag indicating whether the place has permanently shut down (valuetrue
). If the place is not permanently closed, the flag is absent from the response.
Accessing Additional Results
By default, each Nearby Search or Text Search returns up to
20 establishment
results
per query; however, each search can return as many as 60 results, split
across three pages. If your search will return more than
20, then the search response will include
an additional value — next_page_token
. Pass the value of
the next_page_token
to the pagetoken
parameter of
a new search to see the next set of results. If the
next_page_token
is null, or is not returned, then there are no
further results. There is a short delay between when a
next_page_token
is issued, and when it will become
valid. Requesting the next page before it is available will return an
INVALID_REQUEST
response. Retrying the request with the same
next_page_token
will return the next page of results.
For example, in the query below, we search for restaurants near Darling
Harbour, in Sydney Australia, and rank the results by distance. You can see
that the response contains a next_page_token
property.
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&rankby=distance&type=food&key=YOUR_API_KEY
{ "html_attributions" : [], "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q", "results" : [ { "geometry" : { "location" : { "lat" : -33.867217, "lng" : 151.195939 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png", "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7", "name" : "Biaggio Cafe - Pyrmont", "opening_hours" : { "open_now" : true }, "photos" : [ { "height" : 600, "html_attributions" : [], "photo_reference" : "CnRnAAAAmWmj0BqA0Jorm1_vjAvx1n6c7ZNBxyY-U9x99-oNyOxvMjDlo2npJzyIq7c3EK1YyoNXdMFDcRPzwLJtBzXAwCUFDGo_RtLRGBPJTA2CoerPdC5yvT2SjfDwH4bFf5MrznB0_YWa4Y2Qo7ABtAxgeBIQv46sGBwVNJQDI36Wd3PFYBoUTlVXa0wn-zRITjGp0zLEBh8oIBE", "width" : 900 } ], "place_id" : "ChIJIfBAsjeuEmsRdgu9Pl1Ps48", "price_level" : 1, "rating" : 3.4, "reference" : "CoQBeAAAAGu0wNJjuZ40DMrRe3mpn7fhlfIK1mf_ce5hgkhfM79u-lqy0G2mnmcueTq2JGWu9wsgS1ctZDHTY_pcqFFJyQNV2P-kdhoRIeYRHeDfbWtIwr3RgFf2zzFBXHgNjSq-PSzX_OU6OT2_3dzdhhpV-bPezomtrarW4DsGl9uh773yEhDJT6R3V8Fyvl_xeE761DTCGhT1jJ3floFI5_c-bHgGLVwH1g-cbQ", "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ], "vicinity" : "48 Pirrama Rd, Pyrmont" }, { "geometry" : { "location" : { "lat" : -33.866786, "lng" : 151.195633 } }, "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png", "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6", "name" : "Doltone House", "photos" : [ { "height" : 1260, "html_attributions" : [ "From a Google User" ], "photo_reference" : "CnRwAAAAeM-aLqAm573T44qnNe8bGMkr_BOh1MOVQaA9CCggqtTwuGD1rjsviMyueX_G4-mabgH41Vpr8L27sh-VfZZ8TNCI4FyBiGk0P4fPxjb5Z1LrBZScYzM1glRxR-YjeHd2PWVEqB9cKZB349QqQveJLRIQYKq2PNlOM0toJocR5b_oYRoUYIipdBjMfdUyJN4MZUmhCsTMQwg", "width" : 1890 } ], "place_id" : "ChIJ5xQ7szeuEmsRs6Kj7YFZE9k", "reference" : "CnRvAAAA22k1PAGyDxAgHZk6ErHh_h_mLUK_8XNFLvixPJHXRbCzg-gw1ZxdqUwA_8EseDuEZKolBs82orIQH4m6-afDZV9VcpggokHD9x7HdMi9TnJDmGb9Bdh8f-Od4DK0fASNBL7Me3CsAWkUMWhlNQNYExIQ05W7VbxDTQe2Kh9TiL840hoUZfiO0q2HgDHSUyRdvTQx5Rs2SBU", "types" : [ "food", "establishment" ], "vicinity" : "48 Pirrama Rd, Pyrmont" }, { "aspects" : [ { "rating" : 23, "type" : "overall" } ], ... ], "status" : "OK" }
To see the next set of results you can submit a new query, passing the
result of the next_page_token
to the pagetoken
parameter. For example:
https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY
Setting pagetoken
will cause any other parameters to be
ignored. The query will execute the same search as before, but will return
a new set of results. You can request a new page up to two times following
the original query. Each page of results must be displayed in turn. Two or
more pages of search results should not be displayed as the result of a
single query. Note that each search counts as a single request against your
usage limits.
The sensor
Parameter
The Google Places API previously required that you include the
sensor
parameter to indicate whether your application used a
sensor to determine the user's location. This parameter is no longer
required.