API Reference

Complete guide to configuration parameters, methods, and options for Places Autocomplete JS.

← Back to Home Styling Guide → Examples →

Quick Example

Here's a complete example showing all major configuration options:

const autocomplete = new PlacesAutocomplete({
  containerId: 'autocomplete-container',
  googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  googleMapsApiVersion: 'weekly',
  fetchFields: ['formattedAddress', 'addressComponents'],
  onResponse: (placeDetails) => {
    console.log('Selected place:', placeDetails);
  },
  onError: (error) => {
    console.error('Error:', error.message);
  },
  options: {
    placeholder: 'Enter your address...',
    debounce: 150,
    autofocus: true
  },
  requestParams: {
    language: 'en-GB',
    region: 'GB',
    includedRegionCodes: ['GB']
  }
});

Configuration Parameters

The main configuration object passed to the PlacesAutocomplete constructor.

Parameter	Type	Required	Description
containerId	string	Yes	The ID of the HTML element where the autocomplete widget will be rendered.
googleMapsApiKey	string	Yes	Your Google Maps API Key with the Places API (New) enabled.
googleMapsApiVersion	string	No	API version to load ("weekly", "quarterly", "beta"). Default: "weekly"
onResponse	function	No	Callback triggered with selected place details. Receives a Place object.
onError	function	No	Callback triggered on errors. Receives an Error object or string.
options	object	No	UI behavior and appearance options. See UI Options below.
requestParams	object	No	Google Places API request parameters. See Request Parameters below.
fetchFields	array	No	Place Data Fields to fetch. Default: ['formattedAddress', 'addressComponents']

UI & Behavior Options

Options to customize the component's appearance and behavior, passed via the options parameter.

Option	Type	Default	Description
placeholder	string	"Start typing..."	Placeholder text for the input field.
debounce	number	100	Delay (ms) before API request after user stops typing. Set to 0 to disable.
distance	boolean	true	Show distance in suggestions (requires origin in requestParams).
distance_units	'km' \| 'miles'	'km'	Units for distance display.
label	string	""	Optional label text above the input field.
autofocus	boolean	false	Auto-focus input on initialization.
autocomplete	string	'off'	HTML autocomplete attribute value.
clear_input	boolean	true	Clear input after selection. If false, retains formattedAddress.
classes	object	...	Custom CSS classes. See Styling Guide.

API Request Parameters

Parameters sent to the Google Places Autocomplete API via the requestParams option. See Google's AutocompleteRequest documentation for all available options.

Parameter	Type	Description
language	string	Language code for results (e.g., "en", "fr", "de").
region	string	Region code as ccTLD (e.g., "GB", "US").
includedRegionCodes	string[]	Array of up to 5 CLDR region codes to restrict results.
locationBias	object	Area to bias results towards (circle or rectangle).
locationRestriction	object	Area to strictly restrict results to.
origin	LatLngLiteral	Origin point for distance calculations { lat, lng }.

Examples

// Basic region filtering
requestParams: {
  language: 'en-GB',
  region: 'GB',
  includedRegionCodes: ['GB']
}

// With location biasing
requestParams: {
  language: 'en-US',
  region: 'US',
  locationBias: {
    lat: 53.39670653190076,
    lng: -2.9346197562747967
  }
}

// With origin for distance calculations
requestParams: {
  language: 'fr',
  region: 'FR',
  includedRegionCodes: ['FR'],
  origin: { lat: 48.8566, lng: 2.3522 } // Paris
}

// Strict location restriction
requestParams: {
    locationRestriction: {
        north: 54.206681559752205,
        east: -0.7812994437747967,
        south: 52.95447972935652,
        west: -3.6816900687747967
    }
}

Fetch Fields

Specify which place data fields to retrieve when a user selects a suggestion. This directly impacts API costs.

Billing Impact

Different fields have different costs. See Google's Place Data Fields pricing for details.

Common Fields

formattedAddress - The complete address string
addressComponents - Structured address parts (street, city, etc.)
location - Latitude/longitude coordinates
displayName - Human-readable place name
types - Array of place types
viewport - Recommended map viewport
plusCode - Plus code representation

Examples

// Minimal fields (lowest cost)
const autocomplete = new PlacesAutocomplete({
  containerId: 'autocomplete-container',
  googleMapsApiKey: 'YOUR_API_KEY',
  fetchFields: ['formattedAddress']
});

// Standard fields
fetchFields: ['formattedAddress', 'addressComponents', 'location']

// Extensive fields (higher cost)
fetchFields: [
  'formattedAddress',
  'addressComponents',
  'location',
  'displayName',
  'types',
  'viewport',
  'plusCode'
]

Public Methods

The PlacesAutocomplete instance provides several methods for dynamic control.

`clear()`

Clears the input field, removes visible suggestions, and refreshes the session token.

autocomplete.clear();

`destroy()`

Removes event listeners and cleans up DOM elements. Use when the component is no longer needed.

autocomplete.destroy();

`setFetchFields(fields)`

Dynamically updates the Place Data Fields to fetch. Merged with default fields.

autocomplete.setFetchFields(['displayName', 'types', 'location']);

`getFetchFields()`

Returns the current array of Place Data Fields that will be requested.

const fields = autocomplete.getFetchFields();

`setRequestParams(params)`

Dynamically updates API request parameters. Useful for changing search criteria after initialization.

autocomplete.setRequestParams({ region: "US", language: "en-US" });

`getRequestParams()`

Returns the current API request parameters.

const params = autocomplete.getRequestParams();

`setOptions(options)`

Dynamically updates UI behavior and appearance options.

autocomplete.setOptions({ placeholder: "New placeholder...", debounce: 250 });

`getOptions()`

Returns the current UI and behavior options.

const options = autocomplete.getOptions();

Complete Example

// Clear input and reset
autocomplete.clear();

// Update request parameters dynamically
autocomplete.setRequestParams({
  region: 'US',
  language: 'en-US',
  origin: { lat: 40.7128, lng: -74.0060 }
});

// Update UI options
autocomplete.setOptions({
  placeholder: 'New placeholder...',
  debounce: 200
});

// Update fetch fields
autocomplete.setFetchFields(['displayName', 'types', 'location']);

// Get current configuration
const currentParams = autocomplete.getRequestParams();
const currentOptions = autocomplete.getOptions();
const currentFields = autocomplete.getFetchFields();

// Clean up when done
autocomplete.destroy();

← Back to Home

Styling Guide → Examples →