Skip to content

Documentation utilisateur de l'API de gestion

ebuard edited this page Apr 9, 2019 · 30 revisions

Remarque préalable : tous les exemples donnés sur cette page sont sur des identifiants/objets fictifs et ne sont pas rejouable à l'identique.

Généralités sur l'API de gestion BAN

L'url de l'api de gestion de production est https://api-ban.ign.fr/. Celle en qualif est: https://qlf-ban.ign.fr/.

L'API de gestion de la BAN permet de lire / créer / modifier les objets de la Base Adresse Nationale. Les différentes ressources disponibles sont décrites sur la page ressources de l'API. Celles-ci sont soit des municipalities (communes), des postcodes (codes postaux), des groupes (voies/lieux-dits), des housenumbers (numéros dans une voie/lieu-dit) ou des positions (géométries ponctuelles du numéro).

L'API de gestion de la BAN est une API REST, dont l'utilisation est soumise à des CGU ou une charte d'expérimentation pendant la période de test. Un token est nécessaire pour accéder à l'API. La procédure de demande et d'utilisation du token est décrite dans le prochain chapitre.

L'API permet d'envoyer des requêtes de différents types, détaillées dans les chapitres suivants :

  • GET pour lire les ressources
  • POST pour créer une ressources
  • PUT / PATCH pour modifier complètement ou partiellement une ressource
  • DELETE pour marquer une ressource comme étant détruite (soft-delete)

Une route diff permet d'obtenir un différentiel sur les dernières actions de création/modification d'objets.

Les différentes versions successives d'un même objet de la BAN sont conservées en base et accessibles via l'API.

Il est aussi possible de valider une version d'un objet en lui mettant un flag.

En retour de ces différents requêtes, on obtient un code http et un ou n objets de la BAN en json (cf retour API). Les routes sont décrites ici: https://api-ban.ign.fr/openapi ou https://qlf-ban.ign.fr/openapi

Obtenir et utiliser un token

Pour pouvoir utiliser l'API, il faut disposer d'un token, dérivé d'un client_id et d'un client_secret.

Le client_id et le client_secret sont créés et fournis par le gestionnaire de la ban. Ils sont nominatifs et associés au client. Le gestionnaire configure aussi le profil du client qui contient notamment les droits de l'utilisateur sur les ressources de la BAN (lecture/écriture/modification/suppression).

A partir du client_id et du client_secret, l'utilisateur obtient un token qui est valable 1 h. Passé cette période, il doit le redemander. Voici la procédure pour obtenir le token : Faire une requête POST avec :

Champs Clé Valeur
Header Content-Type application/x-www-form-urlencoded
Body client_id <xxxxx.....>
Body client_secret <yyyy.....>
Body grant_type client_credentials
Body email l'email du client
Body contributor_type type de contributeur

Le contributor_type peut prendre les valeurs suivantes : ign, laposte, dgfip, osm, sdis, municipal_administration

En retour on obtient un json avec le token, comme :

{
  "token_type": "Bearer",
  "client": "10",
  "client_id": " b19c1de0-ac9e-40f9-......",
  **"access_token": " 7ecvlc05xqF0gWBp2gTd9mzTClyj.."**,
  "email": "xxx@yyy",
  "scope": "contrib",
  "client_secret": "LOwMlTlvER5ZBw95ChLeNxfb....",
  "expires_in": 3600,
  "grant_type": "client_credentials" 
}

Ensuite le token est à placer dans le header des requêtes http de la façon suivante (Exemple donné pour le token "xxx"):

  • Champ "Authorization"
  • Valeur "Bearer xxx"

Description des retours de l'API

