For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Aller au contenu

Éditer le RNB

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

Pré-requis, cultivez-vous 🙂

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
/api/alpha/buildings/

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é (en-tête Authorization: Token <votre token>) et disposer des droits nécessaires pour écrire dans le RNB.

La requête est refusée (400) si un champ obligatoire manque, si une clé d'interopérabilité ne fait pas entre 5 et 30 caractères ou désigne autre chose qu'un numéro (voie, lieu-dit ou commune), ou si la géométrie ne respecte pas les règles décrites pour le champ shape.

Autorisations
AuthorizationstringRequis

Token d'authentification, envoyé sous la forme Token <votre token>. Il est nécessaire pour modifier 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. Chaque clé fait entre 5 et 30 caractères.

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.

La géométrie doit :

  • être valide, en 2D (les géométries avec une coordonnée Z sont refusées) et en WGS84 ;
  • pour un polygone ou un multipolygone, avoir une surface comprise entre 5 m² et 500000 m² ;
  • ne pas recouvrir à plus de 80 % un autre bâtiment actif au statut constructed ou notUsable, ni être recouverte par lui à plus de 80 % (un point situé dans un tel bâtiment est refusé).
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: MFD5CFNA7GX5
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, un bâtiment remplacé par une fusion ou une scission, ou un bâtiment dont la création a été annulée.

Example: true
post/api/alpha/buildings/
POST /api/alpha/buildings/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Authorization: Token YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "comment": "nouveau bâtiment",
  "status": "constructed",
  "addresses_cle_interop": [
    "75105_8884_00004"
  ],
  "shape": "POLYGON((2.3522 48.8566, 2.3532 48.8567, 2.3528 48.857, 2.3522 48.8566))"
}
{
  "rnb_id": "MFD5CFNA7GX5",
  "status": "constructed",
  "point": {
    "type": "Point",
    "coordinates": [
      -0.280536093341573,
      47.18791226741607
    ]
  },
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [
            -0.280580994183435,
            47.18781451259896
          ],
          [
            -0.280518618884989,
            47.18802712764387
          ],
          [
            -0.280312563687183,
            47.18800773707939
          ],
          [
            -0.280354544338391,
            47.18778578845762
          ],
          [
            -0.280580994183435,
            47.18781451259896
          ]
        ],
        [
          [
            -0.28053964857276,
            47.187830101194784
          ],
          [
            -0.280374443008843,
            47.18780865208074
          ],
          [
            -0.28033686595634,
            47.18799443363734
          ],
          [
            -0.280496410208815,
            47.18800973584818
          ],
          [
            -0.28053964857276,
            47.187830101194784
          ]
        ]
      ]
    ]
  },
  "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",
      "organization_short_name": "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
}

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

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

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é (en-tête Authorization: Token <votre token>) 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", "is_valid": true}

La requête est refusée (400) si :

  • le corps est vide ou ne contient que comment, ou combine is_active avec status, addresses_cle_interop, shape ou is_valid ;

  • le bâtiment est inactif et la requête ne demande pas sa réactivation (une requête qui ne change rien peut répondre 204) ;

  • is_active vaut false alors que le bâtiment est déjà inactif ;

  • is_active vaut true alors que la dernière opération sur le bâtiment n'est pas une désactivation (par exemple un bâtiment désactivé par une fusion ou une scission) ;

  • une clé d'interopérabilité ne fait pas entre 5 et 30 caractères ;

  • une clé d'interopérabilité désigne autre chose qu'un numéro (voie, lieu-dit ou commune) ;

  • la nouvelle géométrie ne respecte pas les règles décrites pour le champ shape.

Autorisations
AuthorizationstringRequis

Token d'authentification, envoyé sous la forme Token <votre token>. Il est nécessaire pour modifier le RNB.

Paramètres de chemin
rnb_idstringRequis

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

Example: MFD5CFNA7GX5
Corps
commentstringOptionnel

Texte associé à la modification et la justifiant.

Example: Le bâtiment est démoli.
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 : la réactivation est refusée si la dernière opération sur le bâtiment n'est pas une désactivation.
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.

