**European Economic Area (EEA) developers**
> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt).
> [!NOTE]
> This product is in [Legacy status](https://developers.google.com/maps/legacy.md.txt). As of October 2026, Places API (Legacy) can no longer be enabled for new Google Cloud projects. Existing projects remain fully supported. For new features and improved performance, [migrate
> to Places API (New)](https://developers.google.com/maps/documentation/places/web-service/legacy/migrate-overview).
**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](https://developers.google.com/maps/documentation/places/web-service/client-library).
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 (New)](https://developers.google.com/maps/documentation/places/android-sdk), the
[Places SDK for iOS (New)](https://developers.google.com/maps/documentation/places/ios-sdk), and the
[Places Library, Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/places).
Place Autocomplete (Legacy) is a web service that returns place
predictions in response to an HTTP request. The request specifies a textual
search string and optional geographic bounds. The service can be used to
provide autocomplete functionality for text-based geographic searches, by
returning places such as businesses, addresses and points of interest as a
user types.
## Place Autocomplete (Legacy) requests
Place Autocomplete (Legacy) is part of the
Places API and shares an
[API key](https://developers.google.com/maps/documentation/places/web-service/get-api-key.md.txt) and quotas with the
[Places API](https://developers.google.com/maps/documentation/places/web-service/overview.md.txt).
> [!NOTE]
> **Note:** You can use Place Autocomplete (Legacy) even without a map. If you do show a map, it must be a Google map. When you display predictions from Place Autocomplete (Legacy) without a map, you must include the Google logo displayed inline with the search field/results. For more information, see [Displaying the Google logo and attributions](https://developers.google.com/maps/documentation/places/web-service/policies.md.txt#logo).
Place Autocomplete (Legacy) can match on full words and substrings,
resolving place names, addresses, and [plus
codes](https://plus.codes). Applications can therefore send queries as the user types, to provide
on-the-fly place predictions.
You must properly format plus codes. This means you must URL-escape the plus sign to
`%2B`, and you must URL-escape spaces to `%20`.
- **global code** is a four character area code, and six character or longer local code. For example, the URL-escape global code `849VCWC8+R9` is `849VCWC8%2BR9`.
- **compound code** is a six character (or longer) local code with an explicit location. For example, the URL-escaped compound code `CWC8+R9 Mountain View, CA, USA` is `CWC8%2BR9%20Mountain%20View%20CA%20USA`.
The returned predictions are designed to be presented to the user to aid them
in selecting the place they want. You can send a
[Place Details (Legacy)
request](https://developers.google.com/maps/documentation/places/web-service/details#PlaceDetailsRequests) for more information about any of the places which are
returned.
A Place Autocomplete (Legacy) request is an HTTP URL of the following form:
```
https://maps.googleapis.com/maps/api/place/autocomplete/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 Place Autocomplete (Legacy) 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.
## Required parameters
### input
The text string on which to search. The Place Autocomplete service will
return candidate matches based on this string and order results based on
their perceived relevance.
## Optional parameters
### components
A grouping of places to which you would like to restrict your results.
You can use components to filter by up to 5 countries.
Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible
country code. For example: `components=country:fr` would
restrict your results to places within France. Multiple countries must be
passed as multiple `country:XX` filters, with the pipe
character `|` as a separator. For example:
`components=country:us|country:pr|country:vi|country:gu|country:mp`
would restrict your results to places within the United States and its
unincorporated organized territories.
**Note:** If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at [Wikipedia: List of ISO 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) or the [ISO Online Browsing Platform](https://www.iso.org/obp/ui/#search).
### language
The language in which to return results.
- See the [list of supported languages](https://developers.google.com/maps/faq.md.txt#languagesupport). Google often updates the supported languages, so this list may not be exhaustive.
- If `language` is not supplied, the API attempts to use the preferred language as specified in the `Accept-Language` header.
- The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
- If a name is not available in the preferred language, the API uses the closest match.
- The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, *utca* and *tér* are synonyms for street in Hungarian.
### location
The point around which to retrieve place information. This must be
specified as `latitude,longitude`. The
`radius` parameter must also be provided when specifying a
location. If `radius` is not provided, the
`location` parameter is ignored.
When using the Text Search API, the \`location\` parameter may be overridden if the \`query\` contains an explicit location such as \`Market in Barcelona\`.
### locationbias
Prefer results in a specified area, by specifying either a radius plus
lat/lng, or two lat/lng pairs representing the points of a rectangle. If
this parameter is not specified, the API uses IP address biasing by
default.
- IP bias: Instructs the API to use IP address biasing. Pass the string `ipbias` (this option has no additional parameters).
- Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: `circle:radius@lat,lng`.
- Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:`rectangle:south,west|north,east`. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.
### locationrestriction
Restrict results to a specified area, by specifying either a radius plus
lat/lng, or two lat/lng pairs representing the points of a rectangle.
- Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: `circle:radius@lat,lng`.
- Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:`rectangle:south,west|north,east`. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.
### offset
The position, in the input term, of the last character that the service
uses to match predictions. For example, if the input is
`Google` and the offset is 3, the service will match on
`Goo`. The string determined by the offset is matched against
the first word in the input term only. For example, if the input term is
`Google abc` and the offset is 3, the service will attempt to
match against `Goo abc`. If no offset is supplied, the service
will use the whole term. The offset should generally be set to the
position of the text caret.
### origin
The origin point from which to calculate straight-line distance to the
destination (returned as `distance_meters`). If this value is
omitted, straight-line distance won't be returned. Must be specified as
`latitude,longitude`.
### radius
Defines the distance (in meters) within which to return place results. You
may bias results to a specified circle by passing a
`location` and a `radius` parameter. Doing so
instructs the Places service to *prefer* showing results within
that circle; results outside of the defined area may still be displayed.
The radius will automatically be clamped to a maximum value depending on
the type of search and other parameters.
- Autocomplete: 50,000 meters
- Nearby Search:
- with `keyword` or `name`: 50,000 meters
- without `keyword` or `name`
- Up to 50,000 meters, adjusted dynamically based on area density, independent of `rankby` parameter.
- When using `rankby=distance`, the radius parameter won't be accepted, and will result in an `INVALID_REQUEST`.
- Query Autocomplete: 50,000 meters
- Text Search: 50,000 meters
### region
The region code, specified as a
[ccTLD ("top-level domain")](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains)
two-character value. Most ccTLD codes are identical to ISO 3166-1 codes,
with some notable exceptions. For example, the United Kingdom's ccTLD is
"uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the
entity of "The United Kingdom of Great Britain and Northern Ireland").
### sessiontoken
A random string which identifies an autocomplete
[session](https://developers.google.com/maps/documentation/places/web-service/details#session_tokens)
for billing purposes.
The session begins when the user starts typing a query, and concludes when
they select a place and a call to Place Details is made. Each session can
have multiple queries, followed by one place selection. The API key(s)
used for each request within a session must belong to the same Google
Cloud Console project. Once a session has concluded, the token is no
longer valid; your app must generate a fresh token for each session. If
the `sessiontoken` parameter is omitted, or if you reuse a
session token, the session is charged as if no session token was provided
(each request is billed separately).
We recommend the following guidelines:
- Use session tokens for all autocomplete sessions.
- Generate a fresh token for each session. Using a version 4 UUID is recommended.
- Ensure that the API key(s) used for all Place Autocomplete and Place Details requests within a session belong to the same Cloud Console project.
- Be sure to pass a unique session token for each new session. Using the same token for more than one session will result in each request being billed individually.
### strictbounds
Returns only those places that are strictly within the region defined by
`location` and `radius`. This is a restriction,
rather than a bias, meaning that results outside this region won't be
returned even if they match the user input.
### types
You can restrict results from a Place Autocomplete request to be of a
certain type by passing the `types` parameter. This parameter
specifies a type or a type collection, as listed in
[Place Types](https://developers.google.com/maps/documentation/places/web-service/supported_types). If nothing is specified, all types are returned.
A place can only have a **single primary type** from types listed in
[Table 1](https://developers.google.com/maps/documentation/places/web-service/supported_types#table1) or
[Table 2](https://developers.google.com/maps/documentation/places/web-service/supported_types#table2). For
example, a hotel where food is served may by returned only with `types=lodging`
and not with `types=restaurant`.
For the value of the `types` parameter you can specify either:
-
Up to five values from
[Table 1](https://developers.google.com/maps/documentation/places/web-service/supported_types#table1)
or
[Table 2](https://developers.google.com/maps/documentation/places/web-service/supported_types#table2). For multiple values, separate each value with a
`|` (vertical bar). For example:
`types=book_store|cafe`
-
Any single supported filter in
[Table 3](https://developers.google.com/maps/documentation/places/web-service/supported_types#table3). You cannot mix type collections.
> [!NOTE]
> **Note:** Although `geocode` and `establishment` are part of Table 2, they cannot be combined with any other type in Tables 1, 2, or 3 in Place Autocomplete request filters.
The request will be rejected with an `INVALID_REQUEST` error
if:
- More than five types are specified.
- Any unrecognized types are present.
- Any types from in [Table 1](https://developers.google.com/maps/documentation/places/web-service/supported_types#table1) or [Table 2](https://developers.google.com/maps/documentation/places/web-service/supported_types#table2) are mixed with any of the filters in [Table 3](https://developers.google.com/maps/documentation/places/web-service/supported_types#table3).
**Note:** The `types` parameter only works on the primary type of the place, not all types associated with the place. Although every place has a primary type, not every primary type is supported by Places API (New). Supported types include those listed in [Table 1](https://developers.google.com/maps/documentation/places/web-service/supported_types#table1) or [Table 2](https://developers.google.com/maps/documentation/places/web-service/supported_types#table2).
## Place Autocomplete (Legacy) examples
A request for establishments containing the string "Amoeba" within
an area centered in San Francisco, CA:
### URL
```
https://maps.googleapis.com/maps/api/place/autocomplete/json
?input=amoeba
&types=establishment
&location=37.76999%2C-122.44696
&radius=500
&key=YOUR_API_KEY
```
### curl
```console
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'
```
The same request, restricted to results within 500 meters of Ashbury St \& Haight St,
San Francisco:
### URL
```
https://maps.googleapis.com/maps/api/place/autocomplete/json
?input=amoeba
&types=establishment
&location=37.76999%2C-122.44696&radius=500
&strictbounds=true
&key=YOUR_API_KEY
```
### curl
```console
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'
```
A request for addresses containing "Vict" with results in French:
### URL
```
https://maps.googleapis.com/maps/api/place/autocomplete/json
?input=Vict
&types=geocode
&language=fr
&key=YOUR_API_KEY
```
### curl
```console
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'
```
A request for cities containing "Vict" with results in Brazilian Portuguese:
### URL
```
https://maps.googleapis.com/maps/api/place/autocomplete/json
?input=Vict
&types=(cities)
&language=pt_BR&key=YOUR_API_KEY
```
### curl
```console
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'
```
Note that you'll need to replace the
[API key](https://developers.google.com/maps/documentation/places/web-service/get-api-key.md.txt)
in these examples with your own key.
## Place Autocomplete (Legacy) response
Place Autocomplete (Legacy) responses are returned in the format indicated by the
`output` flag within the request's URL path. The results below are
indicative of what may be returned for a query with the following
parameters:
### URL
```
https://maps.googleapis.com/maps/api/place/autocomplete/json
?input=Paris
&types=geocode
&key=YOUR_API_KEY
```
### curl
```console
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'
```
### JSON
```json
{
"predictions":
[
{
"description": "Paris, France",
"matched_substrings": [{ "length": 5, "offset": 0 }],
"place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
"reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
"structured_formatting":
{
"main_text": "Paris",
"main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
"secondary_text": "France",
},
"terms":
[
{ "offset": 0, "value": "Paris" },
{ "offset": 7, "value": "France" },
],
"types": ["locality", "political", "geocode"],
},
{
"description": "Paris, TX, USA",
"matched_substrings": [{ "length": 5, "offset": 0 }],
"place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
"reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
"structured_formatting":
{
"main_text": "Paris",
"main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
"secondary_text": "TX, USA",
},
"terms":
[
{ "offset": 0, "value": "Paris" },
{ "offset": 7, "value": "TX" },
{ "offset": 11, "value": "USA" },
],
"types": ["locality", "political", "geocode"],
},
{
"description": "Paris, TN, USA",
"matched_substrings": [{ "length": 5, "offset": 0 }],
"place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
"reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
"structured_formatting":
{
"main_text": "Paris",
"main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
"secondary_text": "TN, USA",
},
"terms":
[
{ "offset": 0, "value": "Paris" },
{ "offset": 7, "value": "TN" },
{ "offset": 11, "value": "USA" },
],
"types": ["locality", "political", "geocode"],
},
{
"description": "Paris, Brant, ON, Canada",
"matched_substrings": [{ "length": 5, "offset": 0 }],
"place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
"reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
"structured_formatting":
{
"main_text": "Paris",
"main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
"secondary_text": "Brant, ON, Canada",
},
"terms":
[
{ "offset": 0, "value": "Paris" },
{ "offset": 7, "value": "Brant" },
{ "offset": 14, "value": "ON" },
{ "offset": 18, "value": "Canada" },
],
"types": ["neighborhood", "political", "geocode"],
},
{
"description": "Paris, KY, USA",
"matched_substrings": [{ "length": 5, "offset": 0 }],
"place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
"reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
"structured_formatting":
{
"main_text": "Paris",
"main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
"secondary_text": "KY, USA",
},
"terms":
[
{ "offset": 0, "value": "Paris" },
{ "offset": 7, "value": "KY" },
{ "offset": 11, "value": "USA" },
],
"types": ["locality", "political", "geocode"],
},
],
"status": "OK",
}
```
### XML
```xml
OK
Paris, France
locality
political
geocode
ChIJD7fiBh9u5kcRYJSMaMOCCwQ
Paris
0
France
7
0
5
ChIJD7fiBh9u5kcRYJSMaMOCCwQ
Paris
France
0
5
Paris, TX, USA
locality
political
geocode
ChIJmysnFgZYSoYRSfPTL2YJuck
Paris
0
TX
7
USA
11
0
5
ChIJmysnFgZYSoYRSfPTL2YJuck
Paris
TX, USA
0
5
Paris, TN, USA
locality
political
geocode
ChIJ4zHP-Sije4gRBDEsVxunOWg
Paris
0
TN
7
USA
11
0
5
ChIJ4zHP-Sije4gRBDEsVxunOWg
Paris
TN, USA
0
5
Paris, Brant, ON, Canada
neighborhood
political
geocode
ChIJsamfQbVtLIgR-X18G75Hyi0
Paris
0
Brant
7
ON
14
Canada
18
0
5
ChIJsamfQbVtLIgR-X18G75Hyi0
Paris
Brant, ON, Canada
0
5
Paris, KY, USA
locality
political
geocode
ChIJsU7_xMfKQ4gReI89RJn0-RQ
Paris
0
KY
7
USA
11
0
5
ChIJsU7_xMfKQ4gReI89RJn0-RQ
Paris
KY, USA
0
5
```
### PlacesAutocompleteResponse
| Field | Required | Type | Description |
|:---|---|---|---|
| #### `predictions` | **required** | Array\<[PlaceAutocompletePrediction](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompletePrediction "PlaceAutocompletePrediction")\> | Contains an array of predictions. See [PlaceAutocompletePrediction](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompletePrediction) for more information. |
| #### `status` | **required** | [PlacesAutocompleteStatus](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlacesAutocompleteStatus "PlacesAutocompleteStatus") | Contains the status of the request, and may contain debugging information to help you track down why the request failed. See [PlacesAutocompleteStatus](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlacesAutocompleteStatus) for more information. |
| #### `error_message` | optional | string | When the service returns a status code other than `OK<`, there may be an additional `error_message` field within the response object. This field contains more detailed information about the reasons behind the given status code. This field is not always returned, and its content is subject to change. |
| #### `info_messages` | optional | Array\ | When the service returns additional information about the request specification, there may be an additional `info_messages` field within the response object. This field is only returned for successful requests. It may not always be returned, and its content is subject to change. |
Of particular interest within the results are the `place_id`
elements, which can be used to request more specific details about the
place using a separate query. See
[Place Details (Legacy)
requests](https://developers.google.com/maps/documentation/places/web-service/details#PlaceDetailsRequests).
An **XML response** consists of a single
`` element with two types of child
elements:
- A single `` element contains metadata on the request. See [Status Codes](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlacesAutocompleteStatus) below.
- Zero or more `` elements, each containing information about a single place. See [Place Autocomplete (Legacy) Results](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompletePrediction) for information about these results. The Places API returns up to 5 results.
We recommend that you use `json` as the preferred output flag
unless your application requires `xml` for some reason.
Processing XML trees requires some care, so that you reference proper nodes
and elements. See
[Processing
XML with XPath](https://developers.google.com/maps/documentation/directions/web-service-best-practices#ParsingXML) for help processing XML.
> [!NOTE]
> The `street_number` address component may not be present in Place Details (Legacy) responses for place IDs in some autocomplete predictions. This typically happens when the address cannot be interpolated for a place. In these cases, the prediction's `types` array will contain "route". For autocomplete predictions with a number in the description (input query is matched), the Place Details (Legacy) response for the place ID contains the street number only if the `types` array for the prediction contains at least one of:
>
> - street_address
> - premise
> - establishment
### PlacesAutocompleteStatus
Status codes returned by service.
- `OK` indicating the API request was successful.
- `ZERO_RESULTS` indicating that the search was successful but returned no results. This may occur if the search was passed a bounds in a remote location.
- `INVALID_REQUEST` indicating the API request was malformed, generally due to the missing `input` parameter.
- `OVER_QUERY_LIMIT` indicating 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](https://developers.google.com/maps/faq.md.txt#over-limit-key-error) for more information about how to resolve this error.
- `REQUEST_DENIED` indicating that your request was denied, generally because:
- The request is missing an API key.
- The `key` parameter is invalid.
- `UNKNOWN_ERROR` indicating an unknown error.
When the Places service returns JSON results from a search, it places them
within a `predictions` array. Even if the service returns
no results (such as if the `location` is remote) it
still returns an empty `predictions` array. XML responses consist
of zero or more `` elements.
### PlaceAutocompletePrediction
| Field | Required | Type | Description |
|:---|---|---|---|
| #### `description` | **required** | string | Contains the human-readable name for the returned result. For `establishment` results, this is usually the business name. This content is meant to be read as-is. Don't programmatically parse the formatted address. |
| #### `matched_substrings` | **required** | Array\<[PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring "PlaceAutocompleteMatchedSubstring")\> | A list of substrings that describe the location of the entered term in the prediction result text, so that the term can be highlighted if chosen. See [PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring) for more information. |
| #### `structured_formatting` | **required** | [PlaceAutocompleteStructuredFormat](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteStructuredFormat "PlaceAutocompleteStructuredFormat") | Provides pre-formatted text that can be shown in your autocomplete results. This content is meant to be read as-is. Don't programmatically parse the formatted address. See [PlaceAutocompleteStructuredFormat](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteStructuredFormat) for more information. |
| #### `terms` | **required** | Array\<[PlaceAutocompleteTerm](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteTerm "PlaceAutocompleteTerm")\> | Contains an array of terms identifying each section of the returned description (a section of the description is generally terminated with a comma). Each entry in the array has a `value` field, containing the text of the term, and an `offset` field, defining the start position of this term in the description, measured in Unicode characters. See [PlaceAutocompleteTerm](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteTerm) for more information. |
| #### `distance_meters` | optional | integer | The straight-line distance in meters from the origin. This field is only returned for requests made with an `origin`. |
| #### `place_id` | optional | string | 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 IDs](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) overview. |
| #### `reference` | optional | string | > [!WARNING] > `reference` is deprecated. See place_id. |
| #### `types` | optional | Array\ | Contains an array of types that apply to this place. For example: `[ "political", "locality" ]` or `[ "establishment", "geocode", "beauty_salon" ]`. The array can contain multiple values. Learn more about [Place types](https://developers.google.com/maps/documentation/places/web-service/supported_types). |
### PlaceAutocompleteMatchedSubstring
| Field | Required | Type | Description |
|:---|---|---|---|
| #### `length` | **required** | number | Length of the matched substring in the prediction result text. |
| #### `offset` | **required** | number | Start location of the matched substring in the prediction result text. |
### PlaceAutocompleteStructuredFormat
| Field | Required | Type | Description |
|:---|---|---|---|
| #### `main_text` | **required** | string | Contains the main text of a prediction, usually the name of the place. |
| #### `main_text_matched_substrings` | **required** | Array\<[PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring "PlaceAutocompleteMatchedSubstring")\> | Contains an array with `offset` value and `length`. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if chosen. See [PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring) for more information. |
| #### `secondary_text` | optional | string | Contains the secondary text of a prediction, usually the location of the place. |
| #### `secondary_text_matched_substrings` | optional | Array\<[PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring "PlaceAutocompleteMatchedSubstring")\> | Contains an array with `offset` value and `length`. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if chosen. See [PlaceAutocompleteMatchedSubstring](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#PlaceAutocompleteMatchedSubstring) for more information. |
### PlaceAutocompleteTerm
| Field | Required | Type | Description |
|:---|---|---|---|
| #### `offset` | **required** | number | Defines the start position of this term in the description, measured in Unicode characters |
| #### `value` | **required** | string | The text of the term. |
## Place Autocomplete (Legacy) optimization
This section describes best practices to help you make the most of the
Place Autocomplete (Legacy) service.
Here are some general guidelines:
- The quickest way to develop a working user interface is to use the Maps JavaScript API [Place Autocomplete (Legacy) widget](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add-autocomplete), Places SDK for Android [Place Autocomplete (Legacy) widget](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete#add_an_autocomplete_widget), or Places SDK for iOS [Place Autocomplete (Legacy) UI control](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete#adding_an_autocomplete_ui_control).
- Understand essential Place Autocomplete (Legacy) [data fields](https://developers.google.com/maps/documentation/places/web-service/legacy/place-data-fields.md.txt) from the start.
- Location biasing and location restriction fields are optional but can have a significant impact on autocomplete performance.
- Use error handling to make sure your app degrades gracefully if the API returns an error.
- Make sure your app handles when there is no selection and offers users a way to continue.
### Cost optimization best practices
### Basic cost optimization
[Video](https://www.youtube.com/watch?v=VOP8cvCLGac)
To optimize the cost of using the Place Autocomplete (Legacy)
service, use field masks in Place Details (Legacy) and Place Autocomplete (Legacy) widgets to return only the
Place Autocomplete (Legacy) [data fields](https://developers.google.com/maps/documentation/places/web-service/legacy/place-data-fields.md.txt)
you need.
### Advanced cost optimization
Consider programmatic implementation of Place Autocomplete (Legacy) to access
[SKU: Autocomplete - Per Request pricing](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#places_autocomplete-per-request-legacy-ess-sku)
and request [Geocoding API results](https://developers.google.com/maps/documentation/geocoding/overview#results) about the selected place instead of Place Details (Legacy). Per-request pricing paired with Geocoding API is more cost-effective than per-session (session-based) pricing if both of the following conditions are met:
- If you only need the latitude and longitude or address of the user's selected place, the Geocoding API delivers this information for less than a Place Details (Legacy) call.
- If users select an autocomplete prediction within an average of four Place Autocomplete (Legacy) predictions requests or fewer, per-request pricing can be more cost-effective than per-session pricing.
To choose the Place Autocomplete (Legacy) implementation that costs the least for your application, find the row in the following table that matches what your application needs.
| What your application needs | Average Place Autocomplete (Legacy) requests before a user selects a prediction | Recommended implementation |
|---|---|---|
| Place details other than the address and location, such as the place name, business status, or opening hours | Any number | [Session-based Place Autocomplete (Legacy) with Place Details (Legacy)](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#select-place-details) |
| Only the address and latitude/longitude of the selected prediction | Four or fewer | [Per-request Place Autocomplete (Legacy) with the Geocoding API](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#select-location-performant) |
| Only the address and latitude/longitude of the selected prediction | More than four | [Session-based Place Autocomplete (Legacy) for address-only applications](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#select-location-nonperformant) |
Geocoding API could be a more cost-effective option than Place Details (Legacy) for your application, depending on the performance of your Place Autocomplete (Legacy) usage. Every application's Place Autocomplete (Legacy) efficiency varies depending on what users are entering, where the application is being used, and whether [performance optimization best practices](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#perf-best-practices) have been implemented.
To find the average number of requests for the table, analyze how many characters a user types on average before selecting a Place Autocomplete (Legacy) prediction in your application.
### Session-based Place Autocomplete (Legacy) with Place Details (Legacy)
**Use session-based Place Autocomplete (Legacy) with Place Details (Legacy).**
Since your application requires Place Details (Legacy), such as the place name, business status,
or opening hours, your implementation of Place Autocomplete (Legacy) should use a session token
([programmatically](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#sessiontoken) or built into the
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add-autocomplete),
[Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete#add_an_autocomplete_widget),
or [iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete#adding_an_autocomplete_ui_control)
widgets) [per session](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#about-autocomplete-sessions)
plus applicable [Places Data SKUs](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#data-skus),
depending on which place data fields you request.^[1](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#fn1)^
**Widget implementation**
Session management is automatically built into the
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add-autocomplete),
[Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete#add_an_autocomplete_widget),
or [iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete#adding_an_autocomplete_ui_control)
widgets. This includes both the Place Autocomplete (Legacy) requests and the Place Details (Legacy) request
on the selected prediction. Be sure to specify the `fields` parameter in order to
ensure you are only requesting the
Place Autocomplete (Legacy) [data fields](https://developers.google.com/maps/documentation/places/web-service/legacy/place-data-fields.md.txt)
you need.
**Programmatic implementation**
Use a
[session token](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#sessiontoken)
with your Place Autocomplete (Legacy) requests. When requesting Place Details (Legacy) about the selected prediction, include the following parameters:
1. The place ID from [the Place Autocomplete (Legacy) response](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#programmatic-response)
2. The session token used in the Place Autocomplete (Legacy) request
3. The `fields` parameter specifying the Place Autocomplete (Legacy) [data fields](https://developers.google.com/maps/documentation/places/web-service/legacy/place-data-fields.md.txt) you need
### Per-request Place Autocomplete (Legacy) with the Geocoding API
**Implement Place Autocomplete (Legacy) programmatically without session tokens and call Geocoding API on the selected place prediction.**
Geocoding API delivers addresses and latitude/longitude coordinates.
Making four
[Autocomplete - Per Request](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#places_autocomplete-per-request-legacy-ess-sku)
requests plus a [Geocoding API](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#geocoding-ess-sku)
call about the selected place prediction is less than the per-session Place Autocomplete (Legacy)
cost per session.^[1](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#fn1)^
Consider employing [performance best practices](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#perf-best-practices) to help your users get the prediction they're looking for in even fewer characters.
### Session-based Place Autocomplete (Legacy) for address-only applications
**Use session-based Place Autocomplete (Legacy) with Place Details (Legacy).**
Since the average number of requests you expect to make before a user selects a
Place Autocomplete (Legacy) prediction exceeds the cost of per-session pricing, your implementation
of Place Autocomplete (Legacy) should use a session token for both the Place Autocomplete (Legacy) requests
and the associated Place Details (Legacy) request
[per session](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#about-autocomplete-sessions).
^[1](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#fn1)^
**Widget implementation**
Session management is automatically built into the
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete#add-autocomplete),
[Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete#add_an_autocomplete_widget),
or [iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete#adding_an_autocomplete_ui_control)
widgets. This includes both the Place Autocomplete (Legacy) requests and the Place Details (Legacy)
request on the selected prediction. Be sure to specify the `fields` parameter
in order to ensure you are only requesting the fields you need.
**Programmatic implementation**
Use a
[session token](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#sessiontoken)
with your Place Autocomplete (Legacy) requests.
When requesting Place Details (Legacy) about the selected prediction,
include the following parameters:
1. The place ID from [the Place Autocomplete (Legacy) response](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#programmatic-response)
2. The session token used in the Place Autocomplete (Legacy) request
3. The `fields` parameter specifying [Basic Data](https://developers.google.com/maps/billing-and-pricing/sku-details/legacy.md.txt#data-skus) fields such as address and geometry
**Consider delaying Place Autocomplete (Legacy) requests**
You can employ strategies such as delaying a Place Autocomplete (Legacy) request until the user has typed in the first three or four characters so that your application makes fewer requests. For example, making Place Autocomplete (Legacy) requests for each character *after* the user has typed the third character means that if the user types seven characters then selects a prediction for which you make one Geocoding API request, the total cost would be for 4 Place Autocomplete (Legacy) Per Request + Geocoding.^[1](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#fn1)^
If delaying requests can get your average programmatic request below four, you can follow the guidance for [performant Place Autocomplete (Legacy) with Geocoding API](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#select-location-performant) implementation. Note that delaying requests can be perceived as latency by the user who might be expecting to see predictions with every new keystroke.
Consider employing [performance best practices](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#perf-best-practices) to help your users get the prediction they're looking for in fewer characters.
*** ** * ** ***
1. For costs, see [Google Maps Platform pricing lists](https://developers.google.com/maps/billing-and-pricing/pricing.md.txt).
### Performance best practices
[Video](https://www.youtube.com/watch?v=bv1p4s_d8OM)
The following guidelines describe ways to optimize Place Autocomplete (Legacy) performance:
- Add country restrictions, [location biasing](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#location_biasing), and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
- If Place Autocomplete (Legacy) is accompanied by a map, you can bias location by map viewport.
- In situations when a user does not choose one of the Place Autocomplete (Legacy) predictions, generally because none of those predictions are the result-address wanted, you can reuse the original user input to attempt to get more relevant results:
- If you expect the user to enter only address information, reuse the original user input in a call to the [Geocoding API](https://developers.google.com/maps/documentation/geocoding/overview).
- If you expect the user to enter queries for a specific place by name or address, use a Place Details (Legacy) request. If results are only expected in a specific region, use [location biasing](https://developers.google.com/maps/documentation/places/web-service/legacy/autocomplete.md.txt#location_biasing).
Other scenarios when it's best to fall back to the Geocoding API include:
- Users inputting subpremise addresses, such as addresses for specific units or apartments within a building. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete (Legacy).
- Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.
### Location biasing
Bias results to a specified area by passing a `location` parameter and a `radius`
parameter. This instructs Place Autocomplete (Legacy) to *prefer* showing results
within the defined area. Results outside of the defined area may still be
displayed. You can use the `includedRegionCodes` parameter to filter results
to show only those places within a specified country.
> [!WARNING]
> **Warning:** If `radius` is not provided, the `location` parameter is ignored.
> [!TIP]
> Establishment results generally don't rank highly enough to show in results when the search area is large. If you want establishments to appear in mixed establishment/geocode results, you can specify a smaller radius. Alternatively, use `types=establishment` to restrict results to establishments only.
### Location restricting
Restrict results to a specified area by passing a `locationRestriction` parameter.
You may also restrict results to the region defined by `location`
and a `radius` parameter, by adding the
`strictbounds`
parameter. This instructs Place Autocomplete (Legacy) to return *only*
results within that region.
> [!NOTE]
> **Note:** Location restrictions are only applied to entire routes. Synthetic results located outside the location restriction may be returned based on a route that overlaps with the location restriction.