Skip to content

Documentation

Jump to bottom
Obliv edited this page Apr 10, 2024 · 8 revisions

Contexte

Un Base Adresse Locale est un fichier structuré contenant toutes les adresses d'un territoire.

Ce territoire peut être communal ou supra-communal (EPCI, département, région), tant que l'acteur de référence (la commune) est au centre du dispositif de mise à jour.

La création et la mise à jour d'une Base Adresse Locale est le mode d'alimentation privilégié de la Base Adresse Nationale.

Ces opérations peuvent être réalisées via (le cas échéant) :

  • un logiciel dont s'est équipé la commune ;
  • un logiciel mis à disposition par un chef de file territorial (EPCI, département, région) ;
  • le logiciel mis à disposition par l'État (mes-adresses.data.gouv.fr) ;
  • un outil dédié du système d'information du territoire concerné (cas des métropoles ou communautés urbaines).

Techniquement, l'alimentation de la Base Adresse Nationale avec une Base Adresse Locale se fait selon deux modes :

  • par référencement ou dépôt d'un fichier BAL sur data.gouv.fr (lien vers procédure) ;
  • par soumission d'une BAL de périmètre communale via une API dédiée.

Le présent document explicite les modalités de fonctionnement de cette deuxième approche.

Intérêt d'une API "push" spécialisée

L'approche "pull" historique, qui correspond au référencement ou au dépot d'un fichier sur data.gouv.fr, fonctionne, et est très simple à mettre en oeuvre. Elle a néanmoins plusieurs inconvénients :

  • elle encourage une organisation pyramidale qui dé-responsabilise les communes ;
  • pour être efficace, elle implique une disponibilité et des performances minimales pour le serveur qui héberge le fichier (objectif malheureusement rarement atteint), sauf dans le cas d'un dépôt sur data.gouv.fr ;
  • elle n'offre aucune garantie de prise en compte immédiate des données, puisque les traitements d'incorporation sont exécutés a posteriori, sous réserve de validité du fichier et de l'absence d'erreurs bloquantes.

L'approche "push" vient donc répondre à ces problématiques, mais ne se destine qu'à des éditeurs/intégrateurs de solutions.

Elle permet notamment :

  • de renforcer la rôle des communes, en imposant un dépôt à la maille communale ;
  • de permettre un fonctionnement déconnecté, sans nécessité de disposer d'un serveur du côté du soumissionnaire (les problématiques de performances sont déportées sur adresse.data.gouv.fr) ;
  • de garantir la prise en compte immédiate ou non des adresses soumises, et de disposer d'un rapport d'erreur
  • d'atteindre des performances élevées pour les projets sur de grands territoires composés de nombreuses communes puisqu'il n'est plus nécessaire de traiter le fichier territorial en entier, mais juste la commune concernée.

Cette nouvelle architecture permet aussi une meilleure traçabilité des dépôts, des changements, et une historisation.

Si le dépôt est organisé, la commune reste bien gestionnaire de ses adresses.

Par ailleurs, il sera toujours possible de fonctionner en mode "pull".

Concepts généraux

Une Base Adresse Locale Communale (BALC) est un fichier contenant toutes les adresses d'une unique commune, structuré au format Base Adresse Locale (BAL) (1.2 ou 1.3).

Un client de l'API est un dispositif logiciel ayant vocation à déposer une nouvelle version de Base Adresse Locale Communale (BALC).

Un périmètre d'intervention est une liste de communes sur lequel un client de l'API est habilité à intervenir. Il pourra éventuellement être exprimé sous forme de liste d'EPCI ou de départements.

Habilitation

Chaque client de l'API peut demander une habilitation à déposer des BALC sur un périmètre donné.

Il devra pour cela produire un justificatif indiquant qu'il a été missionné par les communes ou leur représentant pour intervenir sur ce territoire.

Il devra notamment justifier d'un commanditaire responsable et de la mise en place d'un système d'authentification permettant à la commune d'exercer sa compétence sans usurpation.

Une charte de bonne conduite est à l'étude, et son non-respect pourra mener à une suspension temporaire de l'habilitation. Des garanties en terme de sécurité pourront être exigées à l'avenir.

Labellisation et visibilité

Une solution logicielle techniquement raccordée à cette API, qui respecte les chartes et référentiels en vigueur pourra bénéficier d'une labellisation et l'utiliser comme argument de vente.

La solution pourra par ailleurs être référencée sur le site adresse.data.gouv.fr dans une rubrique dédiée.

Documentation technique

Principe général

La mise à jour des adresses d'une commune est réalisée par le dépôt d'une nouvelle BALC qui écrase l'ancienne. Dans l'API, cette opération est appelée revision.

Chaque commune dispose de 0 ou plusieurs revisions qui ont été publiées par différents clients habilités sur son territoire.

La création d'une revision suit le processus suivant :

  • Étape 1 : création de la revision avec contexte d'authentification
  • Étape 2 : téléversement du fichier au format BAL 1.2 ou 1.3
  • Étape 3 : validation
  • Étape 4 : soumission finale de la revision et prise en compte effective de la BALC

4 requêtes HTTP successives sont nécessaires pour réaliser le processus en entier.

Lorsqu'une revision est effectivement prise en compte, toutes les revisions en attente de la même commune reviennent à l'étape 3.

Une revision en attente depuis plus de 24h est supprimée et purgée.

