Google Places API

Place Search

Looking to use this service in a JavaScript application? Check out the Places Library of the Google Maps API v3.

The Google Places API allows you to query for place information on a variety of categories, such as: establishments, prominent points of interest, geographic locations, and more. 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.

  1. Nearby Search Requests
  2. Text Search Requests
  3. Radar Search Requests
  4. Search Responses

Nearby Search Requests

Earlier versions of the Places API referred to Nearby Search as Place Search.

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 for purposes of quota management and so that Places added from your application are made immediately available to your app. Visit the APIs Console to create an API Project and obtain your key.
  • 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 that radius must not be included if rankby=distance (described under Optional parameters below) is specified.
  • sensor — Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request. This value must be either true or false.
  • If rankby=distance (described under Optional parameters below) is specified, then one or more of keyword, name, or types 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 and maxprice (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 — One or more terms to be matched against the names of Places, separated with a space character. Results will be restricted to those containing the passed name values. Note that a Place may have additional names associated with it, beyond its listed name. The API will try to match the passed name value against all of these names; as a result, Places may be returned in the results whose listed names do not match the search term, but whose associated names do.
  • 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. 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, the number of check-ins from your application, global popularity, and other factors.
    • distance. This option sorts results in ascending order by their distance from the specified location. When distance is specified, one or more of keyword, name, or types is required.
  • types — Restricts the results to Places matching at least one of the specified types. Types should be separated with a pipe symbol (type1|type2|etc). See the list of supported types.
  • pagetoken — Returns the next 20 results from a previously run search. Setting a pagetoken parameter will execute a search with the same parameters used previously — all parameters other than pagetoken will be ignored.
  • zagatselected — Add this parameter (just the parameter name, with no associated value) to restrict your search to locations that are Zagat selected businesses. This parameter must not include a true or false value. The zagatselected parameter is experimental, and is only available to Places API enterprise customers.

Maps API for Business customers should not include a client or signature parameter with their requests.

An example request is below, showing a search for Places of type 'food' within a 500m radius of a point in Sydney, Australia, containing the word 'harbour' in their name:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&types=food&name=harbour&sensor=false&key=AddYourOwnKeyHere

Note that you'll need to replace the key in this example with your own 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". The service responds with a list of Places matching the text string and any location bias that has been set. 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.

Both the Google Nearby Search and the Google Places Text Search services share the same usage limits. However, the Text Search service is subject to a 10-times multiplier. That is, each Text Search request that you make will count as 10 requests against your quota. If you've purchased the Google Places API as part of your Maps API for Business contract, the multiplier may be different. Please refer to the Google Maps API for Business documentation for details.

A Place 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". The Place service will return candidate matches based on this string and order the results based on their perceived relevance.
  • key — Your application's API key. This key identifies your application for purposes of quota management and so that Places added from your application are made immediately available to your app. Visit the APIs Console to create an API Project and obtain your key.
  • sensor — Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request. This value must be either true or false.

Optional parameters

  • location — The latitude/longitude around which to retrieve Place information. This must be specified as latitude,longitude. If you specify a location parameter, you must also specify a radius 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 and maxprice (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.
  • types — Restricts the results to Places matching at least one of the specified types. Types should be separated with a pipe symbol (type1|type2|etc). See the list of supported types.
  • zagatselected — Add this parameter (just the parameter name, with no associated value) to restrict your search to locations that are Zagat selected businesses. This parameter must not include a true or false value. The zagatselected parameter is experimental, and is only available to Places API enterprise customers.

You may bias results to a specified circle by passing a location and a radius parameter. This will instruct the Place service to prefer showing results within that circle; results outside of the defined area may still be displayed.

Maps API for Business customers should not include a client or signature parameter with their requests.

The below example shows a search for restaurants near Sydney.

https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&sensor=true&key=AddYourOwnKeyHere

Note that you'll need to replace the key in this example with your own key in order for the request to work in your application.

Radar Search Requests

The Google Places API Radar Search Service allows you to search for up to 200 Places at once, but with less detail than is typically returned from a Text Search or Nearby Search request. With Radar Search, you can create applications that help users identify specific areas of interest within a geographic area. The search response will include up to 200 Places, identified only by their geographic coordinates and Place reference. You can send a Place Details request for more information about any of the Places in the response.

Radar Search shares the same usage limits and quota as Text Search and Nearby Search. However, the Radar Search Service is subject to a 5-times multiplier. That is, each Radar Search request that you make will count as 5 requests against your quota.

A Place Radar Search request is an HTTP URL of the following form:

https://maps.googleapis.com/maps/api/place/radarsearch/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

  • key — Your application's API key. This key identifies your application for purposes of quota management and so that Places added from your application are made immediately available to your app. Visit the APIs Console to create an API Project and obtain your key.
  • 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.
  • sensor — Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request. This value must be either true or false.

Optional parameters

A Radar Search request must include at least one of keyword, name, or types. Other parameters are completely optional.

  • 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.
  • minprice and maxprice (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.
  • name — One or more terms to be matched against the names of Places, separated with a space character. Results will be restricted to those containing the passed name values. Note that a Place may have additional names associated with it, beyond its listed name. The API will try to match the passed name value against all of these names; as a result, Places may be returned in the results whose listed names do not match the search term, but whose associated names do.
  • 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.
  • types — Restricts the results to Places matching at least one of the specified types. Types should be separated with a pipe symbol (type1|type2|etc). See the list of supported types.
  • zagatselected — Add this parameter (just the parameter name, with no associated value) to restrict your search to locations that are Zagat selected businesses. This parameter must not include a true or false value. The zagatselected parameter is experimental, and is only available to Places API enterprise customers.

Maps API for Business customers should not include a client or signature parameter with their requests.

The below example returns a list of museums near London, England.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=51.503186,-0.126446&radius=5000&types=museum&sensor=false&key=AddYourOwnKeyHere

Using a combination of the keyword, name and types parameters, you can perform more precise queries. The below example shows restaurants and cafes in Paris that users have described as vegetarian.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=48.859294,2.347589&radius=5000&types=food|cafe&sensor=false&keyword=vegetarian&key=AddYourOwnKeyHere

Note that you'll need to replace the key in these examples with your own key in order for the request to work in your application.

Search Responses

Search responses are returned in the format indicated by the output flag within the URL request's path.

A Text Search response is similar to a Nearby Search response, except that it returns a formatted_address instead of a vicinity property.

JSON
{
   "html_attributions" : [
      "Listings by \u003ca href=\"http://www.yellowpages.com.au/\"\u003eYellow Pages\u003c/a\u003e"
   ],
   "results" : [
      {
         "formatted_address" : "529 Kent Street, Sydney NSW, Australia",
         "geometry" : {
            "location" : {
               "lat" : -33.8750460,
               "lng" : 151.2052720
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "827f1ac561d72ec25897df088199315f7cbbc8ed",
         "name" : "Tetsuya's",
         "rating" : 4.30,
         "reference" : "CnRmAAAAmmm3dlSVT3E7rIvwQ0lHBA4sayvxWEc4nZaXSSjRtfKRGoYnfr3d5AvQGk4e0u3oOErXsIJwtd3Wck1Onyw6pCzr8swW4E7dZ6wP4dV6AsXPvodwdVyqHgyGE_K8DqSp5McW_nFcci_-1jXb5Phv-RIQTzv5BjIGS0ufgTslfC6dqBoU7tw8NKUDHg28bPJlL0vGVWVgbTg",
         "types" : [ "restaurant", "food", "establishment" ]
      },
      {
         "formatted_address" : "Upper Level, Overseas Passenger Terminal/5 Hickson Road, The Rocks NSW, Australia",
         "geometry" : {
            "location" : {
               "lat" : -33.8583790,
               "lng" : 151.2100270
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png",
         "id" : "f181b872b9bc680c8966df3e5770ae9839115440",
         "name" : "Quay",
         "rating" : 4.10,
         "reference" : "CnRiAAAADmPDOkn3znv_fX78Ma6X5_t7caEGNdSWnpwMIdDNZkLpVKPnQJXP1ghlySO-ixqs28UtDmJaOlCHn18pxpj7UQjRzR4Kmye6Gijoqoox9bpkaCAJatbJGZEIIUwRbTNIE_L2jGo5BDqiosqU2F5QdBIQbXKrvfQuo6rmu8285j7bDBoUrGrN4r6XQ-PVm260PFt5kwc3EfY",
         "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ]
      },
      {
         "formatted_address" : "107 George Street, The Rocks NSW, Australia",
         "geometry" : {
            "location" : {
               "lat" : -33.8597750,
               "lng" : 151.2085920
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "7beacea28938ae42bcac04faf79a607bf84409e6",
         "name" : "Rockpool",
         "rating" : 4.0,
         "reference" : "CnRlAAAAVK4Ek78r9yHV56I-zbaTxo9YiroCbTlel-ZRj2i6yGAkLwNMm_flMhCl3j8ZHN-jJyG1TvKqBBnKQS2z4Tceu-1kZupZ1HSo5JWRBKd7qt2vKgT8VauiEBQL-zJiKVzSy5rFfilKDLSiLusmdi88ThIQqqj6hKHn5awdj6C4f59ifRoUg67KlbpuGuuW7S1tAH_EyBl6KE4",
         "types" : [ "restaurant", "food", "establishment" ]
      },
      {
         "formatted_address" : "483 George Street, Sydney NSW, Australia",
         "events" : [
            {
              "event_id" : "7lH_gK1GphU",
              "summary" : "Google Maps Developer Meetup: Rockin' out with the Places API",
              "url" : "https://developers.google.com/places"
            }
          ],
         "geometry" : {
            "location" : {
               "lat" : -33.8731950,
               "lng" : 151.2063380
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/civic_building-71.png",
         "id" : "017049cb4e82412aaf0efbde890e82b7f2987c16",
         "name" : "Chinatown Sydney",
         "rating" : 4.0,
         "reference" : "CnRuAAAAsLNeRQtKD7TEUXWG6gYD7ByOVKjQE61GSyeGZrX-pOPVps2BaLBlH0zBHlrVU9DKhsuXra075loWmZUCbczKDPdCaP9FVJXB2NsZ1q7188pqRFik58S9Z1lcWjyVoVqvdUUt9bDMLqxVT4ENmolbgBIQ9Wy0sgDy0BgWyg5kfPMHCxoUOvmhfKC-lTefXGgnsRqEQwn8M0I",
         "types" : [
            "city_hall",
            "park",
            "restaurant",
            "doctor",
            "train_station",
            "local_government_office",
            "food",
            "health",
            "establishment"
         ]
      }
   ],
   "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 Nearby Search Results for information about these results. The Places API returns up to 20 establishment results per query. Additionally, political results may be returned which serve to identify the area of the request.
  • html_attributions contain a set of attributions about this listing which must be displayed to the user.
  • next_page_token contains a token that can be used to return up to 20 additional results. A next_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 a next_page_token is issued, and when it will become valid.

See Processing JSON with Javascript for help parsing JSON responses.

XML
<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Tetsuya's</name>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>529 Kent Street, Sydney NSW, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8750460</lat>
    <lng>151.2052720</lng>
   </location>
  </geometry>
  <rating>4.3</rating>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <reference>CnRmAAAANRC46osWIWF63JgsOdM2XGk22I0x4HxtfL9F_XWMmF3s-ayUyIwvnySqckNlMreu53OqSrX3YsffYOxQh7PYKV2KzI19EqVcBe50qBwmy_vSXoJ3L6ehFYDJTvpHhwAH3b4BFwM8spTOwjOSMeTqhhIQ3LhryZnC4k2F7nKkT9f-8RoUVBwA9UV-C8hHNZh44YkvVOxxtK0</reference>
  <id>827f1ac561d72ec25897df088199315f7cbbc8ed</id>
 </result>
 <result>
  <name>Quay</name>
  <type>cafe</type>
  <type>bar</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>Upper Level, Overseas Passenger Terminal/5 Hickson Road, The Rocks NSW, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8583790</lat>
    <lng>151.2100270</lng>
   </location>
  </geometry>
  <rating>4.1</rating>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png</icon>
  <reference>CnRiAAAAeNd3Vvz1j9dvz1deiDQWd96zoKYOFMBVhXYbhbZf4A5zfHmMsolsTAH5pd_AJ2jZYOAfCG82yFJLMTMY5-C_Jnic1bsTVud_uTBnJ0JUzD5Q-p0_7_7qYTRfVqBcCKktQ8PGrQquPEl4LfgDa1j3AhIQfkhCpHR9bgfqawWNkbzpqRoUkd7Qatt_OFkX3KKa9K_fxwE2bc4</reference>
  <id>f181b872b9bc680c8966df3e5770ae9839115440</id>
 </result>
 <result>
  <name>Rockpool</name>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>107 George Street, The Rocks NSW, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8597750</lat>
    <lng>151.2085920</lng>
   </location>
  </geometry>
  <rating>4.0</rating>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>

<reference>CnRlAAAALuyHKpRN_oLCCfTJZ-uIA7YdJCe3zEhsSf0RZ25GnX6UhQ66gTeVJdGAyfS2bwB3XPvocWSGBfxF-De6bXC3P_Cvezr9kAEW9jBKvazwyyYZoUaZqVwuy4sGlzKOSCse5qDR7snP63sDD1bkV60OGxIQ2zfuqWNJmtiiSXeNFqSgQhoUthzNiDC86p2SIXdpcarNFXRgBLk</reference>
  <id>7beacea28938ae42bcac04faf79a607bf84409e6</id>
  <event>
    <summary>Google Maps Developer Meetup: Rockin' out with the Places API</summary>
    <event_id>7lH_gK1GphU</event_id>
    <url>https://developers.google.com/places</url>
  </event>
 </result>
 <result>
  <name>Chinatown Sydney</name>
  <type>city_hall</type>
  <type>park</type>
  <type>restaurant</type>
  <type>doctor</type>
  <type>train_station</type>
  <type>local_government_office</type>
  <type>food</type>
  <type>health</type>
  <type>establishment</type>
  <formatted_address>483 George Street, Sydney NSW, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8731950</lat>
    <lng>151.2063380</lng>
   </location>
  </geometry>
  <rating>4.0</rating>
 <icon>http://maps.gstatic.com/mapfiles/place_api/icons/civic_building-71.png</icon>  <reference>CnRuAAAAiC5vFoN7Y_uh9092KqN1O1KEgihp845nP1IGIj3eDOzfOT_RPdrTmCv4wrNcwMUvMfR2NhTyWd1g2W11V6HPrYlH_gXJQyohh6iHgQmDCXUESusetpMRPfob1GnBk2ylXq-oQz_85mEyqzBFFMICshIQuDEafdNuT1HpAx5suyTUeBoUWx0qvhqfUxl0F37Qae2RlLgdk0c</reference>
  <id>017049cb4e82412aaf0efbde890e82b7f2987c16</id>
 </result>
 <html_attribution>Listings by <a href="http://www.yellowpages.com.au/">Yellow Pages</a></html_attribution>
</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 20 establishment 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. A next_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. The next_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 a latlng 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 a sensor parameter.
  • INVALID_REQUEST generally indicates that a required query parameter (location or radius) is missing.

Error Messages

When the 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 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 ordering of results can be influenced by check-in activity within your application - Places with many recent check-ins may figure more prominently in your application's results. The result may also contain attribution information which must be displayed to the user.

Each result within the results array may contain the following fields:

  • An events[]: array or one or more <event> elements provide information about current events happening at this Place. Up to three events are returned for each place, ordered by start time. For information about events, please read Events in the Places API. Each event contains:
    • event_id: The unique ID of this event.
    • summary: A textual description of the event. This property contains a string, the contents of which are not sanitized by the server. Your application should be prepared to prevent or deal with attempted exploits, if necessary.
    • url: A URL pointing to details about the event. This property will not be returned if no URL was specified for the event.
  • icon contains the URL of a recommended icon which may be displayed to the user when indicating this result.
  • id contains a unique stable identifier denoting this place. This identifier may not be used to retrieve information about this place, but is guaranteed to be valid across sessions. It can be used to consolidate data about this Place, and to verify the identity of a Place across separate searches.
  • geometry contains geometry information about the result, generally including the location (geocode) of the Place and (optionally) the viewport identifying its general area of coverage.
  • name contains the human-readable name for the returned result. For establishment 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 of photo objects, each containing a reference to an image. A Place Search will return at most one photo 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. A photo 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.
  • 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 — Free
    • 1 — Inexpensive
    • 2 — Moderate
    • 3 — Expensive
    • 4 — Very Expensive
  • rating contains the Place's rating, from 1.0 to 5.0, based on user reviews.
  • reference contains a unique token that you can use to retrieve additional information about this place in a Place Details request. You can store this token and use it at any time in future to refresh cached data about this Place, but the same token is not guaranteed to be returned for any given Place across different searches.
  • types[] contains an array of feature types describing the given result. See the list of supported types for more information. 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. The vicinity 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". The formatted_address property is only returned for a Text Search.

Premium Data

In addition to the fields listed above, Places API enterprise customers may receive the following fields. These fields will appear as top level children of the result field.

Note: Premium data features are considered experimental and subject to change.

  • aspects contains a single AspectRating object, for the Primary rating of that establishment. Each AspectRating is described as:
    • type the name of the aspect that is being rated. The following types are supported: appeal, atmosphere, decor, facilities, food, overall, quality and service.
    • rating the aggregate rating for this particular aspect, from 0 to 30. Note that aggregate ratings range from 0 to 30, while ratings that appear as part of a review range from 0 to 3.
  • zagat_selected indicates that the Place has been selected as a Zagat quality location. The Zagat label identifies places known for their consistently high quality or that have a special or unique character.

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 below query, we search for restaurants near Darling Harbor, 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&types=food&sensor=false&key=AddYourOwnKeyHere
{
   "debug_info" : [],
   "html_attributions" : [
      "Listings by \u003ca href=\"http://www.yellowpages.com.au/\"\u003eYellow Pages\u003c/a\u003e"
   ],
   "next_page_token" : "ClRIAAAA81cWfi0WTUUKB9gszCYq9df7mStFyoCOu--Kd9Dv8_U7Iljt-DJygDnlXRvy0fsOr5TMgqgoOIeYZ1bJ1VLFyouxZ7guHnI7796Nv66mt7USEE1yVN0OZ3dAl6-wFk0LAlcaFFIxt3tpEKf4SdHth2gHH4f8Tx_y",
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867260,
               "lng" : 151.1958130
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/bar-71.png",
         "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7",
         "name" : "Biaggio Cafe",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CoQBegAAAIDq6dN22YIkR6IVd_zW9Q-r4-Pn4gElH4iETwtiQIjBUhPd6ItDuB9T_wBPCwzPDwB6NXqDZdNMORHzs6yGyitV0bzuP9jrsBjjHHjT6VAyYnMFJe9iPAlcMN6Bnv-EgTSyGibgJPV4P7kODba8AVYKW7jiPxTw1MSV065SRlb5EhAXnIrTWuEyLZxkC0Dk7ccyGhRWdTai1EdGsQnLJJygZpxRSkj_sg",
               "width" : 900
            }
         ],
         "price_level" : 1,
         "reference" : "CnRqAAAAtzxgHoMgRt4nfsgJrK5lCawM_zKjNB-j1IVjh2Un58RyRY2rnR7w5T5s-43qjiwBx2dcnRwnhCZxy4o7zdGC5qiS3zNb0OJz2okMJgNXhwGLRuzvszJelTVTpZKW3ZT__lo0xjZLO1RC5e0WGAC5FBIQGj-j1KCCj5KhZiceDwLwQhoUtPmhjIMcsUA5KkqzbxdqWZBM7oU",
         "types" : [ "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Road, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.8668040,
               "lng" : 151.1955790
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
         "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CqQBmgAAALdW4RNXGQxx6HY8evlcrVpnAsH2fzjE284U6izvlWj-EcdddL18M0XZoPlB-oFQcqJ5HmJ3BAPNLr2mOm7heML43rMfrgMHHrK8hWy3TvvX0c3OS-elATlwhl_a1ZSA8suvO4-prVODWedUbuzOJx2ejlHJEXWtYh93lzmamuGSmjTiWp8Rk9v_xpoYmIhXP_prdLtBnAysbDG0-_mdZ8ISEKKIHt7HKH7peAnLIyJTdRMaFHSnarPIWg5ZfgqbMA75KJfPljsR",
               "width" : 900
            }
         ],
         "reference" : "CnRrAAAAVP24UU2BEUt3KzKx6_Kl0rFvuAry2HsODYy94ykrmb4SpBlgb7VPnFiuaCyV6hBdNjKpWOjkO4-Jh_hmvVyMBsxhsswAPeCWuqcd_R1iMOnTGSEQNfYIAJxC6OdntAwOzdnoj5ReCCSUdQxTzDpr8BIQiYzm8CnsIbCJyJxQzHoRcBoUw89rCN-3_5OrBHeIIxY0MkEZ4Og",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Road, Pyrmont"
      },
      ...
   ],
   "status" : "OK"
}

To see the next set of results, you can either reissue the same query, or 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=ClRIAAAAA6_80mA3VbkPRTawH0Fc2qv2zh28FA-D0RdPQqugFRuWxAk7vFADFjNH4JV65CtFn9s1qE2CpWUN-Ek42X1PU38TEnUaTvBPhnG2HjIcXUESEAVZmD0zcmFe9zOhCsFeVmkaFLDwndrZeaOww2hPyY6_zC07v0UJ&sensor=false&key=AddYourOwnKeyHere

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.