Places Library

Note: Server-side
libraries

This page describes the client-side library available with
the Maps JavaScript API. If you want to work with the
Places API web service on your server, take a look at the
Node.js Client for Google Maps Services. The page at
that link also introduces the Java Client,
Python Client and Go Client for Google Maps Services.

Overview

The functions in the Places Library, Maps JavaScript API enable your application
to search for places (defined in this API as establishments, geographic
locations, or prominent points of interest) contained within a defined area,
such as the bounds of a map, or around a fixed point.

The Places API offers an autocomplete feature which you can use
to give your applications the type-ahead-search behavior of the Google Maps
search field. When a user starts typing an address, autocomplete will
fill in the rest. For more information, see the
autocomplete
documentation.

Getting started

If you are unfamiliar with the Maps JavaScript API or with
JavaScript, we recommend reviewing JavaScript and
Get an API Key prior
to getting started.

Enable APIs

Before using the Places library in the Maps JavaScript API, first ensure
that the Places API is enabled in the Google Cloud Platform Console, in the same
project you set up for the Maps JavaScript API.

Click the Select a project button, then select the same project you set up
for the Maps JavaScript API and click Open.

From the list of APIs on the Dashboard, look for
Places API.

If you see the Places API in the list, it's already enabled. If the API
is not listed, enable it:

At the top of the page, select ENABLE APIS AND SERVICES to display the
Library tab. Alternatively, from the left side menu,
select Library.

Search for Places API, then select it from the
results list.

Select ENABLE. When the process finishes,
Places API appears in the list of APIs on the
Dashboard.

Loading the library

The Places service is a self-contained library, separate from the main
Maps JavaScript API code. To use the functionality contained
within this library, you must first load it using the libraries
parameter in the Maps API bootstrap URL:

Add Places API to the API key's API restrictions list

Applying API restrictions to your keys limits usage of the API key to one or
more APIs or SDKs. Requests to an API or SDK associated with the API key will
be processed. Requests to an API or SDK not associated with the API key will
fail.
To restrict an API key for use with the Places Library, Maps JavaScript API:

Click the project drop-down and select the project that contains the
API key you want to secure.

Click the menu button
and select APIs & Services > Credentials.

On the Credentials page, click the name of the API
key that you want to secure.

On the Restrict and rename API key page, set the restrictions:

API restrictions

Select Restrict key.

Click Select APIs and select both Maps JavaScript API and Places API.
(If either of the APIs is not listed, you need to enable it.)

Click SAVE.

Usage limits and policies

Quotas

The Places Library, JavaScript API shares a usage quota with
Places API as described in the Usage Limits documentation for
Places API. The queries per second rate limit is applied
per user session, regardless of how many users share the same project.*

* Note: When you first load the API, you are allocated an initial
quota of requests. Once you use this quota, the API enforces rate limits on additional
requests on a per-second basis. If too many requests are made within a certain time
period, the API returns an OVER_QUERY_LIMIT response code. The per-session rate limit
prevents the use of client-side services for batch requests. For batch requests, use
our web service APIs.

The information returned can include establishments — such as
restaurants, stores, and offices — as well as 'geocode' results, which
indicate addresses, political areas such as towns and cities, and other
points of interest.

Find Place requests

A Find Place request lets you search for a place either by text query or
phone number. There are two types of Find Place request:

Find Place from Query

Find Place from Query takes a text input and returns a place. The input can
be any kind of Place data, for example a business name or address. To make a
Find Place from Query request, call the PlaceService's
findPlaceFromQuery()
method, which takes the following parameters:

query (required) A text string on which to search.

fields (required) One or more fields
specifying the types of Place data to return.

locationBias
(optional) Coordinates defining the area to search. This can be one of the
following:

Find Place from Phone Number

Find Place from Phone Number takes a phone number and returns a place. To
make a Find Place from Phone Number request, call the
PlaceService's findPlaceFromPhoneNumber()
method, which takes the following parameters:

You must also pass a callback method to findPlaceFromPhoneNumber(),
to handle the results object and google.maps.places.PlacesServiceStatus
response.

Fields (Find Place methods)

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