Chaque clé fait entre 5 et 30 caractères.

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: ["49125_0355_00024","49125_0355_00030"]
shapestringOptionnel

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.

La géométrie doit :

  • être valide, en 2D (les géométries avec une coordonnée Z sont refusées) et en WGS84 ;
  • pour un polygone ou un multipolygone, avoir une surface comprise entre 5 m² et 500000 m² ;
  • ne pas recouvrir à plus de 80 % un autre bâtiment actif au statut constructed ou notUsable, ni être recouverte par lui à plus de 80 % (un point situé dans un tel bâtiment est refusé) ;
  • toucher la géométrie actuelle du bâtiment ou en être à moins de 20 m.
Example: POLYGON((-0.2805 47.1880, -0.2803 47.1880, -0.2803 47.1878, -0.2805 47.1880))
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

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

{
  "comment": "bâtiment démoli",
  "status": "demolished"
}

Aucun contenu

Fusion de bâtiments

post
/api/alpha/buildings/merge/

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é (en-tête Authorization: Token <votre token>) et d'avoir des droits d'édition du RNB.

Les adresses du nouveau bâtiment sont définies par l'un des deux champs suivants, obligatoirement :

  • merge_existing_addresses à true : le nouveau bâtiment reprend les adresses des bâtiments fusionnés ;

  • addresses_cle_interop : liste des adresses du nouveau bâtiment, éventuellement vide ([]).

La fusion est refusée (400) si :

  • rnb_ids contient moins de 2 identifiants, ou un identifiant qui ne fait pas 12 caractères (les identifiants s'écrivent sans tirets) ;

  • addresses_cle_interop est absent alors que merge_existing_addresses n'est pas à true, ou contient des adresses alors que merge_existing_addresses est à true ;

  • une clé d'interopérabilité ne fait pas entre 5 et 30 caractères ;

  • une clé d'interopérabilité désigne autre chose qu'un numéro (voie, lieu-dit ou commune) ;

  • l'un des bâtiments est inactif ;

  • la géométrie de l'un des bâtiments n'est pas un polygone ou un multipolygone ;

  • les bâtiments ne sont pas contigus : leurs géométries doivent se toucher pour former un seul polygone.

Autorisations
AuthorizationstringRequis

Token d'authentification, envoyé sous la forme Token <votre token>. Il est nécessaire pour modifier le RNB.

Corps
commentstringOptionnel

Commentaire optionnel associé à l'opération

rnb_idsarray · min: 2Requis

Liste des ID-RNB des bâtiments à fusionner : au moins 2 identifiants de 12 caractères, sans tirets.

Example: ["XXXXYYYYZZZZ","AAAABBBBCCCC"]
merge_existing_addressesbooleanOptionnel
  • true : le bâtiment nouvellement créé hérite des adresses des bâtiments dont il est issu. addresses_cle_interop ne doit alors contenir aucune adresse.
  • false ou absent : le champ addresses_cle_interop est obligatoire et détermine les adresses du bâtiment.
addresses_cle_interoparrayOptionnel

Liste des clés d'interopérabilité BAN liées au nouveau bâtiment créé, chacune entre 5 et 30 caractères. Si une liste vide est passée sans merge_existing_addresses à true, le bâtiment ne sera lié à aucune adresse. Obligatoire si merge_existing_addresses n'est pas à true.

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: MFD5CFNA7GX5
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, un bâtiment remplacé par une fusion ou une scission, ou un bâtiment dont la création a été annulée.

Example: true
post/api/alpha/buildings/merge/
POST /api/alpha/buildings/merge/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Authorization: Token YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "comment": "un seul et même bâtiment",
  "rnb_ids": [
    "XXXXYYYYZZZZ",
    "AAAABBBBCCCC"
  ],
  "merge_existing_addresses": true,
  "status": "constructed"
}
{
  "rnb_id": "MFD5CFNA7GX5",
  "status": "constructed",
  "point": {
    "type": "Point",
    "coordinates": [
      -0.280536093341573,
      47.18791226741607
    ]
  },
  "shape": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [
            -0.280580994183435,
            47.18781451259896
          ],
          [
            -0.280518618884989,
            47.18802712764387
          ],
          [
            -0.280312563687183,
            47.18800773707939
          ],
          [
            -0.280354544338391,
            47.18778578845762
          ],
          [
            -0.280580994183435,
            47.18781451259896
          ]
        ],
        [
          [
            -0.28053964857276,
            47.187830101194784
          ],
          [
            -0.280374443008843,
            47.18780865208074
          ],
          [
            -0.28033686595634,
            47.18799443363734
          ],
          [
            -0.280496410208815,
            47.18800973584818
          ],
          [
            -0.28053964857276,
            47.187830101194784
          ]
        ]
      ]
    ]
  },
  "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",
      "organization_short_name": "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
