Place Details

Note: Places field permanently_closed is deprecated

Note: Server-side and client-side libraries

The Places API is also available with the Java Client, Python Client, Go Client and Node.js Client for Google Maps Services. The Places API and the client libraries are for use in server applications.

If you're building a client-side application, take a look at the Places SDK for Android, the Places SDK for iOS, and the Places Library, Maps JavaScript API.

Once you have a place_id 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.

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. See Get a key for more information.
place_id (required) — A textual identifier that uniquely identifies a place, returned from a Place Search. For more information about place IDs, see the place ID overview.

Optional Parameters

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.
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, 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 resulting formatted_address for results in the specified region.
sessiontoken — A random string which identifies an autocomplete session for billing purposes. Use this for Place Details requests that are called following an autocomplete request in the same user session.
fields — One or more fields, specifying the types of place data to return, separated by a comma.

Warning: If you do not specify at least one field with a request, or if you omit the fields parameter from a request, ALL possible fields will be returned, and you will be billed accordingly. This applies only to Place Details requests.

Fields

Use the fields parameter to specify a comma-separated list of place data types to return. For example: fields=address_component,name,geometry. Use a forward slash when specifying compound values. For example: opening_hours/weekday_text.

Fields correspond to Place Details 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 it has been requested.

Basic

The Basic category includes the following fields:
address_component, adr_address, business_status, formatted_address, geometry, icon, name, permanently_closed (deprecated), photo, place_id, plus_code, type, url, utc_offset, vicinity

Contact

The Contact category includes the following fields:
formatted_phone_number, international_phone_number, opening_hours, website

Atmosphere

The Atmosphere category includes the following fields: price_level, rating, review, user_ratings_total

Caution: Place Search requests and Place Details requests do not return the same fields. Place Search requests return a subset of the fields that are returned by Place Details requests. If the field you want is not returned by Place Search, you can use Place Search to get a place_id, then use that Place ID to make a Place Details request.

Learn more about place fields. For more information about how Place data requests are billed, see Usage and Billing.

The following example requests the details of a place by place_id, and includes the name, rating, and formatted_phone_number fields:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJN1t_tDeuEmsRUsoyG83frY4&fields=name,rating,formatted_phone_number&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.

Place Details Responses

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

JSON

{
   "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "5",
            "short_name" : "5",
            "types" : [ "floor" ]
         },
         {
            "long_name" : "48",
            "short_name" : "48",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Pirrama Road",
            "short_name" : "Pirrama Rd",
            "types" : [ "route" ]
         },
         {
            "long_name" : "Pyrmont",
            "short_name" : "Pyrmont",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "Council of the City of Sydney",
            "short_name" : "Sydney",
            "types" : [ "administrative_area_level_2", "political" ]
         },
         {
            "long_name" : "New South Wales",
            "short_name" : "NSW",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "Australia",
            "short_name" : "AU",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "2009",
            "short_name" : "2009",
            "types" : [ "postal_code" ]
         }
      ],
      "adr_address" : "5, \u003cspan class=\"street-address\"\u003e48 Pirrama Rd\u003c/span\u003e, \u003cspan class=\"locality\"\u003ePyrmont\u003c/span\u003e \u003cspan class=\"region\"\u003eNSW\u003c/span\u003e \u003cspan class=\"postal-code\"\u003e2009\u003c/span\u003e, \u003cspan class=\"country-name\"\u003eAustralia\u003c/span\u003e",
      "formatted_address" : "5, 48 Pirrama Rd, Pyrmont NSW 2009, Australia",
      "formatted_phone_number" : "(02) 9374 4000",
      "geometry" : {
         "location" : {
            "lat" : -33.866651,
            "lng" : 151.195827
         },
         "viewport" : {
            "northeast" : {
               "lat" : -33.8653881697085,
               "lng" : 151.1969739802915
            },
            "southwest" : {
               "lat" : -33.86808613029149,
               "lng" : 151.1942760197085
            }
         }
      },
      "icon" : "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "international_phone_number" : "+61 2 9374 4000",
      "name" : "Google",
      "place_id" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "rating" : 4.5,
      "reference" : "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "reviews" : [
         {
            "author_name" : "Robert Ardill",
            "author_url" : "https://www.google.com/maps/contrib/106422854611155436041/reviews",
            "language" : "en",
            "profile_photo_url" : "https://lh3.googleusercontent.com/-T47KxWuAoJU/AAAAAAAAAAI/AAAAAAAAAZo/BDmyI12BZAs/s128-c0x00000000-cc-rp-mo-ba1/photo.jpg",
            "rating" : 5,
            "relative_time_description" : "a month ago",
            "text" : "Awesome offices. Great facilities, location and views. Staff are great hosts",
            "time" : 1491144016
         }
      ],
      "types" : [ "point_of_interest", "establishment" ],
      "url" : "https://maps.google.com/?cid=10281119596374313554",
      "utc_offset" : 600,
      "vicinity" : "5, 48 Pirrama Road, Pyrmont",
      "website" : "https://www.google.com.au/about/careers/locations/sydney/"
   },
   "status" : "OK"
}

XML


