Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share your input on your UI Kit experience.

Place Autocomplete Widget

Page Summary

The Place Autocomplete Widget enables adding a text input field to your web page or map, providing place predictions and details upon user selection.
Key improvements include enhanced localization, accessibility, mobile support, performance, and a simplified Place class for object handling.
Implementation involves enabling the Places API, creating a PlaceAutocompleteElement, and appending it to the page or map.
Developers can constrain predictions using componentRestrictions, locationRestrictions, locationBias, and types for refined searches.
Place details are retrieved using the gmp-placeselect listener and place.fetchFields() for displaying or updating the map.

European Economic Area (EEA) developers

The Place Autocomplete Widget creates a text input field, supplies place predictions in a UI pick list, and returns place details in response to the user's selection. Use the Place Autocomplete Widget to embed a complete self-contained autocomplete user interface on your web page.

Prerequisites

To use Place Autocomplete, you must enable "Places API (new)" on your Google Cloud project. See Get started for details.

What's new

Place Autocomplete has been improved in the following ways:

The Autocomplete widget UI supports regional localization (including RTL languages), for the text input placeholder, predictions list logo, and the place predictions.
Enhanced accessibility, including support for screen readers and keyboard interaction.
The Autocomplete widget returns the new Place class to simplify handling of the returned object.
Better support for mobile devices and small screens.
Better performance and improved graphical appearance.

The Autocomplete widget creates a text input field, supplies place predictions in a UI pick list, and returns place details in response to a user click using the gmp-select listener. This section shows you how to add an autocomplete widget to a web page, or a Google map.

To add the Autocomplete widget to a web page, create a new google.maps.places.PlaceAutocompleteElement, and append it to the page as shown in the following example:

TypeScript

// Request needed libraries.
(await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(
    {}
);
document.body.appendChild(placeAutocomplete);index.ts

JavaScript

// Request needed libraries.
(await google.maps.importLibrary('places'));
// Create the input HTML element, and append it.
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement({});
document.body.appendChild(placeAutocomplete);index.js

See the complete code example

If your billing address is outside of the European Economic Area (EEA), you may also use the Autocomplete widget with a Google Map.

To add an Autocomplete widget to a map, create a new google.maps.places.PlaceAutocompleteElement instance, append the PlaceAutocompleteElement to a div, and push it onto the map as a custom control, as shown in the following example:

TypeScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});index.ts

JavaScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});
// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});index.js

See the complete code example

Constrain Autocomplete predictions

By default, Place Autocomplete presents all place types, biased for predictions near the user's location, and fetches all available data fields for the user's selected place. Set PlaceAutocompleteElementOptions to present more relevant predictions, by restricting or biasing results.

Restricting results causes the Autocomplete widget to ignore any results that are outside of the restriction area. A common practice is to restrict results to the map bounds. Biasing results makes the Autocomplete widget show results within the specified area, but some matches may be outside of that area.

If you don't supply any bounds or a map viewport, the API will attempt to detect the user's location from their IP address, and will bias the results to that location. Set a bounds whenever possible. Otherwise, different users may receive different predictions. Also, to generally improve predictions it is important to provide a sensible viewport such as one that you set by panning or zooming on the map, or a developer-set viewport based on device location and radius. When a radius is not available, 5 km is considered a sensible default for Place Autocomplete. Don't set a viewport with zero radius (a single point), a viewport that is only a few meters across (less than 100 m.), or a viewport that spans the globe.

Restrict place search by country

To restrict place search to one or more specific countries, use the includedRegionCodes property to specify the country code(s) as shown in the following snippet:

const pac = new google.maps.places.PlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

Restrict place search to map bounds

To restrict place search to a map's bounds, use the locationRestrictions property to add the bounds, as shown in the following snippet:

const pac = new google.maps.places.PlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

When restricting to map bounds, be sure to add a listener to update the bounds when they change:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

To remove the locationRestriction, set it to null.

Bias place search results

Bias place search results to a circle area by using the locationBias property, and passing a radius, as shown here:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

To remove the locationBias, set it to null.

Restrict place search results to certain types

Restrict place search results to certain types of places by using the includedPrimaryTypes property, and specifying one or more types, as shown here:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

For a complete list of supported types, see Place type tables A and B.

Get place details

To get place details for the selected place, add a gmp-select listener to the PlaceAutocompleteElement, as shown in the following example:

TypeScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(
        place.toJSON(), /* replacer */ null, /* space */ 2);
});index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2);
});index.js

See the complete code example

In the preceding example, the event listener returns an object of Place class. Call place.fetchFields() to get the Place Details data fields needed for your application.

The listener in the next example requests place information and displays it on a map.

TypeScript

// Add the gmp-placeselect listener, and display the results on the map.
  //prettier-ignore
  //@ts-ignore
  placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
      fields: ['displayName', 'formattedAddress', 'location'],
    });

    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      innerMap.fitBounds(place.viewport);
    } else {
      innerMap.setCenter(place.location);
      innerMap.setZoom(17);
    }

    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  }
);index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results on the map.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
        innerMap.fitBounds(place.viewport);
    }
    else {
        innerMap.setCenter(place.location);
        innerMap.setZoom(17);
    }
    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);
    updateInfoWindow(content, place.location);
    marker.position = place.location;
});index.js

See the complete code example

Example maps

This section contains the complete code for the example maps featured on this page.

Autocomplete element

This example adds an Autocomplete widget to a web page, and displays the results for each selected place.

TypeScript

async function initMap(): Promise<void> {
    // Request needed libraries.
    (await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(
        {}
    );
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}

initMap();index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('places'));
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement({});
    document.body.appendChild(placeAutocomplete);
    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);
    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);
    // Add the gmp-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}
initMap();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>

        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </body>
</html>index.html

Try Sample

JSFiddle.net

Autocomplete map

This example shows you how to add an Autocomplete widget to a Google map.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
const placeAutocomplete = document.querySelector(
    'gmp-place-autocomplete'
) as google.maps.places.PlaceAutocompleteElement;
let innerMap;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap(): Promise<void> {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new google.maps.InfoWindow({});

    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
      const place = placePrediction.toPlace();
      await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
      });

      // If the place has a geometry, then present it on a map.
      if (place.viewport) {
        innerMap.fitBounds(place.viewport);
      } else {
        innerMap.setCenter(place.location);
        innerMap.setZoom(17);
      }

      let content = document.createElement('div');
      let nameText = document.createElement('span');
      nameText.textContent = place.displayName;
      content.appendChild(nameText);
      content.appendChild(document.createElement('br'));
      let addressText = document.createElement('span');
      addressText.textContent = place.formattedAddress;
      content.appendChild(addressText);

      updateInfoWindow(content, place.location);
      marker.position = place.location;
    }
  );
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

initMap();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('places'),
    ]);
    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Use the bounds_changed event to restrict results to the current map bounds.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });
    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });
    infoWindow = new google.maps.InfoWindow({});
    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        }
        else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }
        let content = document.createElement('div');
        let nameText = document.createElement('span');
        nameText.textContent = place.displayName;
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        let addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress;
        content.appendChild(addressText);
        updateInfoWindow(content, place.location);
        marker.position = place.location;
    });
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}
initMap();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

.place-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: large;
    font-weight: bold;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <p>Search for a place here:</p>
                <gmp-place-autocomplete></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>index.html

Try Sample

JSFiddle.net

Autocomplete (New) optimization

This section describes best practices to help you make the most of the Autocomplete (New) service.

Here are some general guidelines:

The quickest way to develop a working user interface is to use the Maps JavaScript API Autocomplete (New) widget, Places SDK for Android Autocomplete (New) widget, or Places SDK for iOS Autocomplete (New) widget.
Understand essential Autocomplete (New) data fields 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

To optimize the cost of using the Autocomplete (New) service, use field masks in Place Details (New) and Autocomplete (New) widgets to return only the Autocomplete (New) data fields you need.

Advanced cost optimization

Consider programmatic implementation of Autocomplete (New) in order to access SKU: Autocomplete Request pricing and request Geocoding API results about the selected place instead of Place Details (New). 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/longitude or address of the user's selected place, the Geocoding API delivers this information for less than a Place Details (New) call.
If users select an autocomplete prediction within an average of four Autocomplete (New) predictions requests or fewer, per-request pricing may be more cost-effective than per-session pricing.

For help selecting the Autocomplete (New) implementation that fits your needs, select the tab that corresponds to your answer to the following question.

Does your application require any information other than the address and latitude/longitude of the selected prediction?

Yes, needs more details