Fields correspond to Place Search results, and are divided
into three billing categories: Basic, Contact, and Atmosphere. Basic fields are
billed at base rate, and incur no additional charges. Contact and Atmosphere
fields are billed at a higher rate. See the pricing sheet
for more information. Attributions (html_attributions) are always
returned with every call, regardless of whether the field has been
requested.

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.

Basic

The Basic category includes the following fields:formatted_address, geometry, icon,name,
permanently_closed, photos, place_id,plus_code,
types

Contact

The Contact category includes the following field:
opening_hours (Place Search returns only
open_now; use a Place Details request to get the
full opening_hours results).

Atmosphere

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

The findPlaceFromQuery() and
findPlaceFromPhoneNumber() methods each take the same set of
fields, and can return the same fields in their respective responses.

Set location bias (Find Place methods)

Use the locationBias parameter to make Find Place favor results
in a particular area. You can set locationBias in the following
ways:

Nearby Search Requests

Nearby Search and Text Search return all of the
available data fields for the selected place (a
subset of the supported fields),
and you will be
billed accordingly
There is no way to constrain Nearby Search or Text Search to only return specific fields.
To keep from requesting (and paying for) data that you don't need, use a
Find Place request instead.

A Nearby Search lets you search for places within a specified area by
keyword or type. A Nearby Search must always include a location, which can
be specified in one of two ways:

a circular area defined as the combination of the location
property — specifying the center of the circle as a
LatLng object — and a radius, measured in meters.

A Places Nearby search is initiated with a call to the
PlacesService's nearbySearch() method, which will
return an array of
PlaceResult objects. Note that the nearbySearch()
method replaces the search() method as of version 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

This method takes a request with the following fields:

Either of:

bounds, which must be a
google.maps.LatLngBounds object defining the rectangular
search area; or

a location and a radius; the former takes a
google.maps.LatLng object, and the latter takes a simple
integer, representing the circle's radius in meters. The maximum
allowed radius is 50 000 meters. Note that when
rankBy is set to DISTANCE, you must specify a
location but you cannot specify a radius
or bounds.

keyword (optional) — A term to be matched
against all available fields, including but not limited to name, type, and
address, as well as customer reviews and other third-party content.

name (optional) — A term to be matched
against the names of places. Results will be restricted to those
containing the passed name value. 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 (optional) — A boolean value,
indicating that the Places service should only return 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. Setting
openNow to false has no effect.

rankBy (optional) — Specifies the order in
which results are listed. Possible values are:

google.maps.places.RankBy.PROMINENCE (default). This
option sorts results based on their importance. Ranking will
favor prominent places within the set radius over nearby
places that match but that are less prominent. Prominence can be
affected by a place's ranking in Google's index, global popularity,
and other factors. When
google.maps.places.RankBy.PROMINENCE is
specified, the radius parameter is required.

google.maps.places.RankBy.DISTANCE. This option
sorts results in ascending order by their distance from the specified
location (required). Note that you cannot specify a
custom bounds and/or radius if you
specify RankBy.DISTANCE. When you specify
RankBy.DISTANCE, one or more of
keyword, name, or type is
required.

type — Restricts the
results to places matching the specified type. Only one type may be
specified (if more than one type is provided, all types following the first
entry are ignored). See the list of
supported types.

You must also pass a callback method to nearbySearch(), to
handle the results object and
google.maps.places.PlacesServiceStatus response.

Text Search Requests

Nearby Search and Text Search return all of the
available data fields for the selected place (a
subset of the supported fields),
and you will be
billed accordingly
There is no way to constrain Nearby Search or Text Search to only return specific fields.
To keep from requesting (and paying for) data that you don't need, use a
Find Place request instead.

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

Text Searches are initiated with a call to the
PlacesService's textSearch() method.

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

This method takes a request with the following fields:

query (required) The text string on which to
search, for example: "restaurant". The Places service will return candidate
matches based on this string and order the results based on their
perceived relevance. This parameter becomes optional if the type
parameter is also used in the search request.

Optionally:

openNow — A boolean value,
indicating that the Places service should only return 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. Setting
openNow to false has no effect.

