Place Details

Once you have a place_id or 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. Below is a list of the parameters and their possible values.

• 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. See Get a key for more information.
• Either placeid or reference (you must supply one of these, but not both):
  • placeid — A textual identifier that uniquely identifies a place, returned from a Place Search. For more information about place IDs, see the place ID overview.
  • reference — A textual identifier that uniquely identifies a place, returned from a Place Search. Note: The reference is now deprecated in favor of placeid. See the deprecation notice on this page.

• 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.

The following example requests the details of a place by placeid:

https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4&key=YOUR_API_KEY

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

The following example uses the deprecated reference parameter:

https://maps.googleapis.com/maps/api/place/details/json?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g&key=YOUR_API_KEY

Place Details Responses

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

{
   "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" ]
         }
      ],
      "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",
      "place_id" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "scope" : "GOOGLE",
      "alt_ids" : [
         {
            "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
            "scope" : "APP"
         }
      ],
      "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 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>
  <place_id>ChIJN1t_tDeuEmsRUsoyG83frY4</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <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 contains 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 an invalid key 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 Google 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.
• 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. Note: The id is now deprecated in favor of place_id. See the deprecation notice on this page.
• 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 international_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.
  • weekday_text is an array of seven strings representing the formatted opening hours for each day of the week. If a language parameter was specified in the Place Details request, the Places Service will format and localize the opening hours appropriately for that language. The ordering of the elements in this array depends on the language parameter. Some languages start the week on Monday while others start on Sunday.
• permanently_closed is a boolean flag indicating whether the place has permanently shut down (value true). If the place is not permanently closed, the flag is absent from the response.
• 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.
• place_id: A textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeId field of a Places API request. For more information about place IDs, see the place ID overview.
• scope: Indicates the scope of the place_id. The possible values are:
  • APP: The place ID is recognised by your application only. This is because your application added the place, and the place has not yet passed the moderation process.
  • GOOGLE: The place ID is available to other applications and on Google Maps.
• alt_ids — An array of zero, one or more alternative place IDs for the place, with a scope related to each alternative ID. Note: This array may be empty or not present. If present, it contains the following fields:
  • place_id — The most likely reason for a place to have an alternative place ID is if your application adds a place and receives an application-scoped place ID, then later receives a Google-scoped place ID after passing the moderation process.
  • scope — The scope of an alternative place ID will always be APP, indicating that the alternative place ID is recognised by your application only.
  For example, let's assume your application adds a place and receives a place_id of AAA for the new place. Later, the place passes the moderation process and receives a Google-scoped place_id of BBB. From this point on, the information for this place will contain:

      "results" : [
        {
          "place_id" : "BBB",
          "scope" : "GOOGLE",
          "alt_ids" : [
            {
              "place_id" : "AAA",
              "scope" : "APP",
            }
          ],
        }
      ]
      

• 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 aggregated 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. Note: The reference is now deprecated in favor of place_id. See the deprecation notice on this page.
• 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 & 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 URL of the official Google page for this place. This will be the Google-owned page that contains the best available information about the place. Applications must link to or embed this page on any screen that shows detailed results about the place to the user.
• 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

In addition to the fields listed above, Google Places API customers with a Premium Plan license 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.

The following example shows how the aspects and review_summary fields appear in the response body:

"aspects" : [
   {
      "rating" : 24,
      "type" : "food"
   },
   {
      "rating" : 21,
      "type" : "decor"
   },
   {
      "rating" : 24,
      "type" : "service"
   }
],

...

"review_summary" : "For a meal that's a \"leisurely celebration\",
Mountain View \"foodies\" head to this \"lovely\" old Victorian house, where
\"artful\", \"high-end\" New French tasting dinners that \"look great and taste
even better\" are enhanced by sommelier-selected wines and service that
\"anticipates your every need\"; a garden out back supplies some ingredients,
while four dining areas provide \"lovely decor and ambiance\"; P.S. an
abbreviated tasting menu is also available."

The sensor Parameter

The Google Places API Web Service 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.