README

A typed PHP 8.4 client for French government APIs, auto-generated from their official OpenAPI specifications.

Requirements
Installation
Supported APIs
Quick Start
Development & Contribution

Requirements

PHP 8.4+
Composer

Installation

composer require ecourty/data-gouv-client

Supported APIs

API	Client class	Auth	Documentation
data.gouv.fr	`DataGouvClient`	Optional API key	docs/datagouv.md
SIRENE (INSEE)	`SireneClient`	API key required	docs/sirene.md
Recherche d'entreprises	`EntrepriseClient`	None	docs/entreprise.md
Géoplateforme Géocodage	`GeoplatformeClient`	Optional Bearer token	docs/geoplateforme.md
API Géo	`GeoClient`	None	docs/geo.md
Info Financière	`InfoFinanciereClient`	Optional API key	docs/infofinanciere.md
Éducation Nationale	`EducationClient`	None	docs/education.md
Annuaire des services publics	`AnnuaireServicePublicClient`	None	docs/annuaire-service-public.md
Calendrier Scolaire	`CalendrierScolaireClient`	None	docs/calendrierscolaire.md
Jours Fériés	`JoursFeriesClient`	None	docs/joursferies.md

Sub-clients are exposed as PHP 8.4 virtual property hooks — access them directly, no method call needed.

Quick Start

use Ecourty\DataGouv\DataGouv\DataGouvClient;

// Anonymous read-only access
$client = new DataGouvClient();
$datasets = $client->datasets->listDatasets(['q' => 'budget', 'page_size' => 10]);

// Authenticated access (required for write operations)
$client = new DataGouvClient(apiKey: 'your-key');
$me = $client->me->getMe();

See each API's documentation in docs/ for details on authentication, sub-clients, and examples.

Development & Contribution

Setup

git clone https://github.com/EdouardCourty/data-gouv-client
cd data-gouv-client
composer install

Regenerate from the API specs

The library is fully generated from live OpenAPI specs. To regenerate:

composer generate                                    # all APIs (download → Jane → patch → facade → cs-fix)
php bin/console generate --api=datagouv             # data.gouv.fr only
php bin/console generate --api=sirene               # INSEE SIRENE only
php bin/console generate --api=entreprise           # Recherche d'entreprises only
php bin/console generate --api=geoplateforme        # Géoplateforme Géocodage only
php bin/console generate --api=geo                  # API Géo only
php bin/console generate --api=infofinanciere       # Info Financière only
php bin/console generate --api=education            # Éducation Nationale only
php bin/console generate --api=annuaireservicepublic # Annuaire des services publics only
php bin/console generate --api=calendrierscolaire   # Calendrier Scolaire only
php bin/console generate --api=joursferies          # Jours Fériés only

Do not manually edit anything under src/*/Client/, src/*/Api/, src/*/Exception/, or the *Client.php facades — these files are fully generated. To change their output, edit the scripts in bin/ or src/Generator/ and re-run composer generate.

QA

composer test              # all tests (unit + integration)
composer test-unit         # unit tests only
composer test-integration  # integration tests (hits the real API)
composer phpstan           # static analysis
composer cs-check          # code style check
composer cs-fix            # auto-fix code style
composer qa                # phpstan + cs-check + all tests

Adding a new API

Use the provided CLI command:

php bin/console add-api \
  --name=myapi \
  --spec-url=https://api.example.com/openapi.json \
  --namespace="Ecourty\DataGouv\DataServices\MyApi" \
  --base-url=https://api.example.com \
  --auth=none \
  --generate

See .github/skills/support-new-api/SKILL.md for the full guide.

Contributing

Fork the repository
Create a feature branch
Make your changes (update AGENTS.md, README.md, and docs/ as needed)
Ensure composer qa passes
Open a pull request

Writing integration tests

Every API domain has integration tests in tests/Integration/{Domain}/. When adding a new API or a new endpoint, add the corresponding integration test:

Extend IntegrationTestCase and annotate with #[Group('integration')]
Wrap all API calls with $this->callApi(fn () => ...) — it auto-skips on network errors and rate limits
For "get by ID" endpoints, derive the ID from the list endpoint first
For ODS-platform APIs (OpenDataSoft), use $client->getClient()->method(FETCH_RESPONSE) and $this->decodeResponse($response) since their Jane-generated typed methods return null

Run integration tests with:

composer test-integration                               # all domains
composer validate-integration-coverage                  # verify every domain has ≥1 test
./vendor/bin/phpunit tests/Integration/{Domain}/        # one domain only

ecourty / data-gouv-client

Maintainers

Package info

Statistics

Security