Skip to content

DRAFT # Format BAN & Différentiel BAN

Jump to bottom
Nicolas KOKLA edited this page Sep 24, 2024 · 2 revisions

Format BAN & Différentiel BAN

Pré-requis

Public cible :

Cette documentation s'adresse à un public ayant un niveau de compétence technique avancé dans les domaines suivants : programmation logicielle, utilisation d'API et manipulation de données au format JSON.

Éléments dépréciés (DEPRECATED) :

Certains champs des entités décrites dans le format d'échange de données BAN sont préfixés par la chaîne DEPRECATED_. Ce préfixe indique que les données correspondantes sont obsolètes et seront retirées ultérieurement. La maintenance de ces éléments sera assurée selon un calendrier défini par l'équipe de maintenance et communiqué lors des mises à jour du modèle.

⚠ L'utilisation de ces éléments dans un système en production est fortement déconseillée.

Éléments en test (BETA) :

Certains champs des entités décrites dans le format d'échange de données BAN sont préfixés par la chaîne BETA_. Ce préfixe indique que les données correspondantes sont en phase d'essai ou ne sont pas encore finalisées. Ces éléments sont sujets à des changements et à des améliorations basées sur les retours d'expérience.

⚠ Il est recommandé d'éviter l'utilisation de ces éléments dans un environnement de production critique.

Description des types d'objets communs

TYPE_BAN_ID

