kaveraa / api-gouv-publique-fr

v1.0.0 2026-10-01 14:39 UTC

Requires

• php: ^8.3
• ext-json: *
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/simple-cache: ^2.0 || ^3.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• nyholm/psr7: ^1.8
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.0 || ^4.0
• pestphp/pest-plugin-laravel: ^3.0 || ^4.0
• symfony/cache: ^7.4 || ^8.0
• symfony/framework-bundle: ^7.4 || ^8.0
• symfony/http-client: ^7.4 || ^8.0
• symfony/translation: ^7.4 || ^8.0
• symfony/validator: ^7.4 || ^8.0
• symfony/yaml: ^7.4 || ^8.0

Suggests

• illuminate/support: Enables the Laravel bridge (facade, config, validation rules, fakes).
• nyholm/psr7: A PSR-17 factory, needed by Psr18Transport outside Laravel.
• symfony/cache: Enables the response cache in the Symfony bundle.
• symfony/framework-bundle: Enables the Symfony bundle (configuration, autowired clients, cache, fake mode).
• symfony/http-client: A PSR-18 client for plain PHP, and the HTTP layer of the Symfony bundle.
• symfony/translation: Translates the Symfony constraint messages into French (English is built in).
• symfony/validator: Enables the Siren, Siret and EntrepriseExiste constraints in Symfony.

MIT

• Augustin Kavera

• symfony
• geo
• bundle
• laravel
• Siren
• Siret
• commune
• france
• ban
• adresse
• open-data
• api-gouv

Published on Packagist.org on 2026-10-01 14:40 UTC

README

English - Français

A typed PHP client for French public APIs. Version 0.1 covers company search ("Recherche d'entreprises") and address search (the BAN, served by the Geoplateforme). Version 0.2 adds the Geo API (communes, departements, regions, EPCI). Version 0.3 adds a Symfony bundle. It works in any PHP project. It has optional bridges for Laravel and Symfony. Version 1.0 is stable: see the backward compatibility promise.

This is an unofficial project. It is not affiliated with the French State.

Requirements

• PHP 8.3 or newer
• Laravel 12 or 13 (optional)
• Symfony 7.4 or 8 (optional)

Install

composer require kaveraa/api-gouv-publique-fr

Laravel example

use Kaveraa\ApiGouv\Laravel\ApiGouv;

$company = ApiGouv::entreprises()->parSiren('812487973');
echo $company->nomComplet;            // OCTO
echo $company->siege->commune;        // BORDEAUX

$addresses = ApiGouv::adresse()->rechercher('8 bd du port amiens', 1);
echo $addresses[0]->label;            // 8 Boulevard du Port 80000 Amiens

$commune = ApiGouv::geo()->commune('80021');
echo $commune->nom;                   // Amiens

Plain PHP example

This example uses Symfony HttpClient as the PSR-18 client and Nyholm as the PSR-17 factory.

use Kaveraa\ApiGouv\Entreprises\EntreprisesClient;
use Kaveraa\ApiGouv\Http\Psr18Transport;
use Kaveraa\ApiGouv\Http\Requester;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$transport = new Psr18Transport(new Psr18Client(), new Psr17Factory());
$client = new EntreprisesClient(new Requester($transport, 'https://recherche-entreprises.api.gouv.fr'));

echo $client->parSiren('812487973')->nomComplet;

Guides

• Quick start
• Company search
• Address search
• Geo API
• Laravel
• Symfony
• Plain PHP
• Errors, cache and rate limit
• Testing
• Backward compatibility
• Upgrade from 0.3 to 0.4
• FAQ

Features

• Typed objects (DTOs) for companies, establishments, managers, addresses, communes, departements, regions and EPCI.
• One exception class per problem, all with a common parent: ApiException.
• Optional response cache, off by default. It works with any PSR-16 cache.
• Rate limit retry in Laravel (HTTP 429).
• Laravel validation rules: Siren, Siret and EntrepriseExiste.
• Symfony bundle: configuration, autowired clients and a response cache on a cache pool.
• Symfony validation constraints: Siren, Siret and EntrepriseExiste.
• Test fakes and factories for your own tests, and a fake mode for Symfony tests.

Not included

The INSEE SIRENE API is not included.

Unofficial notice

This package is not made by the French State and is not affiliated with it. "api.gouv.fr" and the API names belong to their owners. Please read the terms of use of each API.

License

MIT. See LICENSE.

Contributing

See CONTRIBUTING.md. To report a security problem, see SECURITY.md.