Use session-based Autocomplete (New) with Place Details (New).
Since your application requires Place Details (New), such as the place name, business status, or opening hours, your implementation of Autocomplete (New) should use a session token (programmatically or built into the JavaScript, Android, or iOS widgets) per session plus applicable Places SKUs, depending on which place data fields you request.¹

Widget implementation
Session management is automatically built into the JavaScript, Android, or iOS widgets. This includes both the Autocomplete (New) requests and the Place Details (New) request on the selected prediction. Be sure to specify the fields parameter in order to ensure you are only requesting the Autocomplete (New) data fields you need.

Programmatic implementation
Use a session token with your Autocomplete (New) requests. When requesting Place Details (New) about the selected prediction, include the following parameters:

The place ID from the Autocomplete (New) response
The session token used in the Autocomplete (New) request
The fields parameter specifying the Autocomplete (New) data fields you need

No, needs only address and location

Geocoding API could be a more cost-effective option than Place Details (New) for your application, depending on the performance of your Autocomplete (New) usage. Every application's Autocomplete (New) efficiency varies depending on what users are entering, where the application is being used, and whether performance optimization best practices have been implemented.

In order to answer the following question, analyze how many characters a user types on average before selecting a Autocomplete (New) prediction in your application.

Do your users select a Autocomplete (New) prediction in four or fewer requests, on average?

Yes

Implement Autocomplete (New) programmatically without session tokens and call Geocoding API on the selected place prediction.
Geocoding API delivers addresses and latitude/longitude coordinates. Making four Autocomplete Requests requests plus a Geocoding API call about the selected place prediction is less than the per-session Autocomplete (New) cost per session.¹

Consider employing performance best practices to help your users get the prediction they're looking for in even fewer characters.

No

Use session-based Autocomplete (New) with Place Details (New).
Since the average number of requests you expect to make before a user selects a Autocomplete (New) prediction exceeds the cost of per-session pricing, your implementation of Autocomplete (New) should use a session token for both the Autocomplete (New) requests and the associated Place Details (New) request per session. ¹

Programmatic implementation
Use a session token with your Autocomplete (New) requests. When requesting Place Details (New) about the selected prediction, include the following parameters:

The place ID from the Autocomplete (New) response
The session token used in the Autocomplete (New) request
The fields parameter specifying fields such as address and geometry

Consider delaying Autocomplete (New) requests
You can employ strategies such as delaying a Autocomplete (New) request until the user has typed in the first three or four characters so that your application makes fewer requests. For example, making Autocomplete (New) 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 Autocomplete (New) Per Request + Geocoding.¹

If delaying requests can get your average programmatic request below four, you can follow the guidance for performant Autocomplete (New) with Geocoding API 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 to help your users get the prediction they're looking for in fewer characters.

For costs, see Google Maps Platform pricing lists.

Performance best practices

The following guidelines describe ways to optimize Autocomplete (New) performance:

Add country restrictions, location biasing, and (for programmatic implementations) language preference to your Autocomplete (New) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
If Autocomplete (New) is accompanied by a map, you can bias location by map viewport.
In situations when a user does not choose one of the Autocomplete (New) 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.
- If you expect the user to enter queries for a specific place by name or address, use a Place Details (New) request. If results are only expected in a specific region, use 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 Autocomplete (New).
- 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 Autocomplete (New) to prefer showing results within the defined area. Results outside of the defined area may still be displayed. You can use the components parameter to filter results to show only those places within a specified country.

Warning: If radius is not provided, the location parameter is ignored.

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 locationRestriction parameter. This instructs Autocomplete (New) to return only results within that region.

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

Page Summary

Prerequisites

What's new

Add an Autocomplete widget

Add an Autocomplete widget to a web page

TypeScript

JavaScript

Add an Autocomplete widget to a map

TypeScript

JavaScript

Constrain Autocomplete predictions

Restrict place search by country

Restrict place search to map bounds

Bias place search results

Restrict place search results to certain types

Get place details

TypeScript

JavaScript

TypeScript

JavaScript

Example maps

Autocomplete element

TypeScript

JavaScript

CSS

HTML

Try Sample

Autocomplete map

TypeScript

JavaScript

CSS

HTML

Try Sample

Autocomplete (New) optimization

Cost optimization best practices

Basic cost optimization

Advanced cost optimization

Yes, needs more details

No, needs only address and location

Yes

No

Performance best practices

Location biasing

Location restricting

Place Autocomplete Widget