README

Address Completion

Address Completion provides a simple Laravel API for address autocomplete. It uses the French BAN API for French territories and Geoapify as a fallback for other countries.

Installation

This package requires PHP 8.3 or later and Laravel 12 or 13.

You can install the package via Composer:

composer require bestmomo/laravel-address-completion

You may publish all of the package's resources at once:

php artisan vendor:publish --tag="laravel-address-completion"

Or, you may publish each resource individually:

Publishing the Configuration File

php artisan vendor:publish --tag="address-completion-config"

The configuration file is created at config/address-completion.php.

Geoapify API key

Geoapify is used for countries that are not supported by the BAN provider. Add your API key to .env:

GEOAPIFY_KEY=your-api-key

You can get an API key from Geoapify.

Usage

Use the Address facade to search for addresses:

use AddressCompletion\Facades\Address;

$addresses = Address::search('10 rue de Paris');

foreach ($addresses as $address) {
    echo $address->label;
}

The country is optional and defaults to FR. It accepts an ISO 3166-1 alpha-2 country code:

$addresses = Address::search('1600 Pennsylvania Avenue', 'US', limit: 8);

Each result is an AddressCompletion\DTO\Address object with these properties:

Property	Description
`label`	Formatted address label
`street`	Street name and house number when available
`postcode`	Postal code
`city`	City or locality

Queries shorter than five characters return an empty array. Network or provider errors are reported and also return an empty array, so autocomplete can fail gracefully.

Configuration

The published configuration file lets you change the default country, result limit, provider URLs and the countries handled by the BAN provider:

// config/address-completion.php
'default_country' => 'FR',
'limit' => 5,

The BAN provider is selected automatically for configured French territories. Geoapify handles all other countries and requires GEOAPIFY_KEY.

Cache

Address search results are cached automatically for 5 minutes to reduce calls to the BAN and Geoapify APIs. The cache uses Laravel's default cache store, so configure it in your application's cache settings when needed.

Cache entries are separated by provider, country, result limit and search query. To clear cached address results, clear the application's cache:

php artisan cache:clear

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Address Completion! Please review our contributing guide to get started.

bestmomo / laravel-address-completion

Maintainers

Package info

Statistics

Security