Google Places API

Place Details

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

Once you have a reference from a Place Search, you can request more details about a particular establishment or point of interest by initiating a Place Details request. A Place Details request returns more comprehensive information about the indicated place such as its complete address, phone number, user rating and reviews.

  1. Place Details Requests
  2. Place Details Responses
    1. Place Details Status Codes
    2. Place Details Error Messages
    3. Place Details Results

Place Details Requests

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

https://maps.googleapis.com/maps/api/place/details/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. The list of parameters and their possible values are enumerated below.

  • key (required) — 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.
  • reference (required) — A textual identifier that uniquely identifies a place, returned from a Place search.
  • sensor (required) — Indicates whether or not the Place Details request came from a device using a location sensor (e.g. a GPS). This value must be either true or false.
Optional Parameters
  • extensions (optional) — Indicates if the Place Details response should include additional fields. Additional fields may include Premium data, requiring an additional license, or values that are not commonly requested. Extensions are currently experimental. Supported values for the extensions parameter are:
    • review_summary includes a rich and concise review curated by Google's editorial staff.
  • language (optional) — The language code, indicating in which language the results should be returned, if possible. Note that some fields may not be available in the requested language. See the list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive.

An example request is shown below:

https://maps.googleapis.com/maps/api/place/details/json?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&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.

Place Details Responses

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


JSON
{
   "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "48",
            "short_name" : "48",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Pirrama Road",
            "short_name" : "Pirrama Road",
            "types" : [ "route" ]
         },
         {
            "long_name" : "Pyrmont",
            "short_name" : "Pyrmont",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "NSW",
            "short_name" : "NSW",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "AU",
            "short_name" : "AU",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "2009",
            "short_name" : "2009",
            "types" : [ "postal_code" ]
         }
      ],
      "events" : [
        {
          "event_id" : "9lJ_jK1GfhX",
          "start_time" : 1293865200,
          "summary" : "<p>A visit from author John Doe, who will read from his latest book.</p>
                       <p>A limited number of signed copies will be available.</p>",
          "url" : "http://www.example.com/john_doe_visit.html"
        }
      ],
      "formatted_address" : "48 Pirrama Road, Pyrmont NSW, Australia",
      "formatted_phone_number" : "(02) 9374 4000",
      "geometry" : {
         "location" : {
           "lat" : -33.8669710,
           "lng" : 151.1958750
         }
      },
      "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "id" : "4f89212bf76dde31f092cfc14d7506555d85b5c7",
      "international_phone_number" : "+61 2 9374 4000",
      "name" : "Google Sydney",
      "rating" : 4.70,
      "reference" : "CnRsAAAA98C4wD-VFvzGq-KHVEFhlHuy1TD1W6UYZw7KjuvfVsKMRZkbCVBVDxXFOOCM108n9PuJMJxeAxix3WB6B16c1p2bY1ZQyOrcu1d9247xQhUmPgYjN37JMo5QBsWipTsnoIZA9yAzA-0pnxFM6yAcDhIQbU0z05f3xD3m9NQnhEDjvBoUw-BdcocVpXzKFcnMXUpf-nkyF1w",
      "reviews" : [
         {
            "aspects" : [
               {
                  "rating" : 3,
                  "type" : "quality"
               }
            ],
            "author_name" : "Simon Bengtsson",
            "author_url" : "https://plus.google.com/104675092887960962573",
            "language" : "en",
            "rating" : 5,
            "text" : "Just went inside to have a look at Google. Amazing.",
            "time" : 1338440552869
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Felix Rauch Valenti",
            "author_url" : "https://plus.google.com/103291556674373289857",
            "language" : "en",
            "rating" : 5,
            "text" : "Best place to work :-)",
            "time" : 1338411244325
         },
         {
           "aspects" : [
              {
                 "rating" : 3,
                 "type" : "quality"
              }
             ],
            "author_name" : "Chris",
            "language" : "en",
            "rating" : 5,
            "text" : "Great place to work, always lots of free food!",
            "time" : 1330467089039
         }
      ],
      "types" : [ "establishment" ],
      "url" : "http://maps.google.com/maps/place?cid=10281119596374313554",
      "vicinity" : "48 Pirrama Road, Pyrmont",
      "website" : "http://www.google.com.au/"
   },
   "status" : "OK"
}
      
XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceDetailsResponse>
 <status>OK</status>
 <result>
  <name>Google Sydney</name>
  <vicinity>48 Pirrama Road, Pyrmont</vicinity>
  <type>establishment</type>
  <formatted_phone_number>(02) 9374 4000</formatted_phone_number>
  <formatted_address>48 Pirrama Road, Pyrmont NSW, Australia</formatted_address>
  <address_component>
   <long_name>48</long_name>
   <short_name>48</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Pirrama Road</long_name>
   <short_name>Pirrama Road</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Pyrmont</long_name>
   <short_name>Pyrmont</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>NSW</long_name>
   <short_name>NSW</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>AU</long_name>
   <short_name>AU</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>2009</long_name>
   <short_name>2009</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
     <lat>-33.8669710</lat>
     <lng>151.1958750</lng>
   </location>
  </geometry>
  <rating>4.7</rating>
  <url>http://maps.google.com/maps/place?cid=10281119596374313554</url>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png</icon>
  <reference>CnRsAAAAoGXc0eAcQOoO1A7sU58repRnghwM5q7UtsZFhVtjYtfKN_LFAPhdhBfUAU8m0EzeSyP0cDBi7kazZwNjlIMUqktqIanMiymuRDS8c539M6KCJNUMkjw22WXxtl3QoR25fIf-7YJnpza6bMIuFZ1CKBIQuBsbXu8xkbUNofECCkdvmxoU5k3Lpbr8XNCbofIKtsZxj8GloGA</reference>
  <id>4f89212bf76dde31f092cfc14d7506555d85b5c7</id>
  <international_phone_number>+61 2 9374 4000</international_phone_number>
  <website>http://www.google.com.au/</website>
  <review>
   <time>1338440552869</time>
   <text>Just went inside to have a look at Google. Amazing.</text>
   <author_name>Simon Bengtsson</author_name>
   <author_url>https://plus.google.com/104675092887960962573</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1338411244325</time>
   <text>Best place to work :-)</text>
   <author_name>Felix Rauch Valenti</author_name>
   <author_url>https://plus.google.com/103291556674373289857</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
  <review>
   <time>1330467089039</time>
   <text>Great place to work, always lots of free food!</text>
   <author_name>Chris</author_name>
   <author_url>https://maps.google.com/maps/user?uid=211457841236072500285</author_url>
   <language>en</language>
   <rating>5</rating>
   <aspect>
     <type>quality</type>
     <rating>3</rating>
   </aspect>
  </review>
 </result>
</PlaceDetailsResponse>

A JSON response contains three root elements:

  • "status" contains metadata on the request. See Status Codes below.
  • "result" contains the detailed information about the place requested. See Place Details Results for information about these results.
  • html_attributions contain a set of attributions about this listing which must be displayed to the user.

See Processing JSON with Javascript for help parsing JSON responses.

An XML response consists of a single <PlaceDetailsResponse> and three top-level elements:

  • <status> contains metadata on the request. See Status Codes.
  • A single <result> element containing detailed information about a single establishment. See Place Details Results for information about these results.
  • <html_attributions> contain a set of attributions which must be displayed to the user.

See Parsing XML with XPath for some recommended design patterns for output processing.

Status Codes

The "status" field within the Place response object contains the status of the request, and may contain debugging information to help you track down why the Place 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.
  • UNKNOWN_ERROR indicates a server-side error; trying again may be successful.
  • ZERO_RESULTS indicates that the reference was valid but no longer refers to a valid result. This may occur if the establishment is no longer in business.
  • 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 the query (reference) is missing.
  • NOT_FOUND indicates that the referenced location was not found in the Places database.

Error Messages

When the Places service returns a status code other than OK, there may be an additional error_message field within the details response object. This field contains more detailed information about the reasons behind the given status code.

Place Details Results

