Éditer le RNB

Cette partie de l'API vous permet de contribuer au référentiel en l'éditant.

Pré-requis, cultivez-vous 🙂

Avant de modifier des données dans le RNB, assurez-vous de respecter : 1) la définition officielle du bâtiment, établie par le Conseil national de l’information géolocalisée (CNIG). Au besoin, relisez la définition du bâtiment au sens du RNB.

2) l'art de l'édition dans le RNB. Lisez les astuces pour bien éditer sur le Guide d’édition Pour que le RNB remplisse son rôle correctement, il est important que tous ses éditeurs et éditrices partagent une même méthodologie.

Il est important de préserver le RNB d’erreurs d'éditions, car les utilisateurs du référentiel sont nombreux et variés. Exemple avec les DPE : Un diagnostiqueur DPE a pu rattacher un diagnostic à un identifiant RNB. Si celui-ci est désactivé à tort, l’information est perdue pour tout le monde. Ou pire, si la géométrie du bâtiment est déplacée, voilà le diagnostic rattaché au mauvais bâtiment.

Dans cet esprit et pour éviter toute erreur massive lors de contributions en production, un quota évolutif est établi par utilisateur. Il est par défaut de 500 éditions, et est mis-à-jour par paliers après vérification des premières contributions.

Authentification

Toute édition (requête en écriture) du RNB doit faire l’objet d’une authentification. Pour vous identifier, utilisez le token fourni par l’équipe du RNB, pour ce faire : 1° 🚀 Demandez vos accès sur https://rnb.beta.gouv.fr/login 2° Une fois vos identifiants créés, cliquez sur "Mon compte" pour accéder à ''Mes Cles API''.

Ajoutez une clé Authorization aux headers HTTP de chacune de vos requêtes. La valeur doit être votre token préfixé de la chaîne “Token”. Un espace sépare “Token” et votre token.

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Bac à sable

Il est vivement recommandé d'utiliser l'environnement "bac à sable" du RNB pour développer et tester vos outils.

Création d'un bâtiment

post

Cet endpoint permet de créer un bâtiment dans le RNB. Lors de la création, un identifiant RNB (ID-RNB) est généré. L'utilisateur doit être identifié et disposer des droits nécessaires pour écrire dans le RNB.

Corps

commentstringOptionnel

Commentaire optionnel associé à la création du bâtiment.

Example: Bâtiment ajouté suite à une nouvelle construction, visible sur la vue satellite.

statusstring · enumRequis

Statut du bâtiment.

Example: constructedValeurs possibles:

addresses_cle_interoparrayRequis

Liste des clés d'interopérabilité BAN liées au bâtiment, éventuellement vide ([]) en l'absence d'adresse à attribuer.

Example: ["75105_8884_00004","75105_8884_00006"]

shapestringRequis

Géométrie du bâtiment au format WKT ou HEX, en WGS84. La géométrie attendue est idéalement un polygone représentant le bâtiment, mais il est également possible de ne donner qu'un point.

Example: POLYGON((2.3522 48.8566, 2.3532 48.8567, 2.3528 48.857, 2.3522 48.8566))

is_validbooleanOptionnel

Optionnel. Si True, le bâtiment est marqué comme valide dès sa création. L'utilisateur déclare ainsi que l'ensemble des informations liées aux bâtiments (statut, adresse, géométrie) sont valides. Vaut 'False' par défaut, ce qui revient à simplement créer le bâtiment sans le valider.

Default: false

Réponses

201

Détails du bâtiment nouvellement créé dans le RNB

application/json

rnb_idstringOptionnel

Identifiant unique du bâtiment dans le RNB

Example: PG46YY6YWCX8

statusstring · enumOptionnel

Statut du bâtiment

Example: constructedValeurs possibles:

is_activebooleanOptionnel

Indique si l'identifiant RNB est actif (True) ou inactif (False). Un identifiant inactif désigne un objet ne correspondant pas à la définition d'un bâtiment.

Example: true

400

Requête invalide (données mal formatées ou incomplètes).

403

L'utilisateur n'a pas les droits nécessaires pour créer un bâtiment.

404

Une clé d'interopérabilité n'a pas été trouvée auprès de la BAN

