Autonnel v0.1.0
Get started

Google Maps

Optional Google Maps API key for address autocomplete on checkout.

Google Maps integration is optional. Without it, address fields on checkout pages are plain text inputs. When configured, the AddressForm Puck component gains autocomplete powered by the Google Places API, which reduces address entry errors.

How it works

The API key is configured under the google.maps.api_key runtime setting. When autonnel renders an AddressForm component on a checkout page, it checks for this key and activates autocomplete if present.

Configure the key

  1. Go to Settings → Google Maps.
  2. Paste your API key into the field and save.

That is all autonnel requires. The feature activates immediately for all checkout pages in your deployment.

Generate a key in GCP

  1. Open the Google Cloud Console.
  2. Navigate to APIs & Services → Credentials.
  3. Click Create credentials → API key.
  4. Once the key is created, go to APIs & Services → Library and enable both Places API and Geocoding API for your project.

Restrict the key

An unrestricted key can be used by anyone who finds it in your page source. Always restrict the key before going to production:

  1. In the Cloud Console, open the key you created.
  2. Under Application restrictions, select HTTP referrers (websites).
  3. Add your domains, for example: 
    https://yourstore.com/*
https://www.yourstore.com/*
  4. Save the restriction.

If someone else uses your unrestricted key, Google bills you for their usage. Domain restrictions prevent that.

Billing

Google charges for autocomplete on a per-session basis. A session begins when the user starts typing and ends when they select an address. As of mid-2025, the rate is approximately $2.83 per 1,000 sessions. Review current pricing in the Google Maps Platform pricing guide.

Controlling which APIs are enabled

When you create the key, enable exactly the APIs you need:

  • Places API — required for address autocomplete suggestions as the customer types
  • Geocoding API — required for resolving a selected suggestion into a structured address object (street, city, postal code, country)

Enabling APIs you do not need increases your billing surface. If you want autocomplete only, both APIs are needed together because Places returns the suggestion and Geocoding resolves it.

You can also set an API restrictions filter on the key itself (separate from the HTTP referrer restriction). Under API restrictions, choose Restrict key and select only Places API and Geocoding API. This means even if the referrer check is misconfigured, the key cannot be used for Maps Embed, Street View, or other services.

What happens without the key

When google.maps.api_key is not configured, the AddressForm component renders standard text fields for address line 1, city, state/province, postal code, and country. Customers can still check out; they just type their address manually without suggestions.

There is no error or warning shown to the customer when the key is missing. The form behaves identically to any plain text address form.

Caveats

  • If you skip domain restrictions, anyone can use your key and generate charges on your account. An unrestricted key embedded in a public page is the same as posting the key publicly.
  • The autocomplete only activates on pages that contain an AddressForm component. Other text inputs are not affected.
  • Removing the key from Settings disables autocomplete immediately; address fields revert to plain text inputs without a redeploy.
  • Google’s per-session billing only applies when a customer completes an autocomplete interaction (selects a result). Partial typing that does not result in a selection is still billed as a session after a short idle period. See Google’s documentation for the exact session timeout rules.
  • Puck editor — AddressForm component
  • Settings overview