README

A library that implements the php-extended/php-api-fr-insee-ban-interface library.

This library makes a collaborative work of the ApiFrInsee, Dgfip, OpenStreetMap Contributors, La Poste and Etalab ; known as the BAN (Base des Adresses Nationale) available as objects to populate a database. The BAN is available at the url : https://adresse.data.gouv.fr/.

Installation

The installation of this library is made via composer and the autoloading of all classes of this library is made through their autoloader.

• Download composer.phar from their website.
• Then run the following command to install this library as dependency :
• php composer.phar php-extended/php-api-fr-insee-ban-object ^9

Basic Usage

This library gives an unique endpoint : \PhpExtended\Insee\InseeCogEndpoint from which all data can be retrieved.

• For most usages, you may use the following code :

use PhpExtended\Insee\InseeBanEndpoint;
use PhpExtended\Endpoint\GzipHttpEndpoint;
use PhpExtended\Endpoint\HttpEndpoint;

/** $client \Psr\Http\Client\ClientInterface */

$endpoint = new ApiFrInseeBanEndpoint(new GzipHttpEndpoint(new HttpEndpoint($client)));

$lastDateTime = $endpoint->getLatestDate();
$departements = $endpoint->getDepartementIds($lastDateTime);

foreach($departements as $departement)
{
	$banLineIterator = $endpoint->getBanLinesIterator($lastDateTime, $departement);
	
	foreach($banLineIterator as $banLine)
	{
		/** @var $banLine \PhpExtended\Insee\InseeBanLine */
		// do something with the ban line representing :
		// - a commune with CodeInsee and NomCommune
		// - a group (street) with Id, NomVoie and NomComplementaire
		// - an address with Id, Numero, Suffixe, CodePostal
		// - a position with Id, X, Y, Lat, Lon
		// - and generic data like type of localisation,
		//     source and date of last update
	}
}

Be wary that the client must follow a certain number of rules regarding the handling of files via the X-Php-Download-File request and response headers for the GzipHttpEndpoint to be able to unzip the downloaded file without having to use gigabytes of memory. It must also return an X-Request-Uri header to get the full uri back.

For an example of the minimal needed http client, look at the InseeBanEndpointTest class file and find the client that is used.

If you have that much memory however, you can bypass the GzipHttpEndpoint and all of the X-Php-Download-File and X-Request-Uri shenanigans altogether.

License

• The code is under MIT (See license file).

• The data is under Open License (English / Français)