Authentification

Les opérations de dépôt proposées cette API sont protégées et nécessitent une authentification et une traçabilité maximale.

Puisque l'authentification de l'utilisateur est déléguée au client de l'API, il est de la responsabilité du client de l'API de fournir un contexte lors de la publication d'une BALC.

Chaque client de l'API dispose d'un jeton permanent, qui pourra être renouvelé à la demande. Il doit être conservé de façon sécurisée.

Étape 1 : création d'une revision

Lors de la création d'une revision, le contexte utilisateur doit être renseigné. Il est composé de 3 champs optionnels (nom de la personne nomComplet qui effectue le dépôt, nom de l'organisation organisation, champs libre clé/valeur extras).

Il est demandé de renseigner les champs nomComplet et organisation au maximum des possibilités du client de l'API, en fonction de sa stratégie d'authentification.

Le champ extras peut être utilisé pour stocker des identifiants internes au client, ou des données additionnelles actuellement non supportées par l'API mais jugées utiles par l'éditeur. Attention ces champs sont publics.

Requête :

POST  /communes/27115/revisions

# Header
Authorization: Token xxxxxxxxxxxxxxxxx
Content-Type: application/json

# Body
{
  "context": {
    "nomComplet": "John Doe", // Optionnel
    "organisation": "Mairie de Breux-sur-Avre", // Optionnel
    "extras": {
      "internal_id": "9990"
    } // Optionnel
  }
}

Réponse :

201 Created

# Header
Content-Type: application/json

# Body
{
  "_id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "John Doe"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {},
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "pending",
  "ready": false,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

Étape 2 : téléversement du fichier BAL

Requête :

PUT /revisions/507f191e810c19729de860ea/files/bal

# Header
Authorization: Token xxxxxxxxxxxxxxxxx
Content-Type: text/csv
Content-Length: 2133 # Optionnel mais recommandé
Content-MD5: 1234567890abcdedf1234567890abcdedf # Optionnel mais recommandé

# Body
@@@ fichier BALC @@@ # Taille max : 50mb

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "_id": "507f199710c19729de860ea", # Identifiant du fichier
  "revisionId": "507f191e810c19729de860ea", # Identifiant de révision
  "type": "bal",
  "size": 2133,
  "hash": "51ca0bce566423b6c5a321e911438c57195adf747d066e0dd4b212d43c0f4c6e", # SHA-256
  "createdAt": "2020-01-01T00:00:00Z"
}

Étape 3 : validation

Une fois le fichier soumis, il faut indiquer à l'API que tout est prêt. Cela déclenche alors la validation des données.

La validation d'une BALC via l'API diffère légèrement de ce qui est proposé sur adresse.data.gouv.fr pour les BAL. En effet un seul code commune est autorisé, celui pour lequel la revision a été créée.

De façon générale, les erreurs qui avaient pour conséquence le rejet de la ligne pour le validateur BAL font désormais échouer la validation.

Quelques règles renforcées qui provoquent le rejet du fichier :

  • une incohérence entre le numéro dans la clé d'interopérabilité et la colonne numéro ;
  • une date invalide ;
  • des coordonnées latitude/longitude invalides ;
  • un type de position invalide ;
  • un numéro ou un suffixe invalide ;
  • un libellé de voie invalide ;
  • une clé d'interopérabilité structurellement invalide (elle peut néanmoins être absente, ou son champ voie rempli à nul 0000-xxxx)

Requête :

POST  /revisions/507f191e810c19729de860ea/compute

# Header
Authorization: Token xxxxxxxxxxxxxxxxx

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "_id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "John Doe"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "pending",
  "ready": true,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

Si les données soumises ne sont pas valides, la valeur ready reste à false et validation.valid est false.

Étape 4 : publication de la nouvelle BAL

Lorsque qu'une revision est publiable (ready: true), elle peut être publiée.

Requête :

POST  /revisions/507f191e810c19729de860ea/publish

# Header
Authorization: Token xxxxxxxxxxxxxxxxx

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "_id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "John Doe"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "published",
  "current": true, # Indique si la BALC est celle actuellement en production
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": "2020-01-01T01:00:00Z"
}

Routes en accès libre

Lister les révisions publiées d'une commune donnée

GET /communes/27115/revisions

Accéder à une révision donnée

GET /revisions/507f191e810c19729de860ea

Accéder à la révision courante d'une commune donnée

GET /communes/27115/current-revision

Télécharger le fichier BAL d'une révision courante

GET /communes/27115/current-revision/files/bal/download

En-têtes pour l'envoi d'une BALC

Contrôle d'intégrité

Pour vérifier l'intégrité du fichier soumis, au moins un en-tête de contrôle doit être fourni.

Nom de l'en-tête Exemple de valeur Description
Content-Length 3126 Longueur en octet du fichier soumis
Content-MD5 1234567890abcdedf1234567890abcdedf Signature MD5 du fichier soumis
X-Rows-Count 510 Nombre de lignes de données du fichier CSV soumis

NB : Si le fichier est fourni compressé (en-tête Content-Encoding présent) les éventuels en-têtes Content-Length et Content-MD5 devront correspondre au fichier compressé et non au fichier brut. Dans ce cas il est recommandé de fournir aussi l'en-tête X-Rows-Count.

Documentation spécifique à un ETL

Paramétrage de l'API BAL pour FME

Clone this wiki locally