Places API & Autocomplete: Implementation Guide

Building Address Autocomplete

Address autocomplete reduces form abandonment by 30% and eliminates address formatting errors. Here's how to implement it properly.

Autocomplete Request

GET /place/autocomplete/json?
  input=123+Main+St
  &types=address
  &components=country:us
  &key=YOUR_API_KEY

The response returns up to 5 predictions with place IDs that you can use to fetch full address details.

Session Tokens

Use session tokens to group autocomplete requests with a Place Details request. Without tokens, each keystroke is billed separately. With tokens, the entire session (all keystrokes + final selection) counts as one billable event.

const sessionToken = crypto.randomUUID();

// All autocomplete requests in this session use the same token
fetch(`/place/autocomplete/json?input=${query}&sessiontoken=${sessionToken}&key=${API_KEY}`)

// When user selects a result, use the same token for details
fetch(`/place/details/json?place_id=${placeId}&sessiontoken=${sessionToken}&key=${API_KEY}`)

Debouncing Requests

Don't fire a request on every keystroke. Debounce by 300ms to reduce unnecessary API calls:

let debounceTimer;
function onInputChange(value) {
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(() => {
    fetchAutocomplete(value);
  }, 300);
}

UX Best Practices

• Show predictions in a dropdown below the input field
• Highlight the matching portion of each prediction
• Allow keyboard navigation (arrow keys + enter)
• Clear predictions when the input is empty
• Handle the "no results" state gracefully

Field Masks for Cost Control

When fetching Place Details after selection, only request the fields you need. For address autocomplete, you typically only need formatted_address and geometry — both basic fields at the lowest pricing tier.