A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://developers.google.com/maps/documentation/places/web-service/place-autocomplete below:

Autocomplete (New) | Places API

Skip to main content Autocomplete (New)

Stay organized with collections Save and categorize content based on your preferences.

Introduction

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

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

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

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

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

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

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

Autocomplete (New) requests

An Autocomplete (New) request is an HTTP POST request to a URL in the 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

Parameter

Description

input*

Text string to search on (full words, substrings, place names, addresses, plus codes).

FieldMask (HTTP Header)

Comma-separated list specifying which fields to return in the response.

includedPrimaryTypes

Restricts results to places matching one of up to five specified primary types.

includePureServiceAreaBusinesses

If true, includes businesses without a physical location (service area businesses). Defaults to false.

includeQueryPredictions

If true, includes both place and query predictions in the response. Defaults to false.

includedRegionCodes

Array of up to 15 two-character country codes to restrict results to.

inputOffset

Zero-based Unicode char offset of cursor position within input string, influencing predictions. Defaults to input length.

languageCode

Preferred language (IETF BCP-47 code) for results. Defaults to Accept-Language header or 'en'.

locationBias

Specifies an area (circle or rectangle) to bias search results towards, allowing results outside the area. Cannot be used with locationRestriction.

locationRestriction

Specifies an area (circle or rectangle) to restrict search results within. Results outside this area are excluded. Cannot be used with locationBias.

origin

Origin point (lat, long) used to calculate straight-line distance (distanceMeters) to predicted destinations.

regionCode

Region code used to format the response and bias suggestions (e.g., 'uk', 'fr').

sessionToken

User-generated string to group Autocomplete calls into a session for billing purposes.

* Denotes required field.

About the response

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

Note: Autocomplete (New) returns five total predictions, either as placePredictions, queryPredictions, or a combination, depending on the request. If the request does not set includeQueryPredictions, the response includes up to five placePredictions. If the request sets includeQueryPredictions, the response includes up to five predictions in a combination of placePredictions and queryPredictions.

The complete JSON object is in the form:

{
  "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
            }]
        },
        ...
    }
  ...]
}
Required parameters Optional parameters Choose parameters to bias results

Autocomplete (New) parameters can influence search results differently. The following table provides recommendations for parameter usage based on the intended outcome.

Parameter Usage recommendation regionCode Set according to user's regional preference. includedRegionCodes Set to limit results to the list of specified regions. locationBias Use when results are preferred in or around a region. If applicable, define the region as the viewport of the map the user is looking at. locationRestriction Use only when results outside of a region shouldn't be returned. origin Use when a straight-line distance to each prediction is intended.
Note: The distance won't be available for every prediction. See Distance missing from response. Autocomplete (New) examples Restrict search to an area using locationRestriction Note: Autocomplete (New) uses IP biasing by default to control the search area. With IP biasing, Autocomplete (New) uses the IP address of the device to bias the results. You can optionally use locationRestriction or locationBias, but not both, to specify an area to search.

locationRestriction specifies the area to search. Results outside the specified area are not returned. In the following example, you use locationRestriction to limit the request to a circle 5000 meters in radius centered on San Francisco:

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

All results from within the specified areas are contained in the suggestions array:

  {
    "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"
          ]
        }
      },
      /.../
    ]
  }

You can also use locationRestriction to restrict searches to a rectangular Viewport. The following example limits the request to downtown San Francisco:

  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

Results are contained in the suggestions array:

  {
    "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"
          ]
        }
      }
    ]
  }
Bias search to an area using locationBias

With locationBias, the location serves as a bias which means results around the specified location can be returned, including results outside the specified area. In the following example, you bias the request to downtown San Francisco:

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

The results now contain many more items, including results outside of the 5000 meter radius:

{
  "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"
        ]
      }
    },
    ...
  ]
}

You can also use locationBias to restrict searches to a rectangular Viewport. The following example limits the request to downtown San Francisco:

  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

Although search results within the rectangular viewport appear in the response, some results are outside of the defined boundaries, due to biasing. Results are also contained within the suggestions array:

  {
    "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 includedPrimaryTypes

Use the includedPrimaryTypes parameter to specify up to five type values from Table 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 an input string of "Soccer" and use the includedPrimaryTypes parameter to restrict results to establishments 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 the includedPrimaryTypes parameter, then the results can include establishments of a type that you do not want, such as "athletic_field".

Request query predictions

Query predictions are not returned by default. Use the includeQueryPredictions request 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

The suggestions array now contains both place predictions and query predictions as shown above in About the response. Each query prediction includes the text field containing a recommended text search string. You can make a Text Search (New) request to get more information about any of the returned query predictions.

Note: Query predictions are not returned when the includedRegionCodes parameter is set. Use origin

In this example, include origin in the request as latitude and longitude coordinates. When you include origin, Autocomplete (New) includes the distanceMeters field in the response which contains the straight-line distance from the origin to the destination. This example sets the origin to the center of San Francisco:

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

The response now includes distanceMeters:

{
  "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
      }
    }
  ]
}
Distance missing from response

In certain cases, distanceMeters is missing from the response body, even when origin is included in the request. This may happen in the following scenarios:

Client libraries attempting to read the distanceMeters field out of a parsed object will return a field with value 0. To avoid misleading users, don't display a zero distance to users.

Try it!

The APIs Explorer lets you make sample requests so that you can get familiar with the API and the API options.

  1. Select the API icon api on the right side of the page.

  2. Optionally edit the request parameters.

  3. Select the Execute button. In the dialog, choose the account that you want to use to make the request.

  4. In the APIs Explorer panel, select the fullscreen icon fullscreen to expand the APIs Explorer window.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-08-14 UTC.

[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-14 UTC."],[[["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 like `includedRegionCodes`, `includedPrimaryTypes`, and `locationRestriction` or `locationBias`."],["The response includes a `suggestions` array containing `placePrediction` objects with place details and `queryPrediction` objects with alternative search terms if enabled."],["It's essential to use either `locationBias` or `locationRestriction`, but not both, for influencing the search area, and to remember that `queryPrediction` is not returned with `includedRegionCodes`."],["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."]]],["The Autocomplete (New) service predicts places and query strings based on user input within a defined search area. It supports real-time, \"as-you-type\" suggestions via a POST request to `places.googleapis.com/v1/places:autocomplete`. Place predictions are default; query predictions are optional. The API accepts text input, offers geographic biasing/restriction using location parameters and filters by language or place type. Results are returned in a JSON response and are ordered by relevance in a `suggestions` array, containing a maximum of five predictions.\n"]]

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4