How Gatemi Address Autocomplete Works

Three rules

  1. Autocomplete never replaces a field. WooCommerce's own address inputs stay exactly where they are. The plugin adds a search box above them and writes the picked address into them. A missing key, a referrer restriction, an exhausted quota, an ad blocker or an unreachable Google costs a convenience, never an order.
  2. It is built on Google's new element. Google has deprecated its old google.maps.places.Autocomplete widget in favour of PlaceAutocompleteElement. The plugin uses the new element only. Where it is not available, the plugin stands down rather than falling back to the widget Google is removing.
  3. The key is public, and the plugin says so. It is handed to every shopper's browser. What protects it is the referrer restriction in Google's console.

Step by step

1. Deciding whether to load anything

On each storefront page the plugin checks:

  • Use address autocomplete is on,
  • a key is saved,
  • at least one of the billing and shipping addresses is switched on,
  • Full edition: the gmaa_enabled filter does not return false, and
  • the page is the checkout (is_checkout()) or My Account's address editor (is_account_page() on the edit-address endpoint).

If any of these is false, nothing is enqueued. On every other page of the shop — products, the cart, blog posts, the rest of My Account — there is no Google script, because loading Maps there would be a request your shoppers wait for and nobody uses.

2. Loading Google's script

The plugin enqueues Google's loader, https://maps.googleapis.com/maps/api/js?key=…&libraries=places&v=weekly&loading=async, under the script handle google-maps-places, followed by its own small script and stylesheet. Using a shared handle means a theme or plugin that already loads Maps under that handle does not get a second copy.

The plugin's own script receives, from PHP, the key, the sections to attach to (billing, shipping), the country list and the field map. The map lives in PHP only, so when Google renames an address component there is one table to change, not two.

3. Attaching the search box

When the page is ready, the script asks Google for the Places library and, for each section, looks for the field named billing_address_1 or shipping_address_1. It inserts a PlaceAutocompleteElement above it with the placeholder "Start typing your address…", restricted to your countries if you set any.

Each field is marked once it has a box, so it never gets two. WooCommerce redraws the classic checkout's fields on every shipping update; the script listens for WooCommerce's updated_checkout and country_to_state_changed events and attaches again to the redrawn fields.

The Checkout block draws its own address fields after the page has loaded (they carry ids rather than name attributes). The script watches the page for them and attaches the search box to the block's address line as soon as it appears.

4. Filling the fields

When the shopper picks a suggestion, the script asks Google for that place's address components and writes them in:

WooCommerce field Built from Google's components
Country country (short code, e.g. GB) — written first
Street address street_number then route, joined with a space
Apartment, suite… subpremise
Town / City postal_town, or locality if there is no post town
Postcode / ZIP postal_code
State / County administrative_area_level_1 (short code)

Three details matter:

  • The country goes first. WooCommerce rebuilds the state field when the country changes; setting the state before the country would put a value into a field that is about to be replaced.
  • Post town before locality. In the UK, locality can be a district or ward; postal_town is the town on the envelope. Only one of the two is used.
  • Every write fires input and change events. WooCommerce recalculates shipping from the country and the postcode; a value set silently would leave the checkout quoting the wrong postage. On the Checkout block the address is instead written through WooCommerce's own checkout data store (wc/store/cart) in one call, with the country and state together, which is how the block itself changes an address.

A component Google does not return leaves its field as it was.

5. When something fails

Every failure ends with the checkout as it was:

  • Google's script did not load (blocked, offline): the plugin's script finds no google.maps and does nothing.
  • The key is refused, restricted or out of quota: the library import fails and is caught silently.
  • The new element is not available: the plugin does not insert anything.

In each case the shopper types their address in the ordinary fields.

Worked example

A shop in Ireland ships to Ireland and the UK. It sets Only suggest addresses in these countries to IE, GB and switches On the shipping address off, because its customers almost always ship to the billing address.

On the checkout, the billing address gets a search box. A shopper in Manchester types "12 Deans", picks "12 Deansgate, Manchester M3 …", and the fields fill: country GB, street "12 Deansgate", town "Manchester", postcode, county. Shipping is recalculated. A French address is never suggested, and the shipping address — if the shopper ticks "Ship to a different address" — is typed by hand.

What the full edition adds

Full edition: filters to change the field map (gmaa_field_map), the Maps loader URL (gmaa_script_url, for pinning a version or a regional endpoint) and whether autocomplete runs on a given request (gmaa_enabled). See the developer reference.

Shopping Cart
Scroll to Top