429

Le quota de requêtes a été atteint. Un quota maximal de 20 requêtes par secondes est appliqué, mais celui-ci peut varier par requête. Veuillez consulter les headers HTTP de la réponse pour plus d'informations concernant le quota.

503

Service temporairement indisponible

post/api/alpha/buildings/

POST /api/alpha/buildings/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Content-Type: application/json
Accept: */*
Content-Length: 284

{
  "comment": "Bâtiment ajouté suite à une nouvelle construction, visible sur la vue satellite.",
  "status": "constructed",
  "addresses_cle_interop": [
    "75105_8884_00004",
    "75105_8884_00006"
  ],
  "shape": "POLYGON((2.3522 48.8566, 2.3532 48.8567, 2.3528 48.857, 2.3522 48.8566))",
  "is_valid": false
}

{
  "rnb_id": "PG46YY6YWCX8",
  "status": "constructed",
  "point": {
    "type": "Point",
    "coordinates": [
      -0.570505392116188,
      44.841034137099996
    ]
  },
  "shape": {
    "type": "Point",
    "coordinates": [
      [
        -0.570505392116188,
        44.841034137099996
      ]
    ]
  },
  "addresses": [
    {
      "id": "02191_0020_00003",
      "ban_id": "a2ef3456-7890-1234-abcd-ef1234567890",
      "source": "bdnb",
      "street_number": "3",
      "street_rep": "bis",
      "street": "rue de l'église",
      "city_name": "Chivy-lès-Étouvelles",
      "city_zipcode": "02000",
      "city_insee_code": 2191
    }
  ],
  "validated_by": [
    {
      "id": 1,
      "username": "n.martin",
      "organization_name": "Mairie de Dreux"
    }
  ],
  "ext_ids": [
    {
      "id": "bdnb-bc-3B85-TYM9-FDSX",
      "source": "bdnb",
      "source_version": "2023_01",
      "created_at": "2023-12-07T13:20:58.310444+00:00"
    }
  ],
  "is_active": true,
  "plots": [
    {
      "id": "01402000AB0051",
      "bdg_cover_ratio": 0.403
    }
  ]
}

Mise à jour ou désactivation/réactivation d'un bâtiment

patch

Cet endpoint permet de :

mettre à jour un bâtiment existant (status, addresses_cle_interop, shape)
désactiver son ID-RNB s'il s'avère qu'il ne devrait pas faire partie du RNB. Par exemple un arbre qui aurait été par erreur répertorié comme un bâtiment du RNB.
réactiver un ID-RNB, si celui-ci a été désactivé par erreur.
valider un bâtiment.

Il n'est pas possible de simultanément mettre à jour un bâtiment et de le désactiver/réactiver. Il n'est pas possible de simultanément valider un bâtiment et de le désactiver/réactiver.

Cet endpoint nécessite d'être identifié et d'avoir des droits d'édition du RNB.

Exemples valides:

{"comment": "faux bâtiment", "is_active": False}
{"comment": "RNB ID désactivé par erreur, on le réactive", "is_active": True}
{"comment": "bâtiment démoli", "status": "demolished"}
{"comment": "bâtiment en ruine", "status": "notUsable", "addresses_cle_interop": ["75105_8884_00004"]}
{"comment": "je valide ce bâtiment", "validate": True}

Paramètres de chemin

rnb_idstringRequis

Identifiant unique du bâtiment dans le RNB (ID-RNB)

Example: PG46YY6YWCX8

Corps

commentstringOptionnel

Texte associé à la modification et la justifiant.

Example: Ce n'est pas un bâtiment mais un arbre.

is_activebooleanOptionnel

False : l' ID-RNB est désactivé, car sa présence dans le RNB est une erreur. Ne permet pas de signaler une démolition, qui doit se faire par une mise à jour du statut.
True : l'ID-RNB est réactivé. À utiliser uniquement pour annuler une désactivation accidentelle.

statusstring · enumOptionnel

Statut du bâtiment.

Example: demolishedValeurs possibles:

addresses_cle_interoparrayOptionnel

Liste des clés d'interopérabilité BAN liées au bâtiment.

Si ce paramêtre est :

absent, alors les clés ne sont pas modifiées.
présent et que sa valeur est une liste vide ([]), alors le bâtiment ne sera plus lié à aucune adresse.

Example: ["75105_8884_00004","75105_8884_00006"]

shapestringOptionnel

Géométrie du bâtiment au format WKT ou HEX, en WGS84. La géometrie attendue est idéalement un polygone représentant le bâtiment, mais il est également possible de ne donner qu'un point. La géométrie doit être en 2D : les géométries 3D (avec une coordonnée Z) sont refusées.

is_validbooleanOptionnel

Permet à l'utilisateur de valider l'état actuel du bâtiment (True) ou de retirer cette validation s'il l'avait précédemment posée (False).

Peut être envoyé seul ou en complément d'une modification (status, addresses_cle_interop, shape).
Lorsqu'un bâtiment est modifié, la liste des utilisateurs l'ayant validé est réinitialisée.

Réponses

204

Pas de contenu attendu dans la réponse en cas de succès

Aucun contenu

400

Requête invalide (données mal formatées ou incomplètes).

403

L'utilisateur n'a pas les droits nécessaires pour modifier un bâtiment.

404

ID-RNB inconnu ou une clé d'interopérabilité n'a pas été trouvée auprès de la BAN

429

503

Service temporairement indisponible

patch/api/alpha/buildings/{rnb_id}/

PATCH /api/alpha/buildings/{rnb_id}/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "comment": "Ce n'est pas un bâtiment mais un arbre.",
  "is_active": true,
  "status": "demolished",
  "addresses_cle_interop": [
    "75105_8884_00004",
    "75105_8884_00006"
  ],
  "shape": "text",
  "is_valid": true
}

Aucun contenu

Fusion de bâtiments

post

Permet de corriger le RNB en fusionnant plusieurs bâtiments existants, donnant lieu à la création d'un nouveau bâtiment.

Cet endpoint nécessite d'être identifié et d'avoir des droits d'édition du RNB.

Corps

commentstringOptionnel

Commentaire optionnel associé à l'opération

rnb_idsarrayRequis

Liste des ID-RNB des bâtiments à fusionner

Example: ["XXXXYYYYZZZZ","AAAABBBBCCCC"]

merge_existing_addressesbooleanOptionnel

True, le bâtiment nouvellement créé hérite des adresses des bâtiments dont il est issu.
False ou non rempli, le champ addresses_cle_interop est utilisé pour déterminer les adresses du bâtiment.

addresses_cle_interoparrayOptionnel

Liste des clés d'interopérabilité BAN liées au nouveau bâtiment créé. Si une liste vide est passée, le bâtiment ne sera lié à aucune adresse.

Example: ["75105_8884_00004","75105_8884_00006"]

statusstring · enumRequis

Statut du bâtiment.

Example: constructedValeurs possibles:

Réponses

201

Détails du bâtiment nouvellement créé

application/json

rnb_idstringOptionnel

Identifiant unique du bâtiment dans le RNB

Example: PG46YY6YWCX8

statusstring · enumOptionnel

Statut du bâtiment

Example: constructedValeurs possibles:

is_activebooleanOptionnel

Indique si l'identifiant RNB est actif (True) ou inactif (False). Un identifiant inactif désigne un objet ne correspondant pas à la définition d'un bâtiment.

Example: true

400

Requête invalide (données mal formatées ou incomplètes).

403

L'utilisateur n'a pas les droits nécessaires pour fusionner des bâtiments.

404

ID-RNB inconnu ou une clé d'interopérabilité n'a pas été trouvée auprès de la BAN

429

503

Service temporairement indisponible

post/api/alpha/buildings/merge/

POST /api/alpha/buildings/merge/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "comment": "text",
  "rnb_ids": [
    "XXXXYYYYZZZZ",
    "AAAABBBBCCCC"
  ],
  "merge_existing_addresses": true,
  "addresses_cle_interop": [
    "75105_8884_00004",
    "75105_8884_00006"
  ],
  "status": "constructed"
}

{
  "rnb_id": "PG46YY6YWCX8",
  "status": "constructed",
  "point": {
    "type": "Point",
    "coordinates": [
      -0.570505392116188,
      44.841034137099996
    ]
  },
  "shape": {
    "type": "Point",
    "coordinates": [
      [
        -0.570505392116188,
        44.841034137099996
      ]
    ]
  },
  "addresses": [
    {
      "id": "02191_0020_00003",
      "ban_id": "a2ef3456-7890-1234-abcd-ef1234567890",
      "source": "bdnb",
      "street_number": "3",
      "street_rep": "bis",
      "street": "rue de l'église",
      "city_name": "Chivy-lès-Étouvelles",
      "city_zipcode": "02000",
      "city_insee_code": 2191
    }
  ],
  "validated_by": [
    {
      "id": 1,
      "username": "n.martin",
      "organization_name": "Mairie de Dreux"
    }
  ],
  "ext_ids": [
    {
      "id": "bdnb-bc-3B85-TYM9-FDSX",
      "source": "bdnb",
      "source_version": "2023_01",
      "created_at": "2023-12-07T13:20:58.310444+00:00"
    }
  ],
  "is_active": true
}

Scission de bâtiments

post

Permet de corriger le RNB en scindant un bâtiment existant, donnant lieu à la création de plusieurs nouveaux bâtiments.

Cet endpoint nécessite d'être identifié et d'avoir des droits d'édition du RNB.

Paramètres de chemin

rnb_idstringRequis

Identifiant unique du bâtiment dans le RNB (ID-RNB)

Example: PG46YY6YWCX8

Corps

commentstringOptionnel

Commentaire optionnel associé à l'opération

Réponses

201

Détails des bâtiments nouvellement créés

application/json

rnb_idstringOptionnel

Identifiant unique du bâtiment dans le RNB

Example: PG46YY6YWCX8

statusstring · enumOptionnel

Statut du bâtiment

Example: constructedValeurs possibles:

is_activebooleanOptionnel

Indique si l'identifiant RNB est actif (True) ou inactif (False). Un identifiant inactif désigne un objet ne correspondant pas à la définition d'un bâtiment.

Example: true

400

Requête invalide (données mal formatées ou incomplètes).

403

L'utilisateur n'a pas les droits nécessaires pour scinder un bâtiment.

404

ID-RNB inconnu ou une clé d'interopérabilité n'a pas été trouvée auprès de la BAN

429

503

Service temporairement indisponible

post/api/alpha/buildings/{rnb_id}/split/

POST /api/alpha/buildings/{rnb_id}/split/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "comment": "text",
  "created_buildings": [
    {
      "status": "constructed",
      "shape": "POLYGON((2.3522 48.8566, 2.3532 48.8567, 2.3528 48.857, 2.3522 48.8566))",
      "addresses_cle_interop": [
        "75105_8884_00004",
        "75105_8884_00006"
      ]
    }
  ]
}

[
  {
    "rnb_id": "PG46YY6YWCX8",
    "status": "constructed",
    "point": {
      "type": "Point",
      "coordinates": [
        -0.570505392116188,
        44.841034137099996
      ]
    },
    "shape": {
      "type": "Point",
      "coordinates": [
        [
          -0.570505392116188,
          44.841034137099996
        ]
      ]
    },
    "addresses": [
      {
        "id": "02191_0020_00003",
        "ban_id": "a2ef3456-7890-1234-abcd-ef1234567890",
        "source": "bdnb",
        "street_number": "3",
        "street_rep": "bis",
        "street": "rue de l'église",
        "city_name": "Chivy-lès-Étouvelles",
        "city_zipcode": "02000",
        "city_insee_code": 2191
      }
    ],
    "validated_by": [
      {
        "id": 1,
        "username": "n.martin",
        "organization_name": "Mairie de Dreux"
      }
    ],
    "ext_ids": [
      {
        "id": "bdnb-bc-3B85-TYM9-FDSX",
        "source": "bdnb",
        "source_version": "2023_01",
        "created_at": "2023-12-07T13:20:58.310444+00:00"
      }
    ],
    "is_active": true
  }
]

PrécédentDifférentiel entre deux dates

SuivantAPI ADS

Mis à jour il y a 13 jours

Ce contenu vous a-t-il été utile ?