Address Autocomplete documentation.

Version: 1.0.0
Requires: WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+
Support: quixwp.com/support
Docs: quixwp.com/docs/address-autocomplete

Table of Contents

1. Overview
2. Requirements
3. Installation
4. Quick Start
5. Configuration Reference
6. Provider Setup
7. Country Restriction
8. Dropdown Theme
9. Hooks & Filters
10. REST API Reference
11. Customising the Dropdown
12. Registering a Custom Provider
13. Troubleshooting
14. Changelog

Overview

QuixWP Address Autocomplete adds real-time address suggestions to the WooCommerce checkout. As a customer types their street address, a dropdown of suggestions appears. Selecting one automatically fills the street address, city, state, postcode, and country — reducing errors, cart abandonment, and failed deliveries.

Key design decisions:

• All geocoding API calls are made server-side via a WordPress REST endpoint. Your API key is never exposed in the browser or network tab.
• Country restriction is automatic — derived from WooCommerce shipping settings, not a manual field.
• Supports 7 providers across three tiers, switchable from the admin without touching code.
• Compatible with both classic shortcode checkout and block-based checkout.
• Zero runtime JavaScript dependencies — pure vanilla JS, no jQuery, no lodash.

Requirements

An API key from at least one supported geocoding provider is required. Geoapify offers 3,000 free requests/day with no credit card required — ideal for testing.

Installation

Via WP Admin (recommended)

1. Download quixwp-address-autocomplete.zip from your account.
2. Go to WP Admin → Plugins → Add New → Upload Plugin.
3. Upload the zip and click Install Now, then Activate Plugin.

Via FTP

1. Unzip and upload the quixwp-address-autocomplete/ folder to /wp-content/plugins/.
2. Activate via WP Admin → Plugins.

After activation a new tab appears at WooCommerce → Settings → Address Autocomplete.

Quick Start

Get autocomplete working in under 5 minutes using Geoapify’s free tier:

1. Sign up at myprojects.geoapify.com — no credit card required.
2. Create a project and copy the API key.
3. Go to WooCommerce → Settings → Address Autocomplete.
4. Check Enable Plugin.
5. Select Geoapify in the provider grid.
6. Paste your API key in the Geoapify field.
7. Click Save Settings (WooCommerce’s blue button at the page bottom).
8. Visit your checkout and type in the billing address field.

Configuration Reference

All settings live under WooCommerce → Settings → Address Autocomplete.

General

Country Restriction

Country restriction is automatic. The plugin reads your WooCommerce shipping countries and restricts results accordingly. There is no manual field — see Country Restriction.

Autocomplete Provider

Seven providers across three tiers. Only the selected provider’s API key is used; keys for inactive providers are saved but never called.

Provider Setup

Google Places

Free tier: $200 monthly credit (~67,000 requests)

1. Go to console.cloud.google.com.
2. Enable the Places API for your project.
3. Create an API key under Credentials.
4. Under API restrictions, select Places API only.
5. Under Application restrictions, choose IP addresses and add your server’s IP (leave empty for local development).
6. Paste the key into the Google Places field and save.

Mapbox Search

Free tier: 50,000 map loads/month

1. Sign up at mapbox.com and go to Account → Access tokens.
2. Click Create a token.
3. Leave all Public scopes checked (default). Do not check any Secret scopes.
4. Leave URL restrictions empty — Mapbox URL restrictions are for client-side browser tokens only. Server-side PHP requests don’t send an Origin header, so a URL restriction will cause all requests to fail.
5. Click Create token, copy the pk. token, and paste it into the Mapbox Search field.

HERE Geocoding & Search

Free tier: 1,000 requests/day

1. Sign up at developer.here.com.
2. Go to Projects → REST → Generate API Key.
3. Paste the key into the HERE field.

Note: HERE’s country filter requires ISO 3166-1 alpha-3 codes internally (e.g. “AUS” not “AU”). The plugin handles this conversion automatically.

TomTom

Free tier: 2,500 requests/day

1. Sign up at developer.tomtom.com.
2. Go to Dashboard → Keys → Create API Key, enable the Search API product.
3. Paste the key into the TomTom field.

Loqate

Free trial: Credit-based trial from sales

1. Sign up at loqate.com.
2. Go to Account → API Keys → Generate New Key.
3. Paste the key into the Loqate field.

Note: Loqate returns a hierarchy of results (containers → addresses). The plugin automatically drills down through containers to return final address suggestions.

LocationIQ

Free tier: 5,000 requests/day

1. Sign up at locationiq.com.
2. Go to Dashboard → Access Tokens → Create Token.
3. Paste the token into the LocationIQ field.

