AI-generated Key Takeaways

outlined_flag

• The Autocomplete (New) service offers place and query predictions based on user input, using parameters like location and place type to refine results.

• Predictions can be customized by region, place type, and search area, using parameters likeincludedRegionCodes,includedPrimaryTypes, andlocationRestriction orlocationBias.

• The response includes asuggestions array containingplacePrediction objects with place details andqueryPrediction objects with alternative search terms if enabled.

• It's essential to use eitherlocationBias orlocationRestriction, but not both, for influencing the search area, and to remember thatqueryPrediction is not returned withincludedRegionCodes.

• The API adheres to usage guidelines, requiring the display of the Google logo when predictions are shown without a map, and Google Maps when displaying them on a map, in addition to limiting the number of predictions returned.

Introduction

Autocomplete (New) is a web service that returns placepredictions and query predictions in response to an HTTP request. In the request, specify a textsearch string and geographic bounds that controls the search area.

Autocomplete (New) can match on full words andsubstrings of the input, resolving place names, addresses, andplus codes. Applications can therefore sendqueries as the user types, to provide on-the-fly place and query predictions.

The response from Autocomplete (New) can contain two typesof predictions:

• Place predictions: Places, such as businesses, addresses and points of interest, based on the specified input text string and search area. Place predictions are returned by default.
• Query predictions: Query strings matching the input text string and search area. Query predictions are not returned by default. Use theincludeQueryPredictions request parameter to add query predictions to the response.

For example, you call Autocomplete (New) using as input a stringthat contains a partial user input, "Sicilian piz", with the search arealimited to San Francisco, CA. The response then contains a list ofplace predictions that match the search string and searcharea, such as the restaurant named "Sicilian Pizza Kitchen", along withdetails about the place.

The returnedplace predictions are designed to be presented to the user to aidthem in selecting the intended place. You can make aPlace Details (New)request to get more information about any of the returned place predictions.

The response can also contain a list ofquery predictions that match thesearch string and search area, such as "Sicilian Pizza & Pasta". Each query prediction in theresponse includes thetext field containing a recommended text search string. Use thatstring as an input toText Search (New)to perform a more detailed search.

The APIs Explorer lets you make live requests so that you can get familiar withthe API and the API options:

Autocomplete (New) requests

An Autocomplete (New) request is an HTTP POST request to a URL inthe form:

https://places.googleapis.com/v1/places:autocomplete

Pass all parameters in the JSON request body or in headers as part of the POST request.For example:

curl -X POST -d '{  "input": "pizza",  "locationBias": {    "circle": {      "center": {        "latitude": 37.7937,        "longitude": -122.3965      },      "radius": 500.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

Supported parameters

About the response

Autocomplete (New) returns a JSON object as a response.In the response:

• Thesuggestions array contains all of the predicted places and queries in order based on their perceived relevance. Each place is represented by aplacePrediction field and each query is represented by aqueryPrediction field.
• AplacePrediction field contains detailed information about a single place prediction, including the place ID, and text description.
• AqueryPrediction field contains detailed information about a single query prediction.