Le TYPE_BAN_ID est une chaine de caractères respectant le format UUID-v4 (et donc issue de l'algorithme de production de ce format) et représentant un Identifiant BAN. Plus d'information sur le format et la spécification UUID-v4 :

TYPE_LABEL

Le TYPE_LABEL est un tableau d'objet où chacun de ces objet représente une valeur, sous forme de chaine de caractère, dans une langue spécifique. Ces objets possèdent deux champs :

  • value: La chaine de caractère représentant la valeur.
  • isoCode : Chaine de caractère, au format ISO, de la langue du champs valeur.

NOTE: Au cas ou des système d'informations n'utiliseraient qu'une langue unique ne figurant pas dans la liste fournit (autrement dit, "la valeur par défaut"), il est, par convention, recommandé d'exploiter la première valeur de ce tableau.

Exemple de TYPE_LABEL 
[
	{
		"isoCode":  "fra",
		"value":  "Petite rue de l'Esté"
	},
	{
		"isoCode":  "eus",
		"value":  "Esté karrika ttipia"
	}
]

TYPE_GEOMETRY

Le TYPE_GEOMETRY représente les informations géométriques des entités. Il utilise le format GeoJSON standard pour décrire les géométries.

  • type : Spécifie le type de la géométrie. Peut être Point, LineString, Polygon, etc.
  • coordinates : Un tableau contenant les coordonnées géométriques selon le type spécifié.
Exemple de TYPE_GEOMETRY 
{
  "type": "Point",
  "coordinates": [2.294481, 48.858370]
}

TYPE_POSITION

Le TYPE_POSITION décrit une position géographique associée à une adresse ou un toponyme.

  • type : Type de position (ex: entrance, building, etc.).
  • geometry : L'objet géométrique associé à cette position, au format TYPE_GEOMETRY.
Exemple de TYPE_POSITION 
{
  "type": "entrance",
  "geometry": {
    "type": "Point",
    "coordinates": [2.294481, 48.858370]
  }
}

Description des types d'objets meta

TYPE_DISTRICT_META

Le TYPE_DISTRICT_META contient des informations supplémentaires et spécifiques à l'entité administrative.

Modele du TYPE_DISTRICT_META 
{
  ban: {
    DEPRECATED_id: string,
    type: string,
    region: {
      nom: string,
      code: string
    },
    departement: {
      nom: string,
      code: string
    },
    composedAt: Date,
    dateRevision: Date,
    withBanId: boolean,
    BETA_hashIdFix: string
  },
  insee: {
    cog: string,
    BETA_mainCog: string,
    BETA_isMainCog: string
  },
  laPoste: {
    codePostal: string[]
  }
}
Explication
  • ban : Métadonnées du format BAL ou données calculées par la Base d'Adresse Nationale.
    • DEPRECATED_id : [DEPRECATED] Identifiant déprécié dans la BAN.
    • type : Type de commune ou d'entité administrative actuelle.
    • region : Région administrative associée à l'entité administrative.
    • departement : Département associé à l'entité administrative.
    • composedAt : Date de composition de l'objet.
    • dateRevision : Date de révision de l'objet.
    • withBanId : Indicateur d'utilisation de l'identifiant BAN.
    • BETA_hashIdFix : [BETA] Hash d'identification idFix.
  • insee : Données fournis par l''INSEE'.
    • cog : Code officiel géographique de l'entité administrative.
    • BETA_mainCog : [BETA] Code officiel géographique de la commune Chef Lieux.
    • BETA_isMainCog : [BETA] Indicateur de chef lieux (vaut true Si le district est également chef lieux).
  • laPoste : Données fournis par 'La Poste SAS'.
    • codePostal : Liste des codes postaux associés à l'entité administrative.

Un exemple de TYPE_DISTRICT_META est disponible dans la section "Exemple de type TYPE_DISTRICT"

TYPE_MICRO_TOPONYM_META

Le TYPE_MICRO_TOPONYM_META fournit des informations supplémentaires sur un toponyme commun.

Modele du TYPE_MICRO_TOPONYM_META 
{
  ban: {
    DEPRECATED_id: string,
    DEPRECATED_groupId: string,
    DEPRECATED_cleInteropBAN: any,
    BETA_cleInterop: string,
    category: string,
    sources: string[],
    sourceNomVoie: string,
    BETA_hashIdFix: string
  },
  dgfip: {
    BETA_cadastre: string[],
    BETA_codeFantoir: string
  },
  insee: {
    cog: string,
    BETA_mainCog: string,
    BETA_isMainCog: string
  },
  laPoste: {
    codePostal: string[]
  }
}
Explications
  • ban : Métadonnées provenant de la Base d'Adresse Nationale (BAN).
    • DEPRECATED_id : [DEPRECATED] Identifiant déprécié dans la BAN.
    • DEPRECATED_groupId : [DEPRECATED] Identifiant de groupe déprécié dans la BAN.
    • DEPRECATED_cleInteropBAN : [DEPRECATED] Clé d'interopérabilité calculé, dépréciée dans la BAN.
    • BETA_cleInterop : [BETA] Clé d'interopérabilité fournit par le producteur de la donnée.
    • category : Catégorie du micro-toponyme (ex: voie, lieu-dit, etc.).
    • sources : Liste des sources de données.
    • sourceNomVoie : Source spécifique pour le nom de voie.
    • BETA_hashIdFix : [BETA] Hash d'identification fixe.
  • dgfip : Données provenant de la Direction Générale des Finances Publiques (DGFiP).
    • BETA_cadastre : [BETA] Liste d'identifiant de parcelle cadastrale.
    • BETA_codeFantoir : [BETA] Code Fantoir en test.
  • insee : Données provenant de l'Institut national de la statistique et des études économiques (INSEE).
    • cog : Code officiel géographique de l'entité administrative associé.
    • BETA_mainCog : [BETA] Code officiel géographique de la commune Chef Lieux.
    • BETA_isMainCog : [BETA] Indicateur de chef lieux (vaut true Si le district est également chef lieux).
  • laPoste : Données provenant de La Poste SAS.
    • codePostal : Liste des codes postaux associés.

Un exemple de TYPE_MICRO_TOPONYM_META est disponible dans la section "Exemple de type TYPE_MICRO_TOPONYM"

TYPE_ADDRESS_META

Le TYPE_ADDRESS_META contient des métadonnées associées à une adresse.

Modele du TYPE_ADDRESS_META 
{
  ban: {
    DEPRECATED_id: string,
    DEPRECATED_cleInteropBAN: any,
    BETA_cleInterop: string,
    sources: string[],
    sourcePosition: string,
    BETA_hashIdFix: string
  },
  dgfip: {
    BETA_cadastre: string,
    BETA_codeFantoir: string
  },
  insee: {
    cog: string,
    BETA_mainCog: string,
    BETA_isMainCog: string
  },
  laPoste: {
    codePostal: string[]
  }
}
Explications
  • ban : Métadonnées provenant de la Base d'Adresse Nationale (BAN).
    • DEPRECATED_id : [DEPRECATED] Identifiant déprécié dans la BAN.
    • DEPRECATED_cleInteropBAN : [DEPRECATED] Clé d'interopérabilité calculé, dépréciée dans la BAN.
    • BETA_cleInterop : [BETA] Clé d'interopérabilité fournit par le producteur de la donnée.
    • sources : Liste des sources de données.
    • sourcePosition : Source de données de la position principale.
    • BETA_hashIdFix : [BETA] Hash d'identification fixe.
  • dgfip : Données provenant de la Direction Générale des Finances Publiques (DGFiP).
    • BETA_cadastre : [BETA] Liste d'identifiant de parcelle cadastrale.
    • BETA_codeFantoir : [BETA] Code Fantoir du micro-toponyme associé.
  • insee : Données provenant de l'Institut national de la statistique et des études économiques (INSEE).
    • cog : Code officiel géographique de l'entité administrative associé.
    • BETA_mainCog : [BETA] Code officiel géographique de la commune Chef Lieux.
    • BETA_isMainCog : [BETA] Indicateur de chef lieux (vaut true Si le district est également chef lieux).
  • laPoste : Données provenant de La Poste SAS.
    • codePostal : Codes postal associé.

Un exemple de TYPE_ADDRESS_META est disponible dans la section "Exemple de type TYPE_ADDRESS"

Description des objets composants de l'adresse

District

Le type TYPE_DISTRICT représente une entité administrative dans la Base d'Adresse Nationale (BAN).

Les Type spécifiques aux districts

  • TYPE_DISTRICT_CONFIG : Le type TYPE_DISTRICT_CONFIG est un objet permettant de stocker l'ensemble des paramètre d'un district (langue par défaut, fournisseur de données BAL, etc). Le type TYPE_DISTRICT_CONFIG étant encore en cours d'écriture, sa description détaillée sera fournie ultérieurement.

Modele du type TYPE_DISTRICT

{
	id: TYPE_BAN_ID,
	labels: TYPE_LABEL[],
	config: TYPE_DISTRICT_CONFIG | null,
	meta: TYPE_DISTRICT_META,
	BETA_legalityDate: Date | null,
	BETA_lastRecordDate: Date | null
}

Exemple de type TYPE_DISTRICT

{
  "id": "b99b6b4f-3ce7-4e98-ad55-bc9fd6aa62f5",
  "Labels": [
    {
      "isoCode": "fra",
      "value": "Bayonne"
    }
  ],
  "config": null,
  "meta": {
    "ban": {
      "DEPRECATED_id": "64102",
      "type": "commune-actuelle",
      "region": {
        "nom": "Nouvelle-Aquitaine",
        "code": "75"
      },
      "departement": {
        "nom": "Pyrénées-Atlantiques",
        "code": "64"
      },
      "composedAt": "2024-06-21T09:45:25.323Z",
      "dateRevision": "2024-06-12T08:24:23.224Z",
      "withBanId": false,
      "BETA_hashIdFix": ""
    },
    "insee": {
      "cog": "64102",
      "BETA_mainCog": "",
      "BETA_isMainCog": ""
    },
    "laPoste": {
      "codePostal": [
        "64100"
      ]
    }
  },
  "BETA_legalityDate": "2024-06-21T09:45:25.323Z",
  "BETA_lastRecordDate": "2024-06-21T09:45:25.323Z"
}

Micro-Toponym

Le type TYPE_MICRON_TOPONYM, représente une voie ou un lieudit présents sur un district.

Modele

{

	id: TYPE_BAN_ID,
	districtID: TYPE_BAN_ID,
	labels: TYPE_LABEL[],
	geometry:  TYPE_GEOMETRY,
	meta:  TYPE_MICRO_TOPONYM_META,
	BETA_legalityDate: Date | null,
	BETA_lastRecordDate: Date | null
}

Exemple

{
    "id": "0bca0092-e585-4713-9bfa-fdc4de534a63",
    "districtID": "b99b6b4f-3ce7-4e98-ad55-bc9fd6aa62f5",
    "labels": [
        {
            "isoCode": "fra",
            "value": "Petite rue de l'Esté"
        },
        {
            "isoCode": "eus",
            "value": "Esté karrika ttipia"
        }
    ],
    "geometry": {
        "type": "Point",
        "coordinates": [
            -1.466797,
            43.494803
        ]
    },
    "meta": {
        "ban": {
            "DEPRECATED_id": "64102_xx2ps1",
            "DEPRECATED_groupId": "slug-00000-petite-rue-este",
            "DEPRECATED_cleInteropBAN": null,
            "BETA_cleInterop": "",
            "category": "voie",
            "sources": [
                "bal"
            ],
            "sourceNomVoie": "bal",
            "BETA_hashIdFix": ""
        },
        "dgfip": {
            "BETA_cadastre": "",
            "BETA_codeFantoir": ""
        },
        "insee": {
            "cog": "64102",
            "BETA_mainCog": "",
            "BETA_isMainCog": ""
        },
        "laPoste": {
            "codePostal": [
                "64100"
            ]
        }
    },
    "BETA_legalityDate": "",
    "BETA_lastRecordDate": ""
}

Address

Le type TYPE_ADDRESS représente une adresse présent sur un district.

Modele

{
	id: TYPE_BAN_ID,
	mainMicroToponymID: TYPE_BAN_ID,
	secondaryMicroToponymIDs?: TYPE_BAN_ID[],
	districtID: TYPE_BAN_ID,
	labels?: TYPE_LABEL[],
	number?: number,
	suffix?: string,
	certified: boolean,
	positions: TYPE_POSITION[],
	meta:  TYPE_ADDRESS_META,
	legalityDate: date,
	BETA_lastRecordDate: date | null,
}

Exemple :

{
  "id": "e7b18152-95b5-451c-8d69-b9a44a01b5ff",
  "mainMicroToponymID": "0bca0092-e585-4713-9bfa-fdc4de534a63",
  "secondaryMicroToponymIDs": null,
  "districtID": "b99b6b4f-3ce7-4e98-ad55-bc9fd6aa62f5",
  "labels": [
    {
      "isoCode": "fra",
      "value": null
    }
  ],
  "number": 5,
  "suffix": null,
  "certified": true,
  "positions": [
    {
      "type": "entrée",
      "geometry": {
        "type": "Point",
        "coordinates": [-1.467080085902224, 43.494807245855924]
      }
    }
  ],
  "meta": {
    "ban": {
      "DEPRECATED_id": "64102_xx2ps1_00005",
      "DEPRECATED_cleInteropBAN": "64102_xx2ps1_00005",
      "cleInterop": "64102_0795_00005",
      "sources": ["bal"],
      "sourcePosition": "bal",
      "BETA_hashIdFix": ""
    },
    "dgfip": { 
      "cadastre": ["64102000BH0329"], 
      "BETA_fantoir": "" 
    },
    "insee": { 
      "cog": "64102", 
      "BETA_mainCog": "", 
      "BETA_isMainCog": "" 
    },
    "laPoste": { 
      "codePostal": "64100" 
    }
  },
  "legalityDate": "2015-12-17",
  "BETA_lastRecordDate": ""
}

Description du format d'échange "Format BAN"

Le format d'échange "Format BAN" est utilisé pour représenter les données complètes de la Base d'Adresse Nationale.

Il est utilisé pour l'échange de données complètes de la BAN entre différents systèmes d'information. Il a pour objectif de synchroniser et de maintenir la cohérence des informations géographiques et administratives à travers diverses applications et bases de données.

Modele du type TYPE_OBJECT_BAN_FORMAT 

{
	__meta: {
		date: DATE
	},
	districts: TYPE_DISTRICT[],
	microToponyms: TYPE_MICRO_TOPONYM[],
	addresses: TYPE_ADDRESS[]
}

Explication

  • __meta: Un objet de Métadonnées utiles à la lecture et l'interprétation de la donnée.
  • districts : Un tableau contenant tous les districts répertoriés dans la Base d'Adresse Nationale. Chaque district est représenté par un objet de type TYPE_DISTRICT.
  • microToponyms : Une liste des toponymes communs répertoriés dans la BAN. Chaque toponyme commun est représenté par un objet de type TYPE_MICRO_TOPONYM.
  • addresses : Un ensemble d'adresses enregistrées dans la BAN. Chaque adresse est représentée par un objet de type TYPE_ADDRESS.

Métadonnées du format d'échange "Format BAN"

  • date: Date de création de la données fournie.

Description du format d'échange "Différentiel BAN"

Le format d'échange "Différentiel BAN" est utilisé pour représenter les changements incrémentiels (ajouts, modifications, suppressions), entre deux date, dans la Base d'Adresse Nationale.

Il est utilisé pour mettre à jours les données BAN entre différents systèmes d'information à partir d'un échantillon partiel de donnée. Tout comme le format BAN, il a pour objectif de synchroniser et de maintenir la cohérence des informations géographiques et administratives à travers diverses applications et bases de données.

Modele du type TYPE_OBJECT_BAN_DIFF 

{
	__meta: {
		date: DATE,
		fromDate: DATE,
		toDate: DATE,
		cogList: string[],
		districtIDs: TYPE_BAN_ID[]
	},
	created: TYPE_OBJECT_BAN_FORMAT,
	disabled: TYPE_OBJECT_BAN_FORMAT,
	updated: {
		districts: [TYPE_DISTRICT, TYPE_DISTRICT][],
		microToponyms: [TYPE_MICRO_TOPONYM, TYPE_MICRO_TOPONYM][],
		addresses: [TYPE_ADDRESS, TYPE_ADDRESS][]
	}
}

Explications

  • __meta: Un objet de Métadonnées utiles à la lecture et l'interprétation de la donnée.
  • created : Contient, au format BAN, les nouveaux objets ajoutés.
  • disabled : Contient, au format BAN, les objets désactivés ou supprimés.
  • updated : Contient, sous la forme d'un objets présentant chaque types présent dans le format BAN (district, microToponym, address) , les éléments modifiés. Chaque élément y est représenté sous forme de liste de paires d'objets, après et avant modification ([{après}, {avant}]).

Métadonnées du format d'échange "Différentiel BAN"

  • date: Date de création de la données fournie.
  • fromDate: Date de début du différentiel.
  • toDate: Date de fin du différentiel.
  • cogList: Liste de code INSEE des communes concernées par la donnée.
  • districtIDs: Liste d'Identifiant BAN des district (communes) concernés par la donnée.

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