En retour d'une requête de l'API, on obtient :

  • un code http indiquant si la requête s'est correctement déroulée ou non :

    • 200 (Ok : GET, PUT et PATCH)
    • 201 (Ok : POST)
    • 204 NO CONTENT (Ok mais pas d'information à renvoyer, notamment pour une requête DELETE)
    • 302 (Echec : GET, PUT et PATCH si l'identifiant de l'objet n'existe plus)
    • 400 (Echec : requête non conforme)
    • 401 (Echec : pas autorisé)
    • 404 (Echec : la ressource demandée n'existe pas)
    • 409 (Echec : conflit lors de la modification de la ressource)
    • 410 GONE (Echec : le fichier demandé n'existe pas)
    • 422 (Echec : la ressource à créer n'est pas conforme)
  • les objets en json (cf ressources de l'API pour une description des différents champs de chaque ressource)

--soit une collection d'objets : (exemple pour https://api-ban.ign.fr/municipality )

	{
	"total": 36703
	"next": "https://api-ban.ign.fr/municipality/?offset=20"
	"collection": [20]
	- 0:  {
		"name": "L'Abergement-Clémenciat"
		"attributes": {
			"source": "INSEE/COG (2015)"
		}
		"resource": "municipality"
		"alias": null
		"version": 1
		"insee": "01001"
		"id": "ban-municipality-65e742d51c534d49a45fd7cdf7425572"
		"siren": null
		}
	- 1:  {
		"name": "L'Abergement-de-Varey"
		"attributes": {
		"source": "INSEE/COG (2015)"
		}-
		"resource": "municipality"
		"alias": null
		"version": 1
		"insee": "01002"
		"id": "ban-municipality-8592a977f5be4e789bd46a4b80f04a1a"
		"siren": null
		}
	...
	}

-- soit un objet : (exemple pour https://api-ban.ign.fr/municipality/ban-municipality-11e80cc7e7d44e478cf5abad72b6a511)

	{
	"created_by": {...}-
	"alias": null
	"version": 1
	"insee": "01001"
	"id": "ban-municipality-65e742d51c534d49a45fd7cdf7425572"
	"siren": null
	"postcodes": [1]
		0:  "ban-postcode-0ac5ba1392904d379afc36c6a6c52778"
	"modified_at": "2016-10-18T17:07:54.813421+00:00"
	"name": "L'Abergement-Clémenciat"
	"attributes": {
		"source": "INSEE/COG (2015)" 
	}
	"modified_by": {...}
	"created_at": "2016-10-18T17:07:54.813421+00:00"
	}

Description des requêtes GET

Ces requêtes permettent de lire un ou n objets de la BAN.

Remarques préalables:

  • devant chaque requête, il faut ajouter l'url du serveur ban. Dans les exemples, https://api-ban.ign.fr
  • les ressources ({ressource}) sont à choisir parmi (municipality, postcode, group, housenumber, position)

GET de collections d'objets

/{ressource} : renvoie les 20 premiers objets de la {ressource} (municipality, postcode, group, housenumber, position)

https://api-ban.ign.fr/municipality

/{ressource}?limit={n}&offset={m} : renvoie n objets de la {ressource}. Si {m} vaut 0, renvoie les n premiers objets. Autrement les n premiers objets à partir du {m} ième objets (tri sur les identifiants)

https://api-ban.ign.fr/municipality?limit=5

/{ressource}?fields={field} : renvoie les attributs {field} des 20 premiers objets {ressource}

https://api-ban.ign.fr/municipality?fields=insee,name

& : ajoute une condition

https://api-ban.ign.fr/municipality?fields=insee&limit=5

/housenumber?west={lon1}&south={lat1}&east={lon2}&north={lat2} : renvoie les 20 premiers housenumbers dans la boîte englobante (lon1, lat1, lon2, lat2 en WGS84). On peut obtenir plus d'objets en jouant sur le paramètre limit.

https://api-ban.ign.fr/housenumber?west=-0.24&south=44.90&east=-0.22&north=44.91

GET d'un objet

/{ressource}/{id} : renvoie l'objet de la {ressource} ayant l'identifiant {id}

https://api-ban.ign.fr/municipality/ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1

/{ressource}/{champ}:{valeur} : renvoie l'object de la {ressource} ayant l'attribut {champ}={valeur}. Ne fonctionne que si le {champ} est un identifiant.

https://api-ban.ign.fr/municipality/insee:24335

Affichage des objets liés

Par défaut, le get standard ne récupère que les identifiants des objets liés :

https://api-ban.ign.fr/group/ban-group-143510aa44704d0f93c0b22464bf51a3

{
	"fantoir": "060070620"
	"kind": "way"
	"name": "Voie Communale Degrés Soubran"
	"id": "ban-group-143510aa44704d0f93c0b22464bf51a3"
	...
	"municipality": "ban-municipality-822dace1b7b84b78b66ee734dee52e0d"
}

Il est possible d'afficher les objets liés en ajoutant fields=*.* aux requêtes. Ceci est valable aussi bien pour les GET renvoyant des collections d'objets que pour les GET renvoyant un seul objet. On peut aussi afficher les objets liés aux objets liés avec le paramètre fields=*.*.* ...

Quelques exemples:

/{ressource}?fields=*.* : renvoie les 20 premiers objets de la {ressource} ainsi que les objets liés directement à chaque objet.

/{ressource}/{id}?fields=*.* : renvoie l'objet de la {ressource} ayant l'identifiant {id} ainsi que les objets liés directement à cet objet.

https://api-ban.ign.fr/group/ban-group-143510aa44704d0f93c0b22464bf51a3?fields=*.*

{
	"fantoir": "060070620"
	"kind": "way"
	"name": "Voie Communale Degrés Soubran"
	"id": "ban-group-143510aa44704d0f93c0b22464bf51a3"
	"municipality": {
		-"created_by": {...}
		"alias": null
		"version": 1
		"insee": "06007"
		"id": "ban-municipality-822dace1b7b84b78b66ee734dee52e0d"
		"siren": null
		"postcodes": [1]
			- 0:  "ban-postcode-ed97a575246041c09d75c7c02f56a7a2"
		
		"modified_at": "2016-10-18T17:08:06.802463+00:00"
		"name": "Auribeau-sur-Siagne"
		-"attributes": {...}
		-"modified_by": {...}
		"created_at": "2016-10-18T17:08:06.802463+00:00"
		}
}

GET sur les objets liés

Ces requêtes permettent d'obtenir les enfants à partir de leur parent :

/group?municipality={champ}:{valeur} : renvoie les groups liés à la municipality ayant le {champ}={valeur}

https://api-ban.ign.fr/group?municipality=id:ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1

https://api-ban.ign.fr/group?municipality=insee:24335

/postcode?municipality={champ}:{valeur} : renvoie les postcodes liés à la municipality ayant le {champ}={valeur}

/housenumber?postcode={champ}:{valeur} : renvoie les housenumbers liés au postcode ayant le {champ}={valeur}

/housenumber?group={champ}:{valeur} : renvoie les housenumbers liés au group ayant le {champ}={valeur}

/housenumber?parent={id} : renvoie les housenumbers ayant pour groupe principal le groupe d'identifiant {id} (relation parent)

https://api-ban.ign.fr/housenumber?parent=ban-group-83b206e1b4da4f4ca5778ee30fe0dead

/housenumber?ancestors={id} : renvoie les housenumbers ayant pour groupe secondaire le groupe d'identifiant {id} (relation ancestors)

https://api-ban.ign.fr/housenumber?ancestors=ban-group-83b206e1b4da4f4ca5778ee30fe0dead

/position?housenumber={champ}:{valeur} : renvoie les positions liées au housenumber ayant le {champ}={valeur}

GET sur les versions

/{ressource}/{id}/versions : renvoie les versions de l'objet d'identifiant {id} de la {ressource}

https://api-ban.ign.fr/municipality/ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1/versions

/{ressource}/{id}/versions/{version} : renvoie la version {version} de l'objet ayant l'identifiant {id} de la ressource {ressource}

https://api-ban.ign.fr/municipality/ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1/version/1

Description des requêtes POST

/{ressource}: créé un objet de la {ressource}. Le corps de la requête doit contenir les différents champs de l'objet à créer en json: {"champ1":"valeur1","champ2":"valeur2" ... }

Exemple :

https://api-ban.ign.fr/municipality
corps en json : {"insee":"99999","name":"Toto-sur-Seine"}

Les champs suivants sont obligatoires lors des POST :

  • municipality : insee et name
  • postcode : code, name et lien vers la municipality
  • group : name, kind et lien vers la municipality
  • housenumber : parent (lien vers le groupe principal)
  • position : center ou name, kind, positioning, lien vers le house number

D'autres champs peuvent être contraints par des normes et sont recalculés:

  • housenumber: cia (concaténation du code insee (5 char)_ du code rivoli de la voie/lieu-dit (4 char)_ du numéro (char extensibles mais sans 0) _ de l’extension de l'adresse)

Description des requêtes PUT

/{ressource}/{id}: modifie l'objet d'identifiant {id} de la {ressource}. Le corps de la requête doit contenir les différents champs de l'objet à créer : {"champ1":"valeur1","champ2":"valeur2" ... }

L'objet est entièrement remplacé. Les champs obligatoires du POST sont donc nécessaires. Les champs non remplacés contiennent des valeurs null.

Cette requête nécessite aussi de passer un numéro de version. Celui-ci doit correspondre au numéro de version de l'objet sur le serveur ban + 1 . Si ce numéro n'est pas correct, l'api n'effectuera pas la modification et renverra le code 409 (conflit) car la ressource a peut être été modifiée entre temps par un autre utilisateur.

Exemple :

https://api-ban.ign.fr/municipality/ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1
corps en json : {"insee":"99999","name":"Toto-sur-Seine", "version":"2"}

Description des requêtes PATCH

/{ressource}/{id} : met à jour un ou plusieurs champs d'un objet de la BAN (cf PUT pour plus de détails). Les champs non remplacés contiennent leurs anciennes valeurs.

Exemple :

https://api-ban.ign.fr/municipality/ban-municipality-6513dabc72ec472abfbdbc52e5bef2d1
corps en json : {"name":"Toto-sur-Seine", "version":"3"}

Description des requêtes DELETE

/{ressource}/{id} : marque comme détruit l'objet d'identifiant {id} de la ressource {ressource}

On peut réactiver une ressource détruite en faisant un PUT sur cette ressource.

Description des requêtes DIFF

/diff : permet d'obtenir la liste des opérations ayant créées ou modifiées des objets de la ban. Plus exactement, on récupère le type de l'opération, la ressource concernée, un différentiel des anciennes/nouvelles valeurs, l'objet ancien et l'objet nouveau (cf ressources de l'API pour plus de détails).

Les champs résultants de la requête diff:

  • resource : indique la classe modifiée;
  • resource_id : identifiant ban de la resource modifiée;
  • diff contient uniquement les champs modifiés, par exemple pour une suppression, new a un status deleted, et pour une création old a un status null, et ce pour chaque version de l'objet;
  • new contient l’objet après modification;
  • old contient l’objet avant modification;
  • le champ modified_by sur l’objet new permet de savoir quel est l’applicatif qui a fait la modification , par exemple le guichet adresse.

Description des requêtes FLAG

/{ressource}/{id}/versions/{version}/flag : valide ou enlève la validation de la version {version} de l'objet {id}.

Le corps de la requête doit contenir le booléen status qui précise si c'est une validation ou le contraire : {"status": True}

https://api-ban.ign.fr/group/ban-group-a83a45832b1047309ac6dcae8f5585e7/versions/4/flag

Description de la requête BATCH

POST /batch : permet une requête par lots, chaque lot pouvant être un POST, PUT, PATCH ou DELETE

Le corps de la requête doit être un tableau de json ou chaque json est une sous-requête.

Chaque sous requête doit contenir la méthode, le path et le corps de la sous-requête si nécessaire.

Exemple :

POST https://api-ban.ign.fr/batch
corps en json : [{"method":"POST", "path":"/municipality", "body":{"name":"Toto-sur-Seine", "insee":"99999"}},
                     {"method":"DELETE", "path":"/group/ban-group-a83a45832b1047309ac6dcae8f5585e7"}]

Crée la municipality Toto-sur-Seine et détruit le group d'identifiant ban-group-a83a45832b1047309ac6dcae8f5585e7

You can’t perform that action at this time.