minPriceLevel and maxPriceLevel
— 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.

Either of:

bounds — A
google.maps.LatLngBounds object defining the rectangle
in which to search; or

a location and a radius — You may
bias results to a specified circle by passing a
location and a radius parameter. This will
instruct the Places service to prefer showing results within that
circle. Results outside the defined area may still be displayed.
The location takes a google.maps.LatLng object, and
the radius takes a simple integer, representing the circle's radius
in meters. The maximum allowed radius is 50 000 meters.

type — Restricts the results to places matching
the specified type. Only one type may be specified (if more than one
type is provided, all types following the first entry are ignored). See
the list of supported types.

You must also pass a callback method to textSearch(), to
handle the results object and a
google.maps.places.PlacesServiceStatus response.

Search Responses

Status Codes

The PlacesServiceStatus response object contains the status of
the request, and may contain debugging information to help you track down
why the place request failed. Possible status values are:

INVALID_REQUEST: This request was invalid.

OK: The response contains a valid result.

OVER_QUERY_LIMIT: The webpage has gone over its request
quota.

REQUEST_DENIED: The webpage is not allowed to use the
PlacesService.

UNKNOWN_ERROR: The PlacesService request could not be
processed due to a server error. The request may succeed if you try again.

ZERO_RESULTS: No result was found for this request.

Place Search Results

The nearbySearch() and textSearch() functions
return an array of
PlaceResult objects.

Each PlaceResult object may include the following properties:

formatted_address is a string containing the human-readable
address of this place. The formatted_address property is only
returned for a Text Search.

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.

geometry: The place's geometry-related information. This
includes:

location provides the latitude and longitude of the
place.

viewport defines the preferred viewport on the map when
viewing this place.

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.

html_attributions: An array of attributions that you should
display when displaying the search results. Each entry in the array contains
the HTML text for a single attribution. Note: This is an
aggregation of all the attributions for the entire search response. All
PlaceResult objects in the response therefore contain
identical attribution lists.

icon: URL to an image resource that can be used to
represent this place's type.

name: The place's name.

opening_hours may contain the following information:

open_now is a boolean value indicating if the place
is open at the current time.

rating contains the place's rating, from 0.0 to 5.0, based
on aggregated user reviews.

types An array of
types for this place (e.g., ["political", "locality"] or
["restaurant", "lodging"]). This array may contain multiple
values. See the list of
supported types

vicinity: 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 5/48 Pirrama
Road, Pyrmont.

Accessing Additional Results

By default, each place search returns up to 20 results per query. However,
each search can return as many as 60 results, split across three pages.
Additional pages are available via the PlaceSearchPagination
object. In order to access additional pages you must capture the
PlaceSearchPagination object via a callback function. The
PlaceSearchPagination object is defined as:

hasNextPage a boolean property that indicates if further
results are available. true when there is an additional
results page.

nextPage() a function that will return the next set of
results. After executing a search, you must wait two
seconds before the next page of results will be available.

To see the next set of results, call nextPage.
Each page of results must be displayed before displaying the next page of
results. Note that each search counts as a single request against your
usage limits.

The example below demonstrates how to alter your callback function to
capture the PlaceSearchPagination object, so that you can issue
multiple search requests.

Place Details

In addition to providing a list of places within an area, the Places
service can also return detailed information about a specific place. Once
a place has been returned in a place search response, its
place ID can be used to request additional details
about that place, such as its complete address, phone number, user rating
and reviews, etc.

Place Details Requests

Place Details are requested with a call to the service's
getDetails() method.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

This method takes a request, containing the desired place's
placeId, and fields indicating which types of Places data
to return. Learn more about
how to reference a place with a place ID.

It also takes a callback method, which needs to handle the status code passed
in the google.maps.places.PlacesServiceStatus response, as well
as the google.maps.places.PlaceResult object.

You can request the place_id for a place,
free of charge.
To do this, call getDetails(), and specify only the place_id
field.

Fields (Place details)

The fields parameter takes an array of strings (field names).