{"suggestions": [    {"placePrediction": {        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",        "text": {          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",          "matches": [            {              "endOffset": 6            }]        },      ...    },    {"queryPrediction": {        "text": {          "text": "Amoeba Music",          "matches": [            {              "endOffset": 6            }]        },        ...    }  ...]}

• input

  The text string on which to search. Specify full words and substrings, place names, addresses, andplus codes. The Autocomplete (New) service returns candidate matches based on this string and orders results based on their perceived relevance.

Optional parameters

• FieldMask

  Specify the list of fields to return in the response by creating aresponse field mask. Pass the response field mask to the method by using the HTTP headerX-Goog-FieldMask.

  Specify a comma-separated list of suggestion fields to return. For example, to retrieve thesuggestions.placePrediction.text.text andsuggestions.queryPrediction.text.text of the suggestion.

  X-Goog-FieldMask:suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  Note:Spaces are not allowed anywhere in the field list.

  Use* to retrieve all fields.

  X-Goog-FieldMask:*

• includedPrimaryTypes

  A place can only have asingle primary type from types listed inTable A orTable B. For example, the primary type might be"mexican_restaurant" or"steak_house".

  By default, the API returns all places based on theinput parameter, regardless of the primary type value associated with the place. Restrict results to be of a certain primary type or primary types by passing theincludedPrimaryTypes parameter.

  Use this parameter to specify up to five type values fromTable A orTable B. A place must match one of the specified primary type values to be included in the response.

  This parameter may also include, instead, one of(regions) or(cities). The(regions) type collection filters for areas or divisions, such as neighborhoods and postal codes. The(cities) type collection filters for places that Google identifies as a city.

  The request is rejected with anINVALID_REQUEST error if:

  • More than five types are specified.
  • Any type is specified in addition to(cities) or(regions).
  • Any unrecognized types are specified.
  Note: TheincludedPrimaryTypes 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 inTable A orTable B.

• includePureServiceAreaBusinesses

  If set totrue, the response includes businesses that visit or deliver to customers directly, but don't have a physical business location. If set tofalse, the API returns only businesses with a physical business location.

• includeQueryPredictions

  Iftrue, the response includes both place and query predictions. The default value isfalse, meaning the response only includes place predictions.

• includedRegionCodes

  Only include results from the list of specified regions, specified as an array of up to 15ccTLD ("top-level domain") two-character values. If omitted, no restrictions are applied to the response. For example, to limit the regions to Germany and France:

  "includedRegionCodes":["de","fr"]

  If you specify bothlocationRestriction andincludedRegionCodes, the results are located in the area of intersection of the two settings.

  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 atWikipedia: List of ISO 3166 country codes or theISO Online Browsing Platform.

• inputOffset

  The zero-based Unicode character offset indicating the cursor position ininput. The cursor position can influence what predictions are returned. If empty, it defaults to the length ofinput.

  Note:In the initial Restricted Preview release, this property was calledpredictionTermOffset.

• languageCode

  The preferred language in which to return results. The results might be in mixed languages if the language used ininput is different from the value specified bylanguageCode, or if the returned place does not have a translation from the local language tolanguageCode.

  • You must useIETF BCP-47 language codes to specify the preferred language.
  • IflanguageCode is not supplied, the API uses the value specified in theAccept-Language header. If neither is specified, the default isen. If you specify an invalid language code, the API returns anINVALID_ARGUMENT error.
  • 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. This also affects the API's ability to correct spelling errors.
  • The API attempts to provide a street address that is readable for both the user and local population, while at the same time reflecting the user input. Place predictions are formatted differently depending on the user input in each request.
    • Matching terms in theinput parameter are chosen first, using names aligned with the language preference indicated by thelanguageCode parameter when available, while otherwise using names that best match the user input.
    • Street addresses are formatted in the local language, in a script readable by the user when possible, only after matching terms have been picked to match the terms in theinput parameter.
    • All other addresses are returned in the preferred language, after matching terms have been chosen to match the terms in theinput parameter. If a name is not available in the preferred language, the API uses the closest match.

• locationBias or locationRestriction

  You can specifylocationBias orlocationRestriction, but not both, to define the search area. Think oflocationRestriction as specifying the region which the results must be within, andlocationBias as specifying the region that the results must be near but can be outside of the area.

  Note:If you omit bothlocationBias andlocationRestriction, Autocomplete (New) uses IP biasing by default. With IP biasing, Autocomplete (New) uses the IP address of the device to bias the results.

  • locationBias

    Specifies an area to search. This location serves as a bias which means results around the specified location can be returned, including results outside the specified area.

  • locationRestriction

    Specifies an area to search. Results outside the specified area are not returned.

  Specify thelocationBias orlocationRestriction region as arectangular Viewport or as acircle.

  • A circle is defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. The default value is 0.0. ForlocationRestriction, you must set the radius to a value greater than 0.0. Otherwise, the request returns no results.

    For example:

    "locationBias":{"circle":{"center":{"latitude":37.7937,"longitude":-122.3965},"radius":500.0}}

  • A rectangle is a latitude-longitude viewport, represented as two diagonally oppositelow and high points. A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:

    • Iflow =high, the viewport consists of that single point.
    • Iflow.longitude >high.longitude, the longitude range is inverted (the viewport crosses the 180 degree longitude line).
    • Iflow.longitude = -180 degrees andhigh.longitude = 180 degrees, the viewport includes all longitudes.
    • Iflow.longitude = 180 degrees andhigh.longitude = -180 degrees, the longitude range is empty.

    Bothlow andhigh must be populated, and the represented box cannot be empty. An empty viewport results in an error.

    For example, this viewport fully encloses New York City:

    "locationBias":{"rectangle":{"low":{"latitude":40.477398,"longitude":-74.259087},"high":{"latitude":40.91618,"longitude":-73.70018}}}

• origin

  The origin point from which to calculate straight-line distance to the destination (returned asdistanceMeters). If this value is omitted, straight-line distance will not be returned. Must be specified as latitude and longitude coordinates:

  "origin":{"latitude":40.477398,"longitude":-74.259087}

• regionCode

  The region code used to format the response, specified as accTLD ("top-level domain") 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").

  Suggestions are also biased based on region codes. Google recommends setting theregionCode according to the user's regional preference.

  If you specify an invalid region code, the API returns anINVALID_ARGUMENT error. The parameter can affect results based on applicable law.

• sessionToken

  Session tokens are user-generated strings that track Autocomplete (New) calls as "sessions." Autocomplete (New) uses session tokens to group the query and selection phases of a user autocomplete search into a discrete session for billing purposes. For more information, seeSession tokens.

Choose parameters to bias results

Autocomplete (New) examples

Restrict search to an area using locationRestriction

curl -X POST -d '{  "input": "Art museum","locationRestriction": {    "circle": {      "center": {        "latitude": 37.7749,        "longitude": -122.4194      },      "radius": 5000.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

{"suggestions":[{"placePrediction":{"place":"places/ChIJkQQVTZqAhYARHxPt2iJkm1Q","placeId":"ChIJkQQVTZqAhYARHxPt2iJkm1Q","text":{"text":"Asian Art Museum, Larkin Street, San Francisco, CA, USA","matches":[{"startOffset":6,"endOffset":16}]},"structuredFormat":{"mainText":{"text":"Asian Art Museum","matches":[{"startOffset":6,"endOffset":16}]},"secondaryText":{"text":"Larkin Street, San Francisco, CA, USA"}},"types":["establishment","museum","point_of_interest"]}},{"placePrediction":{"place":"places/ChIJI7NivpmAhYARSuRPlbbn_2w","placeId":"ChIJI7NivpmAhYARSuRPlbbn_2w","text":{"text":"de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA","matches":[{"endOffset":15}]},"structuredFormat":{"mainText":{"text":"de Young Museum","matches":[{"endOffset":15}]},"secondaryText":{"text":"Hagiwara Tea Garden Drive, San Francisco, CA, USA"}},"types":["establishment","point_of_interest","tourist_attraction","museum"]}},/.../]}

  curl -X POST -d '{    "input": "Art museum","locationRestriction": {      "rectangle": {        "low": {          "latitude": 37.7751,          "longitude": -122.4219        },        "high": {          "latitude": 37.7955,          "longitude": -122.3937        }      }    }  }' \  -H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \  https://places.googleapis.com/v1/places:autocomplete

{"suggestions":[{"placePrediction":{"place":"places/ChIJkQQVTZqAhYARHxPt2iJkm1Q","placeId":"ChIJkQQVTZqAhYARHxPt2iJkm1Q","text":{"text":"Asian Art Museum, Larkin Street, San Francisco, CA, USA","matches":[{"startOffset":6,"endOffset":16}]},"structuredFormat":{"mainText":{"text":"Asian Art Museum","matches":[{"startOffset":6,"endOffset":16}]},"secondaryText":{"text":"Larkin Street, San Francisco, CA, USA"}},"types":["point_of_interest","museum","establishment"]}},{"placePrediction":{"place":"places/ChIJyQNK-4SAhYARO2DZaJleWRc","placeId":"ChIJyQNK-4SAhYARO2DZaJleWRc","text":{"text":"International Art Museum of America, Market Street, San Francisco, CA, USA","matches":[{"startOffset":14,"endOffset":24}]},"structuredFormat":{"mainText":{"text":"International Art Museum of America","matches":[{"startOffset":14,"endOffset":24}]},"secondaryText":{"text":"Market Street, San Francisco, CA, USA"}},"types":["museum","point_of_interest","tourist_attraction","art_gallery","establishment"]}}]}

curl -X POST -d '{  "input": "Amoeba","locationBias": {    "circle": {      "center": {        "latitude": 37.7749,        "longitude": -122.4194      },      "radius": 5000.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

{"suggestions":[{"placePrediction":{"place":"places/ChIJ5YQQf1GHhYARPKG7WLIaOko","placeId":"ChIJ5YQQf1GHhYARPKG7WLIaOko","text":{"text":"Amoeba Music, Haight Street, San Francisco, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Haight Street, San Francisco, CA, USA"}},"types":["electronics_store","point_of_interest","store","establishment","home_goods_store"]}},{"placePrediction":{"place":"places/ChIJr7uwwy58hYARBY-e7-QVwqw","placeId":"ChIJr7uwwy58hYARBY-e7-QVwqw","text":{"text":"Amoeba Music, Telegraph Avenue, Berkeley, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Telegraph Avenue, Berkeley, CA, USA"}},"types":["electronics_store","point_of_interest","establishment","home_goods_store","store"]}},...]}

  curl -X POST -d '{    "input": "Amoeba","locationBias": {      "rectangle": {        "low": {          "latitude": 37.7751,          "longitude": -122.4219        },        "high": {          "latitude": 37.7955,          "longitude": -122.3937        }      }    }  }' \  -H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \  https://places.googleapis.com/v1/places:autocomplete

