# DfAddressAutocomplete — Address Autocomplete for Shopware 6

> Overview DfAddressAutocomplete adds an instant address search to Shopware 6 address forms: checkout, customer account address book and registration. The customer types the beginning of their address, picks a suggestion…

- Page: <https://www.datafirefly.com/en/documentation/dfaddressautocomplete-shopware/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/dfaddressautocomplete-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfaddressautocomplete-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfaddressautocomplete-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddressautocomplete-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaddressautocomplete-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddressautocomplete-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddressautocomplete-shopware/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

DfAddressAutocomplete adds an instant address search to Shopware 6 address forms: checkout, customer account address book and registration. The customer types the beginning of their address, picks a suggestion and every field fills itself — street, additional line, postcode, city and country.

Two providers ship out of the box: **BAN** (Base Adresse Nationale, free, France) and **Google Places (New)** (paid, worldwide). The architecture is extensible: any address API can be plugged in through a PHP interface.

## Requirements

- Shopware 6.6 or 6.7
- PHP 8.2 or higher
- For Google Places: a Google Cloud API key with the **Places API (New)** enabled (not the legacy Places API)

## Installation

1. Upload the ZIP into `custom/plugins/` or through the Shopware admin (Extensions → My Extensions → Upload extension).
2. Run the following commands:

```
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
```

1. Compile the storefront so the JavaScript and CSS are bundled:

```
./bin/build-storefront.sh
```

On environments without the build script, use `bin/console theme:compile` after the assets have been compiled once.

## Configuration

Go to **Extensions → My Extensions → DfAddressAutocomplete → Configure**. Every setting is sales-channel scopable.

### Provider

- **Autocomplete provider**: BAN (default) or Google Places.
- **Google Places API key**: only required when Google is selected. The key stays server-side and is never sent to the browser.
- **Country restriction**: comma-separated ISO 3166-1 alpha-2 codes (e.g. `FR,BE,LU,CH`). Blank = no restriction. Only applies to Google (BAN is France-only by nature).

### Activation pages

Three independent switches: **checkout**, **customer account** (address book) and **registration**. Each can be enabled or disabled separately.

### Behavior

- **Minimum characters** (default 3): no search below this threshold.
- **Debounce delay** (default 250 ms): wait time after the last keystroke before the API is queried.
- **Maximum suggestions** (default 5).
- **Server-side cache** (enabled by default): 5 minutes on searches, 15 minutes on details. Cuts Google billing and latency.

## Setting up Google Places

1. In the [Google Cloud Console](https://console.cloud.google.com/), create or select a project.
2. Enable the **Places API (New)** — careful, not the legacy "Places API".
3. Create an API key and restrict it **by server IP address** (your Shopware hosting IP). Do not restrict it by HTTP referrer: the traffic is server-to-server.
4. Paste the key into the plugin configuration.

The Places API (New) is billed per usage. The plugin's server-side cache and debounce limit the number of calls, but monitor your consumption in the Google console.

## How it works client-side

A search field appears above the standard address form. Keyboard navigation is complete: up/down arrows to browse suggestions, Enter to select, Escape to close. On selection, the standard Shopware fields are filled and the country is automatically selected in the dropdown.

## Adding a custom provider

Implement the `AutocompleteProviderInterface` interface (namespace `DataFirefly\DfAddressAutocomplete\Provider`) in your own plugin:

```
final class MapboxProvider implements AutocompleteProviderInterface
{
    public function getKey(): string { return 'mapbox'; }

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Query your API and return an array of AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Resolve the id into a full AddressDetails
    }
}
```

Then tag the service in your services.xml (service id = your provider's fully qualified class):

```
<service id="My\Plugin\MapboxProvider">
    <tag name="df_address_autocomplete.provider"/>
</service>
```

Every suggestion embeds its provider prefix in its id (e.g. `mapbox:abc123`): detail calls are routed automatically.

## Custom themes

The plugin extends the standard `component_address_form` component and detects fields by their name (`*AddressStreet`, `*AddressZipcode`, `*AddressCity`, `*AddressCountry`). If your theme renames these fields, override the `_cacheTargetFields` method of the JavaScript plugin to teach it the new names.

## Troubleshooting

- **The search field does not appear**: make sure the storefront was recompiled after activation, and that the relevant page is enabled in the configuration.
- **No suggestions with Google**: check that the Places API (New) is enabled on the project, that the key is valid and that its IP restriction matches your server's IP.
- **The country is not selected**: the plugin compares the ISO code with the `data-country-iso` attribute of the dropdown options, then with their visible text. If your theme exposes neither, the current country is kept.

## Privacy (GDPR)

The plugin stores no personal data. User input flows through your Shopware server to the selected provider. With BAN, data is processed by a French public service (DINUM). With Google, it is subject to Google Cloud terms — mention it in your privacy policy if applicable.