Geoapify

Free tier: 3,000 requests/day, no credit card

1. Sign up at myprojects.geoapify.com.
2. Click Add a new project and copy the API Key.
3. Paste it into the Geoapify field.

Country Restriction

The plugin automatically restricts address suggestions to the countries your WooCommerce store ships to. No manual configuration is needed.

To change which countries are suggested:

Go to WooCommerce → Settings → Shipping → Shipping options and update your shipping destination countries. The autocomplete will immediately reflect this change.

Multi-country support per provider:

If no shipping countries are configured in WooCommerce, suggestions are returned worldwide.

Dropdown Theme

The dropdown colour scheme is set explicitly in the plugin settings rather than using the visitor’s OS dark mode preference. This ensures the dropdown always matches your store’s checkout design.

Light (default) — white background, dark text. Use for stores with a light/white checkout page.

Dark — dark navy background, light text. Use for stores with a dark-themed checkout.

To change: WooCommerce → Settings → Address Autocomplete → Dropdown Theme → Save Settings.

Both themes use CSS custom properties, so you can further customise any colour by adding overrides to your theme’s CSS:

/* Override the active item background */
.quixwp-ac-theme-light {
    --qwp-ac-active-bg: #fff3cd;
    --qwp-ac-active-color: #856404;
}

Hooks & Filters

PHP Actions

qwp_ac_loaded

Fires after the plugin has fully initialised.

add_action( 'qwp_ac_loaded', function( $plugin ) {
    // $plugin is the Plugin singleton instance.
} );

qwp_ac_register_providers

Fires during provider registration. Use to register a custom provider.

add_action( 'qwp_ac_register_providers', function( $registry ) {
    $registry->register( new My_Custom_Provider() );
} );

PHP Filters

qwp_ac_field_address_1 (and siblings)

Filter the CSS selector used to identify checkout fields. Useful for custom themes with non-standard field IDs.

// Add a custom checkout field ID alongside the default.
add_filter( 'qwp_ac_field_address_1', function( $selector ) {
    return $selector . ', #my_custom_address_field';
} );

Available for: qwp_ac_field_address_1, qwp_ac_field_address_2, qwp_ac_field_city, qwp_ac_field_state, qwp_ac_field_postcode, qwp_ac_field_country.

JavaScript Events

qwp_ac_autofilled

Dispatched on document.body after all checkout fields have been populated from a selected suggestion.

document.body.addEventListener( 'qwp_ac_autofilled', function( event ) {
    const { prefix, address } = event.detail;
    // prefix: 'billing_' or 'shipping_'
    // address: normalized address object { address_1, city, state, postcode, ... }
    console.log( 'Autofilled:', prefix, address );
} );

REST API Reference

Two internal REST endpoints under the quixwp-ac/v1 namespace. Used by the plugin’s own JavaScript; available for custom integrations. All requests require a valid X-WP-Nonce header (or _wpnonce query param).

GET /wp-json/quixwp-ac/v1/suggest

Returns address suggestions for a partial input string.

Parameters:

Example response:

{
  "success": true,
  "provider": "geoapify",
  "suggestions": [
    {
      "place_id": "517e48...",
      "label": "123 Main Street, Melbourne VIC 3000, Australia",
      "description": "Melbourne, Australia"
    }
  ]
}

GET /wp-json/quixwp-ac/v1/details

Returns the full normalized address for a place_id from /suggest.

Parameters:

Example response:

{
  "success": true,
  "address": {
    "address_1":    "123 Main Street",
    "address_2":    "",
    "city":         "Melbourne",
    "state":        "Victoria",
    "state_code":   "VIC",
    "postcode":     "3000",
    "country":      "Australia",
    "country_code": "AU",
    "lat":          -37.8136,
    "lng":          144.9631
  }
}

Customising the Dropdown

All visual properties use CSS custom properties. Override any token in your theme’s stylesheet — no child theme required.

/* Light theme overrides */
.quixwp-ac-theme-light {
    --qwp-ac-bg:           #ffffff;  /* Dropdown background */
    --qwp-ac-border:       #e2e2e2;  /* Border colour */
    --qwp-ac-hover-bg:     #f5f7fa;  /* Item hover background */
    --qwp-ac-active-bg:    #eef2ff;  /* Keyboard-selected item */
    --qwp-ac-text:         #1a1a2e;  /* Label text */
    --qwp-ac-desc:         #6b7280;  /* Secondary description */
    --qwp-ac-mark-bg:      #fef08a;  /* Query match highlight */
    --qwp-ac-shadow:       0 4px 16px rgba(0,0,0,.10);
    --qwp-ac-radius:       6px;
    --qwp-ac-z:            9999;     /* z-index */
}