{"suggestions":[{"placePrediction":{"place":"places/ChIJ5YQQf1GHhYARPKG7WLIaOko","placeId":"ChIJ5YQQf1GHhYARPKG7WLIaOko","text":{"text":"Amoeba Music, Haight Street, San Francisco, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Haight Street, San Francisco, CA, USA"}},"types":["point_of_interest","store","establishment"]}},{"placePrediction":{"place":"places/ChIJr7uwwy58hYARBY-e7-QVwqw","placeId":"ChIJr7uwwy58hYARBY-e7-QVwqw","text":{"text":"Amoeba Music, Telegraph Avenue, Berkeley, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Telegraph Avenue, Berkeley, CA, USA"}},"types":["point_of_interest","store","establishment"]}},{"placePrediction":{"place":"places/ChIJRdmfADq_woARYaVhnfQSUTI","placeId":"ChIJRdmfADq_woARYaVhnfQSUTI","text":{"text":"Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Hollywood Boulevard, Los Angeles, CA, USA"}},"types":["point_of_interest","store","establishment"]}},/.../]}

Use theincludedPrimaryTypes parameter to specify up to five type values fromTable A,Table B, or only(regions), or only(cities). A place must match one of the specified primary type values to be included in the response.

In the following example, you specify aninput string of"Soccer" and use theincludedPrimaryTypes parameter to restrict results toestablishments of type"sporting_goods_store":

