Skip to content

3‐ DRAFT # API BAN Plateforme

Jump to bottom
Frederique WILLIAMS edited this page Sep 12, 2025 · 1 revision

BAN-Platform // Specification d'API (DRAFT)

Documentation technique

Vue rapide des routes disponibles

Les routes sont accessibles avec la même url de base https://plateforme.adresse.data.gouv.fr/api

/ban-id

  • GET /ban-id

/address

  • GET /address/{addressID}
  • POST /address/get (DRAFT - Implémentation a l'étude)
  • POST /address (token needed)
  • PUT /address (token needed)
  • DELETE /address/{addressID} (token needed)
  • POST /address/delete (token needed)
  • POST /address/delta-report

/common-toponym

  • GET /common-toponym/{commonToponymID}
  • POST /common-toponym (token needed)
  • PUT /common-toponym (token needed)
  • DELETE /common-toponym/{commonToponymID} (token needed)
  • POST /common-toponym/delete (token needed)
  • POST /common-toponym/delta-report

/district

  • GET /district/{districtID}
  • POST /district (token needed)
  • PUT /district (token needed)
  • DELETE /district/{districtID} (token needed)
  • GET /district/cog/{codeInsee}

/job-status

  • GET /job-status/{idJob}

Définition des types génériques

En plus des TYPEs habituels (STR, INT, ARR(), JSON) vous pouvez rencontrer dans cette documentation des TYPEs plus atypiques ou spécifiques à l'API :

  • INT_TIMESTAMP : Timestamp valide
  • TYPE_ban_id : Type générique - Identifiant
    • TYPE_ban_id_address : TYPE_ban_id d'Adresse
    • TYPE_ban_id_common_toponym : TYPE_ban_id de Toponyme Commun
    • TYPE_ban_id_district : TYPE_ban_id de Découpage Administratif
  • TYPE_json_ban : Type générique - Représentation d'un objet de données au format JSON
    • TYPE_json_ban_district : TYPE_json_ban d'un objet représentant un Découpage Administratif
{
    "date": "2023-05-05T12:58:33.871Z",
    "status": "success",
    "response": {
        "id": "00000000-0000-4fff-9fff-00000000000a",
        "labels": [{
            "isoCode": "fra",
            "value": "Commune A"
        }],
        "updateDate": "2023-06-22",
        "meta": {
            "insee": {
              "cog": "12345"
        }
    }
}
  • TYPE_json_ban_common_toponym : TYPE_json_ban d'un objet représentant un Toponyme Commun
// TYPE_json_ban_common_toponym :
{
    "date": "2023-05-05T12:58:33.871Z",
    "status": "success",
    "response": {
        "id": "00000000-0000-4fff-9fff-00000000001a",
        "districtID": "00000000-0000-4fff-9fff-00000000003a",
        "labels": [{
            "isoCode": "fra",
            "value": "Rue de la baleine"
        }],
        "geometry": {
            "type": "Point",
            "coordinates": [1.2345, 2.3456]
        },
        "updateDate": "2023-04-24"
    }
}
  • TYPE_json_ban_address : TYPE_json_ban d'un objet représentant une adresse
// TYPE_json_ban_address :
{
    "date": "2023-05-05T12:56:40.644Z",
    "status": "success",
    "response": {
        "id": "00000000-0000-4fff-9fff-00000000000a",
        "mainCommonToponymID": '00000000-0000-4fff-9fff-00000000001a',
        "secondaryCommonToponymIDs": ["00000000-0000-4fff-9fff-00000000002a"],
        "districtID": "00000000-0000-4fff-9fff-00000000003a",
        "number": 1,
        "positions": [{
            "type": "entrance",
            "geometry": {
              "type": "Point",
              "coordinates": [1.23, 2.34]
          }
        }],
        "updateDate": "2023-04-12"
    }
}
  • TYPE_csv_bal : Représentation d'une ligne de données au format CSV, tel que décrit dans la spécification BAL
    • TYPE_csv_bal_address : Représentation d'une adresse au format CSV, tel que décrit dans la spécification BAL (Base Adresse Locale)
  • TYPE_ban_status_id : ID de status valide
  • TYPE_status_report : Représentation JSON de l'état d'une demande asynchrone.
// TYPE_status_report :
{
  status: ENUM('pending', 'success', 'error'),
  count : INT,
  type : ENUM('insert', 'edit', 'delete'),
  failed ?: { count : INT, listing : ARR(ban_id) },
  successed ?: { count : INT, listing : ARR(ban_id) },
  details ?: ARR(TYPE_status_task_report)
}
  • TYPE_status_task_report : Représentation JSON de l'état d'une tâche inclus dans une demande asynchrone.
// TYPE_status_task_report :
{
  id : TYPE_ban_id,
  type : ENUM('insert', 'edit', 'delete'),
  status : ENUM('success', 'error'),
  message ?: STR,
  ids ?: ARR(TYPE_ban_id),
  value ?: TYPE_json_ban_address,
  oldValue ?: TYPE_json_ban_address,
}

Authentification

Dans certains cas, l'appel à une route spécifique de l'API peut nécessiter l'usage d'un token d'identification. Ce besoin est alors indiqué dans la documentation pour chacune des routes concernées.

Ce token sera fourni par l'En-Tête HTTP lors de l'appel.

En-Tête a définir

Format de réponse

Les réponses de l'API sont de type JSON. Le Header Content-Type dispose de la valeur JSON et sont corp (body) respecte le format suivant :

{
  date : INT_TIMESTAMP,
  status : ENUM(success, error),
  message ?: STR,
  response ?: VALUE_API_RESPONSE
 }

La valeur VALUE_API_RESPONSE correspond au contenu de la réponse, tel qu'indiqué ci-dessous, dans la documentation de chaque API.

Liste des codes retours et erreurs

Code Statut Message
200 OK undefined
400 Bad request Erreur dans la demande.
Message à préciser pour chaque route:
- Missing required parameter [{paramName…}] (Fr Paramètre requis non renseigné
[{paramName…}])
- Invalid ID (Fr - Identifiant invalide)
- Not available ID (Fr - Identifiant non disponible)
401 Unauthorized Authentication token not provided (Fr - Jeton d'authentification non fourni)
403 Forbidden Authentication token not authorized to access resource (Fr - Jeton d'authentification non autorisé à accéder à la ressource)
404 Not Found Data not found (Fr - Donnée introuvable)

Description des routes de l'API

Tout appel vers une route de l'API retourne un code de statut. En cas d'erreur, la réponse contiendra également un code d'erreur dans le but de faciliter l'identification de cette dernière.

Route API utilitaire

GET : /ban-id

Extrait une liste de d'identifiants disponibles.

Attribut type Commentaire
quantity TYPE_ban_id_address Default = 1 (Max 100000)

Retourne une liste de d'identifiants au format TYPE_ban_id. Note : Les Identifiants retournés sont disponibles au moment de la requête mais ne sont pas réservés. Cependant, l'usage de l'algorithme UUID-V4 pour produire ces identifiants suffit à assurer un risque de collision quasi-nul.

Route API de l'adresse : /address

GET : /address/{addressID}

Extrait une Adresse.

  • Paramètre attendu :
Attribut type Commentaire
addressID TYPE_ban_id_address Required
  • Réponse : Renvoie un objet adresse au format TYPE_json_address.

POST : /address/get (DRAFT - Implémentation a l'étude)

Extrait une liste d'adresses.

  • Paramètre attendu :
Attribut type Commentaire
ids ARR(TYPE_ban_id_address) Required
  • Réponse : Renvoie un tableau d'objet adresses au format TYPE_json_address dans l'ordre des IDs fournis en entrée.

POST : /address

⚠ Identification requise

Publication asynchrone d'une liste d'Adresses.

  • Paramètre attendu :
Attribut type Commentaire
addresses ARR(TYPE_json_ban_address) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

PUT : /address

⚠ Identification requise

Édition asynchrone d'une liste d'Adresses.

  • Paramètre attendu :
Attribut type Commentaire
addresses ARR(TYPE_json_address) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

DELETE : /address/{addressID}

⚠ Identification requise

Suppression d'une Adresse.

  • Paramètre attendu :
Attribut type Commentaire
addressID TYPE_ban_id_address Required
  • Réponse : Envoie un rapport d'état au format TYPE_status_report.

POST : /address/delete

⚠ Identification requise

Suppression asynchrone d'un ensemble d'Adresses.

  • Paramètre attendu :
Attribut type Commentaire
addressIDs ARR(TYPE_ban_id_address) Required
  • Réponse : Envoie un ID de status statusID au format TYPE_ban_status_id.

POST: /address/delta-report

⚠ Identification requise

Extraction d'un rapport d'adresse à créer, modifier, supprimer à partir d'une liste d'adresses.

  • Paramètres attendus :
Attribut type Commentaire
addressIDs ARR(TYPE_ban_id_address) Required
districtID TYPE_ban_id_district Required

Route API des Toponymes Communs : /common-toponym

GET: /common-toponym/{commonToponymID}

Extrait un Toponyme Commun

  • Paramètre attendu :
Attribut type Commentaire
commonToponymID TYPE_ban_id_common_toponym Required
  • Réponse : Renvoie un objet CommonToponym au format TYPE_json_ban_common_toponym.

POST: /common-toponym

⚠ Identification requise

Publication asynchrone d'une liste de Toponymes Communs.

  • Paramètre attendu :
Attribut type Commentaire
commonToponyms ARR(TYPE_json_ban_common_toponym) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

PUT: /common-toponym

⚠ Identification requise

Édition asynchrone d'une liste de Toponymes Communs.

  • Paramètre attendu :
Attribut type Commentaire
commonToponyms ARR(TYPE_json_address) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

DELETE: /common-toponym/{commonToponymID}

⚠ Identification requise

Suppression d'un Toponyme Commun.

  • Paramètre attendu :
Attribut type Commentaire
commonToponymID TYPE_ban_id_common_toponyme Required
  • Réponse : Envoie un rapport d'état au format TYPE_status_report.

POST: /common-toponym/delete

⚠ Identification requise

Suppression asynchrone d'un ensemble de Toponymes Communs.

  • Paramètre attendu :
Attribut type Commentaire
commonToponymIDs ARR(TYPE_ban_id_common_toponym) Required
  • Réponse : Envoie un ID de status statusID au format TYPE_ban_status_id.

POST: /common-toponym/delta-report

⚠ Identification requise

Extraction d'un rapport d'adresses à créer, modifier, supprimer à partir d'une liste d'adresse.

Attribut type Commentaire
commonToponymIDs ARR(TYPE_ban_id_common_toponym) Required
districtID TYPE_ban_id_district Required

Route API des Divisions Administratives : /district

GET: /district/{districtID}

Extrait une Division Administrative.

  • Paramètre attendu :
Attribut type Commentaire
districtID TYPE_ban_id_district Required
  • Réponse : Renvois un objet District au format TYPE_json_ban_district.

POST: /district

⚠ Identification requise

Publication asynchrone d'une liste de Divisions Administratives.

  • Paramètre attendu :
Attribut type Commentaire
districts ARR(TYPE_json_ban_district) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

PUT: /district

⚠ Identification requise

Édition asynchrone d'une liste de Divisions Administratives.

  • Paramètre attendu :
Attribut type Commentaire
districts ARR(TYPE_json_ban_district) Required
  • Réponse : Envoie un ID de status (statusID) au format TYPE_ban_status_id.

DELETE: /district/{districtID}

⚠ Identification requise

Suppression d'une Division Administrative.

  • Paramètre attendu :
Attribut type Commentaire
districtID TYPE_ban_id_district Required
  • Réponse : Envoie un rapport d'état au format TYPE_status_report.

GET: /district/cog/{codeInsee}

Permet de récupérer l'uuid V4 de la commune.

  • Paramètre attendu :
Attribut type Commentaire
codeInsee INT Required
  • Réponse : Envoie les informations du district pour le code INSEE fourni, dont l'uuid v4.

Route API des état de demandes asynchrones : /job-status

GET: /job-status/{idJob}

Extrait l'état d'une demande asynchrone.

  • Paramètre attendu :
Attribut type Commentaire
idJob TYPE_ban_status_id Required
  • Réponse : Renvoie un objet représentant l'état d'une demande asynchrone au format TYPE_status_report.

adresse.data.gouv.fr : Le site national des adresses
Référencer l’intégralité des adresses du territoire et les rendre utilisables par tous.

Clone this wiki locally