Skip to content

Documentation de l'API

Théophile Merlière edited this page Dec 1, 2022 · 14 revisions

Objectif

Cette API a pour vocation de permettre la gestion de bases d'adresses à l'échelon local à travers l'outil Mes Adresses, habituellement au niveau commune ou intercommunalité.

Fonctionnement général

Tout d’abord, l'utilisateur crée une Base Adresse Locale Communale (BALC). La commune est désormais obligatoire à la création.

La BALC est un fichier contenant toutes les adresses d'une unique commune, structuré au format Base Adresse Locale (BAL) (1.2 ou 1.3). Ce fichier peut aussi être importé.

Ensuite, il peut gérer les voies (et toponymes), les numéros et les positions associées.

Règles de relations

  • Une base locale ne peut avoir qu'une seule commune
  • Une commune a plusieurs voies
  • Une voie est associée à une seule commune.
  • Une voie a plusieurs numéros (sauf les voies-toponymes)
  • Un numéro est associé à une seule voie.
  • Un numéro peut avoir plusieurs positions.
  • Une position est associée à un seul numéro ou à une seule voie (dans le cas d'une voie-toponyme).
  • Une parcelle est associée à une ou plusieurs adresses.
  • Une base locale peut être publiée, ou exportée au format BAL/AITF 1.3.

Contrôle d'accès

Le créateur d'une base locale devient l'administrateur de cette base. Un jeton de sécurité lui est alors fourni.

Ce jeton est lié à la base locale, et peut-être renouvelé sur demande de tout utilisateur disposant du jeton.

Si le jeton est perdu, un nouveau peut être envoyé par email sous réserve de communiquer au moins une adresse email connue.

Le jeton doit être passé à l'API via l'en-tête HTTP Authorization.

Exemple : Authorization: Token f66gdjfehfv66DBD

Points d'accès

/bases-locales

  • POST : Créer une base locale
  • GET : Lister les bases locales ou rechercher parmi les bases locales

/bases-locales/create-demo

  • POST : Créer une base locale de démonstration

/bases-locales/search

  • GET : Retourner les bases locales associées correspondant aux critères de recherche.

Filtres possibles :

  • deleted : Valeur 0 ou 1. Si 1 seule les bases locales supprimées sont renvoyées. Si 0 seules les bases locales non supprimées sont renvoyées.
  • email : Recherche de l'email fourni dans les listes des emails de la base locale
  • commune : Recherche les bases locales ayant le code commune demandé
  • status : Recherche les bases locales ayant le statut demandé

/base-locale/recovery

  • POST : Envoi par courriel les bases locales ainsi que leurs jetons d'administration associés à l’adresse électronique indiquée

/bases-locales/{id}

  • GET : Retourne les informations de la base locale
  • PUT : Modifier la base locale
  • DELETE : Supprimer la base locale

/bases-locales/{id}/transform-to-draft

  • POST : Transforme une base locale de démonstration en brouillon, dans le cas où l’utilisateur souhaiterait conserver une base locale créée en mode démonstration

/bases-locales/{id}/sync/exec

  • POST : Lance la synchronisation de la base locale avec la Base Adresse Nationale grâce à l’API dépôt

/bases-locales/{id}/sync/pause

  • POST : Mets la synchronisation de la base locale en pause grâce à l’API dépôt

/bases-locales/{id}/sync/resume

  • POST : Reprend la synchronisation de la base locale grâce à l’API dépôt

/bases-locales/{id}/token/renew

  • POST : Réinitialisation du jeton de la base locale et envoi du nouveau jeton par courriel

/bases-locales/{id}/upload

  • POST : Créer une base locale depuis un fichier au format Base Adresse Locale (1.2 ou 1.3) importé

/bases-locales/{id}/csv

  • GET : Récupérer la base locale au format CSV

/bases-locales/{id}/batch

  • POST : Modifier les numéros d’une commune par lot

/bases-locales/{id}/populate

  • POST : Préremplir la commune avec des adresses existantes dans la Base Adresse Nationale

/bases-locales/{id}/geojson

  • GET : Retourne toutes les adresses de la commune au format GeoJSON

/bases-locales/{id}/voies

  • POST : Créer une voie dans la commune
  • GET : Lister les voies d'une commune

/bases-locale/{id}/toponymes

  • POST : Ajouter un toponyme
  • GET : Retourne les toponymes d’une base locale

/bases-locales/{id}/parcelles

  • GET : Retourne les parcelles d’une commune

/bases-locale/{id}/numeros/batch

  • POST : Modifier les numéros par lot

/bases-locales/{id}/habilitation

  • GET : Récupère l’habilitation de la base locale depuis l’API dépôt si celle-ci existe
  • POST : Demande d’habilitation à l’API dépôt

/bases-locales/{id}/habilitation/email/send-pin-code

  • POST : Envoi le code de confirmation de demande d’habilitation par email

/bases-locales/{id}/habilitation/email/validate-pin-code

  • POST : Valide le code de confirmation de demande d’habilitation

/voies/{id}

  • GET : Retourner les informations concernant une voie
  • PUT : Modifier une voie
  • DELETE : Supprimer une voie

/voies/{id}/numeros

  • POST : Créer un numéro dans la voie
  • GET : Récupérer les numéros d'une voie

/voies/{id}/batch

  • POST : Modifier les numéros d'une voie par lot

/numeros/{id}

  • GET : Retourner les informations d'un numéro de voie
  • PUT : Modifier un numéro de voie
  • DELETE : Supprimer un numéro de voie

/toponymes/{id}

  • GET : Retourne les informations d’un toponyme
  • POST : Ajouter un toponyme
  • DELETE : Supprimer un toponyme

/toponymes/{id}/numeros

  • GET : Retourner les numéros d’un toponyme

/commune/{codeCommune}

  • GET : Retourne les informations de la commune formatées comme suit :
    • hasCadastre : Booléen permettant de savoir si la commune dispose d’un cadastre numérisé.
    • isCOM : Booléen permettant de savoir si la commune fait partie des Collectivités d’Outre-mer.
    • hasOpenMapTiles: Booléen permettant de savoir si la commune est couverte par le fond de carte vectorielle
    • hasOrtho: Booléen permettant de savoir si la commune est couverte par le fond de carte photographie aérienne
    • hasPlanIGN: Booléen permettant de savoir si la commune est couverte par le fond de carte Plan IGN

/stats

  • GET : Retourne les statistiques nationales de publication des Bases Adresses Locales

/stats/departements/{codeDepartement}

  • GET : Retourne les statistiques de publication des bases-locales pour un département

/stats/couverture-tiles/{z}/{x}/{y}.pbf

  • GET : Retourne les tuiles vectorielles des coordonnées demandées

Modèles

Champs communs

Attributs Éditable Commentaire
_id Identifiant unique de l'objet
_created Date de création de l'objet
_updated Date de mise à jour de l'objet

Base locale

Attributs Éditable Commentaire
nom Nom de la Base Adresse Locale
emails Tableau devant toujours contenir au moins une valeur
token Généré par l'application. Renouvelable via URL dédiée. (protégé)
commune Renseigné lors de la création de la Base Adresse Locale.
status Statut indiquant l’état de la base locale (demo, draft, ready-to-publish, published)

Voie

Attributs Éditable Commentaire
nom Nom de la voie
nomAlt Nom(s) de la voie en langue(s) régionale(s)
code Code FANTOIR ou séquence libre (= null pour le moment)
commune Référence
numeros ⚠️ Éditable via routes spécifiques
typeNumerotation numerique ou metrique
trace Line GeoJSON. Champ optionnel
_bal Référence

Toponyme

Attributs Éditable Commentaire
nom Nom du toponyme
nomAlt Nom(s) du toponyme en langue(s) régionale(s)
positions Tableaux des positions du toponyme
parcelles Tableaux des parcelles du toponyme
commune Référence
_bal Référence

Numéro

Attributs Éditable Commentaire
commune Référence
voie Référence (modification = déplacer le numéro dans une autre voie de la commune)
numero 9 (Integer)
suffixe bis
numeroComplet 9 + bis => 9bis
comment Complément pour l’édition des adresses (optionnel et protégé)
parcelles Liste des parcelles du numéro
positions Liste des positions du numéro
certifie Booléen qui précise si l’adresse est certifié par la commune (cf: Certification des adresses)
_bal Référence

Position

Attributs Éditable Commentaire
point Point GeoJSON
source Texte libre (optionnel)
type entrée, délivrance postale, bâtiment, cage d'escalier, logement, parcelle, segment, service technique

Publication d'une base locale

Demander une habilitation en passant par FranceConnect Élu ou en utilisant l’adresse de la commune (données DILA).

Après avoir récupéré votre habilitation, vous pouvez publier votre base locale. Celle-ci sera envoyée vers l’api-dépôt et publiée dans la Base Adresse Nationale.