Use the fields parameter to specify a comma-separated list of
place data types to return. For example: fields=address_component,opening_hours,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.

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.

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 (including Place
Details requests made from the
Place Autocomplete widget).

Place Details Responses

Status Codes

The PlacesServiceStatus response object contains the status of
the request, and may contain debugging information to help you track down
why the Place Details request failed. Possible status values are:

INVALID_REQUEST: This request was invalid.

OK: The response contains a valid result.

OVER_QUERY_LIMIT: The webpage has gone over its request
quota.

NOT_FOUND The referenced location was not
found in the Places database.

REQUEST_DENIED: The webpage is not allowed to use the
PlacesService.

UNKNOWN_ERROR: The PlacesService request could not be
processed due to a server error. The request may succeed if you try again.

ZERO_RESULTS: No result was found for this request.

Place Details Results

A successful getDetails() call returns a
PlaceResult object with the following properties:

address_components: 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.

formatted_address: 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.

viewport defines the preferred viewport on the map when
viewing this place.

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.

html_attributions: Attribution text to be displayed for
this place result.

icon: URL to an image resource that can be used to
represent this place's type.

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: The place's name.

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

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

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. Applications 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: 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 PlacePhoto objects.
A PlacePhoto can be used to obtain a photo with the
getUrl() method, or you can inspect the object for the
following values:

height: the maximum height of the image, in pixels.

width: the maximum width of the image, in pixels.

html_attributions: Attribution text to be displayed
with this place photo.

rating: The place's rating, from 0.0 to 5.0, based on
aggregated user reviews.

reviews an array of up to five reviews. Each review
consists of several components:

aspects[] contains an array of
PlaceAspectRating objects, each of which provides a
rating of a single attribute of the establishment. The first object
in the array is considered the primary aspect. Each
PlaceAspectRating is defined 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". If a
language parameter was set, then the phrase "A Google user" will
return a localized string.

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.

types An array of
types for this place (e.g., ["political", "locality"] or
["restaurant", "lodging"]). The array can contain multiple
values. See the list of
supported types.

url: URL of the official Google page for this
place. This is 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.

vicinity: 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 5/48 Pirrama
Road, Pyrmont. The vicinity property is only returned
for a Nearby Search.

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 0.0 to 5.0 scale (if available) or no
rating at all.

Referencing a Place with a Place ID

A place ID is a unique reference to a place on a Google Map. Place IDs
are available for most locations, including businesses, landmarks, parks,
and intersections.

To use a place ID in your app you must first look up the ID, which is
available in PlaceResult of a Place Search or Details request.
You can then use this place ID to look up
Place
Details.

Note: Place IDs are also available through
the Places API.
A single place ID refers to only one place, but a place can have multiple
place IDs. For more information, see the
place ID overview.

Place IDs are exempt from the caching restrictions stated
in Section 3.2.4(a) of the
Google Maps Platform Terms of Service. You can therefore store place ID values for later use. For
best practises when storing place IDs, see the
place ID overview.

Place Photos

The Place Photo feature allows you to add high quality photographic
content to your site. The Photo service gives you access to the millions of
photos stored in the Places and Google+ Local database. When you get place
information using a Place Details request, photo
references will be returned for relevant photographic content. The Nearby Search
and Text Search requests also return a single photo reference per place, when
relevant. Using the Photo service you can then access the referenced photos and
resize the image to the optimal size for your application.

An array of PlacePhoto objects will be returned as part of the
PlaceResult object for any getDetails(),
textSearch() or
nearbySearch() request made against a PlacesService.

Note: The number of photos returned varies by request.

A Nearby Search or a Text Search will return at most one
PlacePhoto object.

A Details request will return up to ten PlacePhoto objects.

You can request the URL for the associated image by calling the
PlacePhoto.getUrl() method, and passing a valid
PhotoOptions object. The PhotoOptions object allows
you to specify the maximum desired height and width of the image. If you
specify a value for both maxHeight and a maxWidth,
the photo service will resize the image to the smaller of the two sizes, while
maintaining the original aspect ratio.

The following code snippet accepts a place object, and adds a marker
to the map if a photo exists. The default marker image is replaced
by a small version of the photo.