When the Places service returns results from a details request, it places them within a single result. Each result may contain the following fields:

  • address_components[] is an array of separate address components used to compose a given address. For example, the address "111 8th Avenue, New York, NY" contains separate address components for "111" (the street number, "8th Avenue" (the route), "New York" (the city) and "NY" (the US state). Each address_component typically contains:
    • types[] is an array indicating the type of the address component.
    • long_name is the full text description or name of the address component.
    • short_name is 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.
  • An events[] array or one or more <event> elements provide information about current events happening at this Place. Up to 10 events are returned, 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.
    • start_time: The event's start time, expressed in Unix time.
    • 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.
  • formatted_address is a string containing the human-readable address of this place. Often this address is equivalent to the "postal address," which sometimes differs from country to country. This address is generally composed of one or more address_component fields.
  • formatted_phone_number contains the Place's phone number in its local format. For example, the formatted_phone_number for Google's Sydney, Australia office is (02) 9374 4000.
  • geometry contains the following information:
    • location contains the geocoded latitude,longitude value for this place.
  • icon contains the URL of a suggested icon which may be displayed to the user when indicating this result on a map
  • id contains a unique stable identifier denoting this place. This identifier may not be used to retrieve information about this place, but can be used to consolidate data about this Place, and to verify the identity of a Place across separate searches. As ids can occasionally change, it's recommended that the stored id for a Place be compared with the id returned in later Details requests for the same Place, and updated if necessary.
  • international_phone_number 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 formatted_phone_number for Google's Sydney, Australia office is +61 2 9374 4000.
  • name contains the human-readable name for the returned result. For establishment results, this is usually the canonicalized business name.
  • opening_hours contains the following information:
    • open_now is a boolean value indicating if the Place is open at the current time.
    • periods[] is an array of opening periods covering seven days, starting from Sunday, in chronological order. Each period contains:
      • open contains a pair of day and time objects describing when the Place opens:
        • day a number from 0–6, corresponding to the days of the week, starting on Sunday. For example, 2 means Tuesday.
        • time 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.
      • close may contain a pair of day and time objects describing when the Place closes. Note: 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 0 and time with value 0000, and no close.
  • photos[] — an array of photo objects, each containing a reference to an image. A Place Details 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. 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 token that can be used to query the Details service in future. This token may differ from the reference used in the request to the Details service. It is recommended that stored references for Places be regularly updated. Although this token uniquely identifies the Place, the converse is not true: a Place may have many valid reference tokens.
  • reviews[] a JSON array of up to five reviews. If a language parameter was specified in the Place Details request, the Places Service will bias the results to prefer reviews written in that language. Each review consists of several components:
    • aspects contains a collection of AspectRating objects, each of which provides a rating of a single attribute of the establishment. The first object in the collection is considered the primary aspect. 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 user's rating for this particular aspect, from 0 to 3.
    • author_name the name of the user who submitted the review. Anonymous reviews are attributed to "A Google user".
    • author_url the URL to the users Google+ profile, if available.
    • language an IETF language code indicating the language used in the user's 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.
    • rating the user's overall rating for this Place. This is a whole number, ranging from 1 to 5.
    • text the user's review. When reviewing a location with Google Places, text reviews are considered optional. Therefore, this field may by empty. Note that this field may include simple HTML markup. For example, the entity reference &amp; may represent an ampersand character.
    • time the time that the review was submitted, measured in the number of seconds since since midnight, January 1, 1970 UTC.
  • 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.
  • url contains the official Google Place Page URL of this establishment. Applications must link to or embed the Google Place page on any screen that shows detailed results about this Place to the user.
  • utc_offset 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).
  • vicinity lists a simplified address for the Place, including the street name, street number, and locality, but not the province/state, postal code, or country. For example, Google's Sydney, Australia office has a vicinity value of 48 Pirrama Road, Pyrmont.
  • website lists the authoritative website for this Place, such as a business' homepage.

Multidimensional ratings may not be available for all locations. If there are too few reviews then the details response will either include a legacy rating on a 1.0 to 5.0 scale (if available) or no rating at all.

Premium Data

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

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.

  • aspects contains a collection of AspectRating objects, each of which provides an aggregate rating of a single attribute of the establishment. The first object in the collection is considered the primary aspect. Each AspectRating is described as:
    • type the name of the aspect that is being rated. For example, atmosphere, service, food, overall, etc.
    • 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.
  • review_summary includes a rich and concise review curated by Google's editorial staff. This field will be absent unless you pass the extensions=review_summary parameter in your details request. Note that this field may not be available in the requested language.
  • 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.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.