<?xml version="1.0" encoding="UTF-8"?>
<PlaceDetailsResponse>
   <status>OK</status>
   <result>
      <name>Google</name>
      <vicinity>5, 48 Pirrama Road, Pyrmont</vicinity>
      <type>point_of_interest</type>
      <type>establishment</type>
      <formatted_phone_number>(02) 9374 4000</formatted_phone_number>
      <formatted_address>5, 48 Pirrama Rd, Pyrmont NSW 2009, Australia</formatted_address>
      <address_component>
         <long_name>5</long_name>
         <short_name>5</short_name>
         <type>floor</type>
      </address_component>
      <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 Rd</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>Council of the City of Sydney</long_name>
         <short_name>Sydney</short_name>
         <type>administrative_area_level_2</type>
         <type>political</type>
      </address_component>
      <address_component>
         <long_name>New South Wales</long_name>
         <short_name>NSW</short_name>
         <type>administrative_area_level_1</type>
         <type>political</type>
      </address_component>
      <address_component>
         <long_name>Australia</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.8666510</lat>
            <lng>151.1958270</lng>
         </location>
         <viewport>
            <southwest>
               <lat>-33.8680861</lat>
               <lng>151.1942760</lng>
            </southwest>
            <northeast>
               <lat>-33.8653882</lat>
               <lng>151.1969740</lng>
            </northeast>
         </viewport>
      </geometry>
      <rating>4.5</rating>
      <url>https://maps.google.com/?cid=10281119596374313554</url>
      <icon>https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png</icon>
      <international_phone_number>+61 2 9374 4000</international_phone_number>
      <website>https://www.google.com.au/about/careers/locations/sydney/</website>
      <review>
         <time>1491144016</time>
         <text>Awesome offices. Great facilities, location and views. Staff are great hosts</text>
         <author_name>Robert Ardill</author_name>
         <author_url>https://www.google.com/maps/contrib/106422854611155436041/reviews</author_url>
         <rating>5.0</rating>
         <language>en</language>
         <profile_photo_url>https://lh3.googleusercontent.com/-T47KxWuAoJU/AAAAAAAAAAI/AAAAAAAAAZo/BDmyI12BZAs/s128-c0x00000000-cc-rp-mo-ba1/photo.jpg</profile_photo_url>
         <relative_time_description>a month ago</relative_time_description>
      </review>
      <utc_offset>600</utc_offset>
      <adr_address>
         5,
         <span class="street-address">48 Pirrama Rd</span>
         ,
         <span class="locality">Pyrmont</span>
         <span class="region">NSW</span>
         <span class="postal-code">2009</span>
         ,
         <span class="country-name">Australia</span>
      </adr_address>
      <place_id>ChIJN1t_tDeuEmsRUsoyG83frY4</place_id>
   </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.

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.

From our Terms of Service

Innovate, but don't
duplicate

Don't make a substitute for Google Maps. If your app's primary purpose is navigation, a business directory, or a general purpose "maps app", it's a substitute for Google Maps.

Learn more

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 referenced location (place_id) 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 any of the following:
- You have exceeded the QPS limits.
- Billing has not been enabled on your account.
- The monthly $200 credit, or a self-imposed usage cap, has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
See the Maps FAQ for more information about how to resolve this error.
REQUEST_DENIED indicates that your request was denied, generally because:
- The request is missing an API key.
- The key parameter is invalid.
INVALID_REQUEST generally indicates that the query (place_id) is missing.
NOT_FOUND indicates that the referenced location (place_id) 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. Because place data results cannot be empty, only place results with data are returned (for example, if a requested place has no photos, the photos field will not be present in the result). Each result may contain the following fields:

address_components[] is an array containing the separate components applicable to this address.
Each address component typically contains the following fields:
- types[] is an array indicating the type of the address component. See the list of supported types.
- long_name is the full text description or name of the address component as returned by the Geocoder.
- 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.
Note the following facts about the address_components[] array:
- The array of address components may contain more components than the formatted_address.
- The array does not necessarily include all the political entities that contain an address, apart from those included in the formatted_address. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
- The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_components varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the component can change. A particular component may be missing in a later response.
business_status indicates the operational status of the place, if it is a business. It can contain one of the following values:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
If no data exists, business_status is not returned.
formatted_address is a string containing the human-readable address of this place.
Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.

The formatted address is logically composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state).

Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field.
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.
adr_address is a representation of the place's address in the adr microformat.
geometry contains the following information:
- location contains the geocoded latitude,longitude value for this place.
- viewport contains the preferred viewport when displaying this place on a map as a LatLngBounds if it is known.
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).
Typically, both the global code and compound code are returned. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.
icon contains the URL of a suggested icon which may be displayed to the user when indicating this result on a map.
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.
See this video for how to use opening hours with Place Details.
permanently_closed (deprecated) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true). If the place is operational, or if no data is available, the flag is absent from the response.

Notice: permanently_closed is now deprecated. Instead, use business_status to get the operational status of businesses.

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.
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.
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:
- 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 user's Google Maps Local Guides profile, if available.
- profile_photo_url the URL to the user's profile photo, 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.
- relative_time_description the time that the review was submitted, relative to the current time.
- 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. 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.

From our Terms of Service

Serve the freshest data

Data can change over time, so request only what you need, when you need it. Specifically, don't store Google data for longer than 30 days, and don't pre-fetch or cache to avoid future API calls.

Learn More

The `sensor` Parameter

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

Place Details

Place Details Requests

Fields

Place Details Responses

Status Codes

Error Messages

Place Details Results

The sensor Parameter

The `sensor` Parameter