/* Dark theme overrides */
.quixwp-ac-theme-dark {
    --qwp-ac-bg:     #1e1e2e;
    --qwp-ac-text:   #e2e2f0;
    /* ...etc */
}

Registering a Custom Provider

Implement AutocompleteProviderInterface, extend AbstractProvider, and register via the qwp_ac_register_providers action hook.

use QuixWP\AddressAutocomplete\Providers\AbstractProvider;

class My_Custom_Provider extends AbstractProvider {

    public function get_slug(): string  { return 'my_provider'; }
    public function get_name(): string  { return 'My Custom Provider'; }

    public function get_links(): array {
        return [
            'api_key_url' => 'https://example.com/api-keys',
            'docs_url'    => 'https://example.com/docs',
            'pricing_url' => 'https://example.com/pricing',
        ];
    }

    public function get_suggestions( string $input, array $options = [] ): array {
        $data = $this->http_get( 'https://api.example.com/autocomplete', [
            'q'   => $input,
            'key' => $this->api_key,
        ] );

        return array_map( fn( $item ) => [
            'place_id'    => $item['id'],
            'label'       => $item['full_address'],
            'description' => $item['city'],
        ], $data['results'] ?? [] );
    }

    public function get_details( string $place_id ): array {
        $data = $this->http_get( 'https://api.example.com/details', [
            'id'  => $place_id,
            'key' => $this->api_key,
        ] );

        return array_merge( $this->empty_address(), [
            'address_1' => $data['street'] ?? '',
            'city'      => $data['city']   ?? '',
            'postcode'  => $data['zip']    ?? '',
            'country_code' => $data['country'] ?? '',
        ] );
    }
}

add_action( 'qwp_ac_register_providers', function( $registry ) {
    $registry->register( new My_Custom_Provider() );
} );

Your provider will automatically appear in the admin settings UI, including its own API key field.

Troubleshooting

Dropdown doesn’t appear

1. Confirm Enable Plugin is checked and settings are saved.
2. Open browser DevTools (F12) → Console. Look for errors referencing autocomplete.js.
3. On the checkout page, run in the console: console.log(quixwpAC) — if this returns undefined, the JS isn’t loading. Check that assets/dist/js/autocomplete.js exists in the plugin folder.
4. Run: document.querySelector('#billing-address_1') || document.querySelector('#billing_address_1') — if both return null, the plugin can’t find your theme’s address field. Use the qwp_ac_field_address_1 filter to point to the correct selector.

Settings won’t save (403 error)

A security plugin (Wordfence, iThemes Security) may be blocking the WooCommerce settings POST. Temporarily disable security plugins to confirm, then whitelist the WooCommerce settings URL in your security plugin’s settings.

A provider returns no results

Test the REST endpoint directly in your browser (while logged in):

/wp-json/quixwp-ac/v1/suggest?q=123+main&_wpnonce=NONCE

Get a nonce by running console.log(quixwpAC.nonce) on the checkout page. If the endpoint returns an error message it will be visible in the JSON response, pointing to the exact API issue.

City fills but postcode doesn’t

This can happen with landmark/POI addresses where the geocoding API returns the postcode embedded in the formatted address string rather than as a structured field. The plugin automatically parses postcodes from the label string as a fallback for Australian, US, UK, and Canadian formats. If your country’s format isn’t covered, open a support ticket.

State field not being set

WooCommerce reloads the state dropdown after a country change. The plugin waits 350ms after setting the country before attempting to set the state. If your theme or a plugin significantly delays the state list reload, you can listen to the qwp_ac_autofilled JS event and set the state manually.

Changelog

1.0.0

• Initial release
• 7 providers: Google Places, Mapbox Search, HERE Geocoding, TomTom, Loqate, LocationIQ, Geoapify
• Classic checkout and block checkout support
• Server-side REST proxy — API keys never exposed client-side
• Automatic country restriction from WooCommerce shipping settings
• Explicit light and dark dropdown themes (no prefers-color-scheme dependency)
• React-compatible field autofill for block checkout
• Postcode extraction fallback from suggestion label
• Loqate container drill-down for full address resolution
• HERE alpha-3 country code conversion
• TomTom BCP47 language tag conversion
• Accessible dropdown: keyboard navigation, ARIA attributes, screen reader support
• CSS custom properties for complete theme customisation
• qwp_ac_register_providers action for custom provider registration
• Full HPOS (High Performance Order Storage) compatibility