curl -X POST -d '{  "input": "Soccer","includedPrimaryTypes": ["sporting_goods_store"],  "locationBias": {    "circle": {      "center": {        "latitude": 37.7749,        "longitude": -122.4194      },      "radius": 500.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

If you omit theincludedPrimaryTypes parameter, then the results can includeestablishments of a type that you do not want, such as"athletic_field".

Request query predictions

Query predictions are not returned by default. Use theincludeQueryPredictionsrequest parameter to add query predictions to the response. For example:

curl -X POST -d '{  "input": "Amoeba","includeQueryPredictions": true,  "locationBias": {    "circle": {      "center": {        "latitude": 37.7749,        "longitude": -122.4194      },      "radius": 5000.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

Thesuggestions array now contains both place predictions and query predictionsas shown above inAbout the response. Each query predictionincludes thetext field containing a recommended text search string. You can make aText Search (New)request to get more information about any of the returned query predictions.

curl -X POST -d '{  "input": "Amoeba","origin": {    "latitude": 37.7749,    "longitude": -122.4194  },  "locationRestriction": {    "circle": {      "center": {        "latitude": 37.7749,        "longitude": -122.4194      },      "radius": 5000.0    }  }}' \-H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \https://places.googleapis.com/v1/places:autocomplete

{"suggestions":[{"placePrediction":{"place":"places/ChIJ5YQQf1GHhYARPKG7WLIaOko","placeId":"ChIJ5YQQf1GHhYARPKG7WLIaOko","text":{"text":"Amoeba Music, Haight Street, San Francisco, CA, USA","matches":[{"endOffset":6}]},"structuredFormat":{"mainText":{"text":"Amoeba Music","matches":[{"endOffset":6}]},"secondaryText":{"text":"Haight Street, San Francisco, CA, USA"}},"types":["home_goods_store","establishment","point_of_interest","store","electronics_store"],"distanceMeters":3012}}]}