/api/alpha/buildings/{rnb_id}/split/

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é (en-tête Authorization: Token <votre token>) et d'avoir des droits d'édition du RNB.

La scission est refusée (400) si :

  • created_buildings contient moins de 2 bâtiments ;

  • le bâtiment à scinder est inactif ;

  • une clé d'interopérabilité ne fait pas entre 5 et 30 caractères ;

  • une clé d'interopérabilité désigne autre chose qu'un numéro (voie, lieu-dit ou commune) ;

  • la géométrie de l'un des bâtiments créés ne respecte pas les règles décrites pour le champ shape.

Autorisations
AuthorizationstringRequis

Token d'authentification, envoyé sous la forme Token <votre token>. Il est nécessaire pour modifier le RNB.

Paramètres de chemin
rnb_idstringRequis

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

Example: MFD5CFNA7GX5
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: MFD5CFNA7GX5
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, un bâtiment remplacé par une fusion ou une scission, ou un bâtiment dont la création a été annulée.

Example: true
post/api/alpha/buildings/{rnb_id}/split/
POST /api/alpha/buildings/{rnb_id}/split/ HTTP/1.1
Host: rnb-api.beta.gouv.fr
Authorization: Token YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 772

{
  "comment": "deux bâtiments distincts",
  "created_buildings": [
    {
      "status": "constructed",
      "shape": "POLYGON((-0.280518618884989 47.18802712764387, -0.280312563687183 47.18800773707939, -0.280354544338391 47.18778578845762, -0.280374443008843 47.18780865208074, -0.28033686595634 47.18799443363734, -0.280496410208815 47.18800973584818, -0.280518618884989 47.18802712764387))",
      "addresses_cle_interop": [
        "49125_0355_00024"
      ]
    },
    {
      "status": "constructed",
      "shape": "POLYGON((-0.280518618884989 47.18802712764387, -0.280496410208815 47.18800973584818, -0.28053964857276 47.187830101194784, -0.280374443008843 47.18780865208074, -0.280354544338391 47.18778578845762, -0.280580994183435 47.18781451259896, -0.280518618884989 47.18802712764387))",
      "addresses_cle_interop": [
        "49125_0355_00030"
      ]
    }
  ]
}
[
  {
    "rnb_id": "MFD5CFNA7GX5",
    "status": "constructed",
    "point": {
      "type": "Point",
      "coordinates": [
        -0.280536093341573,
        47.18791226741607
      ]
    },
    "shape": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -0.280580994183435,
              47.18781451259896
            ],
            [
              -0.280518618884989,
              47.18802712764387
            ],
            [
              -0.280312563687183,
              47.18800773707939
            ],
            [
              -0.280354544338391,
              47.18778578845762
            ],
            [
              -0.280580994183435,
              47.18781451259896
            ]
          ],
          [
            [
              -0.28053964857276,
              47.187830101194784
            ],
            [
              -0.280374443008843,
              47.18780865208074
            ],
            [
              -0.28033686595634,
              47.18799443363734
            ],
            [
              -0.280496410208815,
              47.18800973584818
            ],
            [
              -0.28053964857276,
              47.187830101194784
            ]
          ]
        ]
      ]
    },
    "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",
        "organization_short_name": "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
  }
]

Mis à jour

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