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 & Behaviour Options

Options to customise the component's appearance and behaviour, passed via the options parameter.

Option	Type	Default	Description
placeholder	string	"Start typing your address ..."	Placeholder text for the input field.
debounce	number	100	Delay in milliseconds before triggering an API request after user stops typing. Set to 0 to disable.
distance	boolean	false	Whether to attempt to show distance in suggestions (requires origin in requestParams).
distance_units	'km' \| 'miles'	'km'	Units to display distance in if distance is true.
label	string	""	Optional label text displayed above the input field.
autofocus	boolean	false	If true, automatically focuses the input field on initialisation.
autocomplete	string	'off'	Standard HTML autocomplete attribute for the input field.
classes	object	(See default classes below)	Object to override default CSS classes for styling. See "Styling" section.
clear_input	boolean	false	If true, clears the input field after a suggestion is selected. If false (default), the input field retains the formattedAddress of the selected place.
response_type	'json' \| 'place'	'json'	Return format: 'json' for plain JSON object (default), 'place' for full Google Maps Place instance with method access.
show_place_type	boolean	false	Whether to display icons representing the place type (🏪, 🍽️, etc.). Mutually exclusive with distance.

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();

`focus()`

Sets focus on the autocomplete text input field.

autocomplete.focus();

`setInputValue(lat, lng)`

Sets input by reverse geocoding coordinates. Requires Geocoding API.

await autocomplete.setInputValue(48.8584, 2.2945);

`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 initialisation.

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

`getRequestParams()`

Returns the current API request parameters.

const params = autocomplete.getRequestParams();

`setOptions(options)`

Dynamically updates UI behaviour and appearance options.

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

`getOptions()`

Returns the current UI and behaviour 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 →