Apprendre à utiliser l’API

Ce tutoriel présente les différents types de routes de l’API et le type de requêtes que vous pouvez réaliser avec celles-ci. Les exemples requièrent une connaissance de base sur les appels d’API en REST, et pour certaines explications, des notions de SQL. Certains exemples avancés nécessitent l’utilisation d’une clé d’API pour les fonctionnalités réservées aux souscriptions Expert ou Open+.

Ce tutoriel concerne la mécanique d’appel des API. Il ne traite pas des contenus ni des cas d’usage.

Les routes /donnees et /metadonnee

Filtres par lignes et par colonnes :

Les API qui commencent par /donnees et /metadonnees, (comme https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe) suivent toutes une syntaxe similaire qui vous permet de sélectionner, filtrer et paginer les résultats.

Par exemple :

import requests
r = requests.get(f'https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe_complet',
                 params={   
                         'select': 'batiment_groupe_id, code_departement_insee, code_qp, nom_qp, libelle_commune_insee',
                         'batiment_groupe_id': 'eq.bdnb-bg-M34R-VABB-TJX1',
                         'limit': 5}                 
                 )
r.json()
# >> [{'batiment_groupe_id': 'bdnb-bg-M34R-VABB-TJX1',
#   'code_departement_insee': '24',
#   'code_qp': 'QP024001',
#   'nom_qp': 'Rive Gauche',
#   'libelle_commune_insee': 'Bergerac'}]
{'code': '42703',
 'details': None,
 'hint': 'Perhaps you meant to reference the column "batiment_groupe_complet.nom_qp".',
 'message': 'column batiment_groupe_complet.code_qp does not exist'}

Cet appel retourne une liste de dictionnaires en json, avec autant d’élément dans la liste que de lignes correspondents à la requête. Les clefs des dictionnaires correspondents au nom des colonnes retournées par l’appel API.

On peut décomposer les paramètres d’appel ainsi : - 'select': 'batiment_groupe_id...' permet de sélectionner les colonnes à retourner. Si ce paramètre est omis, toutes les colonnes sont retournées. - 'limit':5 permet de ne prendre que 5 lignes au maximum. Si ce paramètre est omis, le nombre d’objets retourné est le minimum entre le nombre d’objets qui correspondent à votre sélection et le nombre maximum autorisé par votre niveau de souscription. - 'batiment_groupe_id': 'eq.bdnb-bg-M34R-VABB-TJX1' permet de retourner les informations pour le bâtiment groupe dont l’identifiant est bdnb-bg-M34R-VABB-TJX1. Il est possible de combiner plusieurs conditions.

✎ Ici, il est important de noter eq. qui est l’opérateur d’égalité. De nombreux autres sont disponibles, comme gt (plus grand que). Pour plus d’exemple, vous pouvez vous référer à cette doc en ligne.

Cet appel API est équivalent à la requête SQL :

SELECT batiment_groupe_id, code_departement_insee, code_qp, nom_qp, libelle_commune_insee
FROM batiment_groupe_complet
WHERE batiment_groupe_id = 'bdnb-bg-M34R-VABB-TJX1'
LIMIT 5

💡 Astuce

Pour avoir des réponses plus rapides, pensez à ne sélectionner que les colonnes qui vous intéressent. Les API peuvent retourner un nombre de colonnes important (+150), certaines contenant des géométries. Le volume retourné peut devenir problématique et causer des time out (au-delà de 10s d’attente.)

Nombre d’objets retournés sur /donnees

Comme vu précédemment, il est possible de choisir le nombre de lignes retournées par l’API. Le nombre maximum d’objets autorisés dans une réponse dépend de votre souscription.

En utilisant l’API ouverte (sans souscription), vous pourrez récupérer jusqu’à 10 objets à chaque appel, même si le paramètre limit dans la requête est à 15. Le tableau ci-dessous montre les seuils par souscription :

open (pas de souscription) open+ expert
Quota (hit/month/ip) 10k 1M 10M
Nombre maximum d’objets retournés par requête 10 1000 10000
Rate limit 120 /min 1200 /min 1200 /min

Formats de sortie

Les API /donnees et /metadonnees supportent des sorties en json, csv et geojson. Par défaut, les réponses sont systématiquement en json. Pour obtenir d’autres formats, il suffit de passer ces headers lors de l’appel :

  • json : "Accept": "application/json"
  • geojson : "Accept": "application/geo+json" (nécessite qu’une colonne géospatiale soit présente)
  • csv : "Accept": "text/csv"

Exemple :

import requests
r =  requests.get('https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe',
                  params  = {'limit':'5'},
                  headers = {"Accept": "application/geo+json"}
                 )
r.json()
{'type': 'FeatureCollection',
 'features': [{'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[662147.2, 6623896.2],
       [662149.3, 6623888.4],
       [662136.1, 6623884.9],
       [662134, 6623892.6],
       [662147.2, 6623896.2]]],
     [[[662124.4, 6623922.1],
       [662128.6, 6623922.9],
       [662129.9, 6623914.5],
       [662125.7, 6623913.2],
       [662124.4, 6623922.1]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-PEGS-R7FE-RGAX',
    'code_commune_insee': '18197',
    'code_departement_insee': '18',
    'code_epci_insee': '200036135',
    'code_iris': '181970104',
    'code_qp': None,
    'code_region_insee': '24',
    'commune_parente': None,
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'crs': {'type': 'name', 'properties': {'name': 'EPSG:4326'}},
     'coordinates': [2.504395360524378, 46.71404777610926]},
    'libelle_commune_insee': 'Saint-Amand-Montrond',
    'nom_qp': None,
    'quartier_prioritaire': None,
    's_geom_groupe': 147}},
  {'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[661533.6, 6624364.7],
       [661553.7, 6624364.2],
       [661554, 6624373.4],
       [661534, 6624374.2],
       [661533.6, 6624364.7]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-PEHD-NZTY-TUP6',
    'code_commune_insee': '18197',
    'code_departement_insee': '18',
    'code_epci_insee': '200036135',
    'code_iris': '181970104',
    'code_qp': None,
    'code_region_insee': '24',
    'commune_parente': None,
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'crs': {'type': 'name', 'properties': {'name': 'EPSG:4326'}},
     'coordinates': [2.496529378999691, 46.71832255021383]},
    'libelle_commune_insee': 'Saint-Amand-Montrond',
    'nom_qp': None,
    'quartier_prioritaire': None,
    's_geom_groupe': 188}},
  {'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[665687.9, 6624511.8],
       [665686.4, 6624513.4],
       [665684.3, 6624511.4],
       [665686.2, 6624510],
       [665687.9, 6624511.8]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-PENG-8X49-P31Z',
    'code_commune_insee': '18197',
    'code_departement_insee': '18',
    'code_epci_insee': '200036135',
    'code_iris': '181970104',
    'code_qp': None,
    'code_region_insee': '24',
    'commune_parente': None,
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'crs': {'type': 'name', 'properties': {'name': 'EPSG:4326'}},
     'coordinates': [2.55074862957931, 46.71983106684814]},
    'libelle_commune_insee': 'Saint-Amand-Montrond',
    'nom_qp': None,
    'quartier_prioritaire': None,
    's_geom_groupe': 6}},
  {'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[662449.3, 6624025.8],
       [662447.3, 6624026.8],
       [662447.9, 6624027.9],
       [662441.6, 6624031.2],
       [662440.9, 6624030],
       [662442, 6624029.5],
       [662437.6, 6624021.1],
       [662444.8, 6624017.3],
       [662449.3, 6624025.8]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-PEUD-6WKS-WDN1',
    'code_commune_insee': '18197',
    'code_departement_insee': '18',
    'code_epci_insee': '200036135',
    'code_iris': '181970104',
    'code_qp': None,
    'code_region_insee': '24',
    'commune_parente': None,
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'crs': {'type': 'name', 'properties': {'name': 'EPSG:4326'}},
     'coordinates': [2.508335158865426, 46.71526183622225]},
    'libelle_commune_insee': 'Saint-Amand-Montrond',
    'nom_qp': None,
    'quartier_prioritaire': None,
    's_geom_groupe': 87}},
  {'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[663154.4, 6626229.9],
       [663154.4, 6626238.4],
       [663150.5, 6626238.4],
       [663150.6, 6626239.3],
       [663146.4, 6626239.3],
       [663146.4, 6626229.8],
       [663154.4, 6626229.9]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-PG4N-BC5Y-YGXC',
    'code_commune_insee': '18197',
    'code_departement_insee': '18',
    'code_epci_insee': '200036135',
    'code_iris': '181970104',
    'code_qp': None,
    'code_region_insee': '24',
    'commune_parente': None,
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'crs': {'type': 'name', 'properties': {'name': 'EPSG:4326'}},
     'coordinates': [2.517413046562942, 46.735206056976644]},
    'libelle_commune_insee': 'Saint-Amand-Montrond',
    'nom_qp': None,
    'quartier_prioritaire': None,
    's_geom_groupe': 72}}]}
{'type': 'FeatureCollection',
 'features': [{'type': 'Feature',
   'geometry': {'type': 'MultiPolygon',
    'crs': {'type': 'name', 'properties': {'name': 'EPSG:2154'}},
    'coordinates': [[[[473658.7, 6293914.4],
       [473673.5, 6293915.7],
       [473674.3, 6293908.4],
       [473664.9, 6293907.4],
       [473666.2, 6293894.5],
       [473661.6, 6293893.9],
       [473658.7, 6293914.4]]],
     [[[473697.3, 6293903.5],
       [473685.1, 6293902.5],
       [473684, 6293914.6],
       [473696.3, 6293915.7],
       [473697.3, 6293903.5]]],
     [[[473709.1, 6293873.5],
       [473697.4, 6293873.6],
       [473697.4, 6293875],
       [473688.2, 6293875],
       [473688.2, 6293865.9],
       [473665.4, 6293866],
       [473664.3, 6293877.4],
       [473697.1, 6293879.3],
       [473696.8, 6293885.3],
       [473702.2, 6293885.4],
       [473708.6, 6293885.5],
       [473708.8, 6293881.2],
       [473709.1, 6293873.5]]]]},
   'properties': {'batiment_groupe_id': 'bdnb-bg-Y5EN-7S12-1QQ7',
    'code_departement_insee': '32',
    's_geom_groupe': 784,
    'code_iris': '322190000',
    'code_commune_insee': '32219',
    'code_region_insee': '76',
    'code_qp': None,
    'nom_qp': None,
    'quartier_prioritaire': False,
    'libelle_commune_insee': 'Lupiac',
    'code_epci_insee': '243200607',
    'contient_fictive_geom_groupe': False,
    'geom_groupe_pos_wgs84': {'type': 'Point',
     'coordinates': [0.192162026949915, 43.707698592527194]}}},
[...]
import requests
r =  requests.get('https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe',
                  params  = {'limit':'5',
                            'select' : 'batiment_groupe_id, s_geom_groupe' },
                  headers = {"Accept": "text/csv"}
                 )
batiment_groupe_id,s_geom_groupe
bdnb-bg-Y5EN-7S12-1QQ7,784
bdnb-bg-3RBA-DSEE-EQK1,122
bdnb-bg-Z1BR-53SC-8QTF,214
bdnb-bg-C7W2-SCLG-K611,44
bdnb-bg-XFQC-881H-MBHH,17

Pagination

Dans le cas où le nombre d’éléments retournés est plus important que votre limite maximum, il reste possible de paginer les résultats, c’est-à-dire prendre les 10 premiers, puis les 10 suivants… ainsi de suite.

Par exemple, pour obtenir la liste des groupes de bâtiments en quartier prioritaire dans le département de l’isère :

import requests
import pandas as pd


r = requests.get(f'https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe_complet',
                 params={ 'select': 'batiment_groupe_id, annee_construction,l_libelle_adr,  code_qp, nom_qp, nb_log',
                          'quartier_prioritaire': 'eq.true',
                          'code_departement_insee' : 'eq.38'
                 }   ,             
                headers  = {'Range-Unit': 'items',
                            'Range': '0-3'}
                 )


r.json()
#print(r.headers['Content-Range'])
#>> 0-3/*
#print(pd.DataFrame(r.json()).to_markdown())
{'code': '42703',
 'details': None,
 'hint': 'Perhaps you meant to reference the column "batiment_groupe_complet.nom_qp".',
 'message': 'column batiment_groupe_complet.code_qp does not exist'}
batiment_groupe_id annee_construction l_libelle_adr code_qp nom_qp nb_log
0 bdnb-bg-V6TD-9ZN9-FE6Q 1965 [‘4 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘1 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘2 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘3 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘4 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘5 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘6 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘7 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘8 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘9 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘10 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘11 rue du languedoc, 38300, Bourgoin-Jallieu’, ‘12 rue du languedoc, 38300, Bourgoin-Jallieu’] QP038002 Champaret 170
1 bdnb-bg-PMMM-VEQ4-PJ7Z 1977 [‘8 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘10 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 86
2 bdnb-bg-9YZH-XQRZ-B2PH 1975 [‘6 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘6 B avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘11 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 100
3 bdnb-bg-W84W-7UQ1-VKD7 1980 [‘3 route de chambery, 38300, Bourgoin-Jallieu’, ‘6 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘14 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 0
import pandas as pd
import requests 
r = requests.get(f'https://api.bdnb.io/v1/bdnb/donnees/batiment_groupe_complet',
                 params={ 'select': 'batiment_groupe_id, annee_construction,l_libelle_adr,  code_qp, nom_qp, nb_log',
                          'quartier_prioritaire': 'eq.true',
                         'code_departement_insee' : 'eq.38'},             
                headers  = {'Range-Unit': 'items',
                            'Range': '4-7'}
                 )

#print(r.headers['Content-Range'])
#>> 4-7/*
r.json()
#print(pd.DataFrame(r.json()).to_markdown()) 
{'code': '42703',
 'details': None,
 'hint': 'Perhaps you meant to reference the column "batiment_groupe_complet.nom_qp".',
 'message': 'column batiment_groupe_complet.code_qp does not exist'}
batiment_groupe_id annee_construction l_libelle_adr code_qp nom_qp nb_log
0 bdnb-bg-GYLC-X4Z6-X64H 1959 [‘1 route de chambery, 38300, Bourgoin-Jallieu’] QP038002 Champaret 1
1 bdnb-bg-MT2H-ABMM-JGJB 2015 [‘16 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 1
2 bdnb-bg-Y452-N43V-CVEY 1968 [‘18 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘20 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘22 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘24 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘26 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘28 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘30 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 119
3 bdnb-bg-84N2-52E2-UWEG 1979 [‘12 avenue du dauphine, 38300, Bourgoin-Jallieu’, ‘14 avenue du dauphine, 38300, Bourgoin-Jallieu’] QP038002 Champaret 62

Limite d’appels par minutes (Rate limit) et par mois (quotas)

Pour limiter les abus sur l’API, la fréquence des appels API est également soumise à des limites :

open (pas de souscription) open+ expert
Quota (hit/month/ip) 10k 1M 10M
Rate limit 120 /min 1200 /min 1200 /min

Si vous procédez à des appels en boucle trop rapidement et dépassez ces limites, vous allez obtenir des messages d’erreur avec le code “429” avec le message : “Too many requests”. Attendez une minute que votre compteur redescende.

L’état de vos quotas est renvoyé dans le header de chaque réponse de l’API :

  • X-Rate-Limit-Limit : Votre limites d’appels par minutes sur cette API

  • X-Rate-Limit-Remaining : nombre d’appels restant jusqu’aux reset.

  • X-Rate-Limit-Reset : le timestamp de la date du prochain reset de votre quota (Unix timestamp en ms depuis le 1er janvier 1970 en UTC)

  • X-Quota-Limit : votre quota mensuel sur cette API

  • X-Quota-Remaining : votre quota restant

  • X-Quota-Reset : le timestamp de la date du prochain reset de votre quota (Unix timestamp en ms depuis le 1er janvier 1970 en UTC)

  • X-Max-Items-Per-Call : le nombre maximal d’éléments qu’un appel API peut retourner. Valide pour les routes /donnees/*

Par exemple :

from datetime import datetime
import requests

r = requests.get(f'https://api.bdnb.io/v1/bdnb/donnees/adresse', params={'limit': '15'})

print(f"Quota restant {r.headers['X-Rate-Limit-Remaining']} sur {r.headers['X-Rate-Limit-Limit']}. Date de réinitialisation du quota : {datetime.fromtimestamp(int(r.headers['X-Rate-Limit-Reset'])/1e3)} ")
#>> Quota restant : 119 sur 120. Date de réinitialisation du quota : 2024-01-11 17:01:35.515000
Quota restant 91 sur 120. Date de réinitialisation du quota : 2026-07-10 13:00:49.622000 
print(f"Quota restant {r.headers['X-Quota-Remaining']} sur {r.headers['X-Quota-Limit']}. Date de réinitialisation du quota : {datetime.fromtimestamp(int(r.headers['X-Quota-Reset'])/1e3)} ")
#>> Quota restant 9991 sur 10000. Date de réinitialisation du quota : 2024-01-28 13:42:46.031000
Quota restant 9321 sur 10000. Date de réinitialisation du quota : 2026-07-29 14:25:43.789000 

Pour les abonnés ayant un compte sur le portail d’API, il est possible de consulter votre consommation par application et par routes : applications > {mon application} > analytics

open (pas de souscription) open+ expert
Quota (nombre d’appels / mois ) 10k 1M 10M
Rate limit (nombre d’appels / min ) 120 /min 1200 /min 1200 /min
Nombre maximum d’objets retournés par requête 10 1000 10000

Connaitre les données disponibles dans une route /metadonnees :

La route de métadonnées suits la même syntaxe, bien qu’elle dispose d’une limite plus grande sur le nombre d’objets retournés.

import pandas as pd
import requests 
r = requests.get(f'https://api.bdnb.io/v1/bdnb/metadonnees',
                 params={'select': 'nom_colonne, nom_table, route, description',                         
                         'route': 'eq./v1/bdnb/donnees/batiment_groupe'
                         }                                               
                 )
print(pd.DataFrame(r.json()).to_markdown())
|    | nom_colonne                  | nom_table       | route                            | description                                                            |
|---:|:-----------------------------|:----------------|:---------------------------------|:-----------------------------------------------------------------------|
|  0 | batiment_groupe_id           | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | batiment_groupe_id (BDNB name: batiment_groupe_id)                     |
|  1 | batiment_groupe_id           | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | batiment_groupe_id (BDNB name: batiment_groupe_id)                     |
|  2 | code_commune_insee           | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_commune_insee (BDNB name: code_commune_insee)                     |
|  3 | code_commune_insee           | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_commune_insee (BDNB name: code_commune_insee)                     |
|  4 | code_departement_insee       | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_departement_insee (BDNB name: code_departement_insee)             |
|  5 | code_departement_insee       | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_departement_insee (BDNB name: code_departement_insee)             |
|  6 | code_epci_insee              | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_epci_insee (BDNB name: code_epci_insee)                           |
|  7 | code_epci_insee              | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_epci_insee (BDNB name: code_epci_insee)                           |
|  8 | code_iris                    | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_iris (BDNB name: code_iris)                                       |
|  9 | code_iris                    | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_iris (BDNB name: code_iris)                                       |
| 10 | code_qp                      | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_qp (BDNB name: code_qp)                                           |
| 11 | code_qp                      | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_qp (BDNB name: code_qp)                                           |
| 12 | code_region_insee            | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_region_insee (BDNB name: code_region_insee)                       |
| 13 | code_region_insee            | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | code_region_insee (BDNB name: code_region_insee)                       |
| 14 | commune_parente              | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | commune_parente (BDNB name: commune_parente)                           |
| 15 | commune_parente              | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | commune_parente (BDNB name: commune_parente)                           |
| 16 | contient_fictive_geom_groupe | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | contient_fictive_geom_groupe (BDNB name: contient_fictive_geom_groupe) |
| 17 | contient_fictive_geom_groupe | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | contient_fictive_geom_groupe (BDNB name: contient_fictive_geom_groupe) |
| 18 | geom_groupe                  | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | geom_groupe (BDNB name: geom_groupe)                                   |
| 19 | geom_groupe                  | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | geom_groupe (BDNB name: geom_groupe)                                   |
| 20 | geom_groupe_pos_wgs84        | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | geom_groupe_pos_wgs84 (BDNB name: geom_groupe_pos_wgs84)               |
| 21 | geom_groupe_pos_wgs84        | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | geom_groupe_pos_wgs84 (BDNB name: geom_groupe_pos_wgs84)               |
| 22 | libelle_commune_insee        | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | libelle_commune_insee (BDNB name: libelle_commune_insee)               |
| 23 | libelle_commune_insee        | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | libelle_commune_insee (BDNB name: libelle_commune_insee)               |
| 24 | nom_qp                       | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | nom_qp (BDNB name: nom_qp)                                             |
| 25 | nom_qp                       | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | nom_qp (BDNB name: nom_qp)                                             |
| 26 | quartier_prioritaire         | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | quartier_prioritaire (BDNB name: quartier_prioritaire)                 |
| 27 | quartier_prioritaire         | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | quartier_prioritaire (BDNB name: quartier_prioritaire)                 |
| 28 | s_geom_groupe                | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | s_geom_groupe (BDNB name: s_geom_groupe)                               |
| 29 | s_geom_groupe                | batiment_groupe | /v1/bdnb/donnees/batiment_groupe | s_geom_groupe (BDNB name: s_geom_groupe)                               |
nom_colonne nom_table route description
0 batiment_groupe_id batiment_groupe /v1/bdnb/batiment_groupe (bdnb) Identifiant du bâtiment au sens de la BDNB
1 code_commune_insee batiment_groupe /v1/bdnb/batiment_groupe (insee) Identifiant INSEE de la commune dans laquelle se trouve le bâtiment
2 code_departement_insee batiment_groupe /v1/bdnb/batiment_groupe (insee) Code département
3 code_epci_insee batiment_groupe /v1/bdnb/batiment_groupe (insee) Identifiant INSEE de l’EPCI dans laquelle se trouve le bâtiment
4 code_iris batiment_groupe /v1/bdnb/batiment_groupe (insee) Identifiant de l’iris sur lequel est présent le bâtiment
5 code_qp batiment_groupe /v1/bdnb/batiment_groupe Code quartier prioritaire de la ville
6 code_region_insee batiment_groupe /v1/bdnb/batiment_groupe Numéro et ID de la région
7 contient_fictive_geom_groupe batiment_groupe /v1/bdnb/batiment_groupe (bdnb) la géométrie du bâtiment groupe est générée automatiquement et ne représente pas réellement la géométrie du batiment_groupe
8 geom_groupe batiment_groupe /v1/bdnb/batiment_groupe (bdnb) géométrie du groupe de batiment
9 libelle_commune_insee batiment_groupe /v1/bdnb/batiment_groupe (insee) Libelle de la commune du batiment
10 nom_qp batiment_groupe /v1/bdnb/batiment_groupe Nom du quartier prioritaire de la ville
11 quartier_prioritaire batiment_groupe /v1/bdnb/batiment_groupe Est un quartier prioritaire
12 s_geom_groupe batiment_groupe /v1/bdnb/batiment_groupe (bdnb) Surface au sol de la géométrie du bâtiment groupe (geom_groupe)

Il est ainsi possible de chercher par nom de colonne, nom de table, nom de route, y compris sur les métadonnées elles-mêmes :

import pandas as pd
import requests 
r = requests.get(f'https://api.bdnb.io/v1/bdnb/metadonnees',
                 params={ 'select': 'nom_colonne, nom_table, route, description',   
                          'limit':10,         
                         'route': 'like./v1/bdnb/metadonnees%'
                         }                 
                 )
print(pd.DataFrame(r.json()).to_markdown())
|    | nom_colonne      | nom_table                    | route                                             | description                                    |
|---:|:-----------------|:-----------------------------|:--------------------------------------------------|:-----------------------------------------------|
|  0 | acronyme         | fournisseur                  | /v1/bdnb/metadonnees/fournisseur                  | acronyme (BDNB name: acronyme)                 |
|  1 | acronyme         | fournisseur                  | /v1/bdnb/metadonnees/fournisseur                  | acronyme (BDNB name: acronyme)                 |
|  2 | code             | autocompletion_entites_texte | /v1/bdnb/metadonnees/autocompletion_entites_texte | code (BDNB name: code)                         |
|  3 | api_open         | colonne                      | /v1/bdnb/metadonnees/colonne                      | api_open (BDNB name: api_open)                 |
|  4 | api_open         | colonne                      | /v1/bdnb/metadonnees/colonne                      | api_open (BDNB name: api_open)                 |
|  5 | api_expert       | colonne                      | /v1/bdnb/metadonnees/colonne                      | api_expert (BDNB name: api_expert)             |
|  6 | api_expert       | colonne                      | /v1/bdnb/metadonnees/colonne                      | api_expert (BDNB name: api_expert)             |
|  7 | contrainte_acces | contrainte_acces             | /v1/bdnb/metadonnees/contrainte_acces             | contrainte_acces (BDNB name: contrainte_acces) |
|  8 | contrainte_acces | contrainte_acces             | /v1/bdnb/metadonnees/contrainte_acces             | contrainte_acces (BDNB name: contrainte_acces) |
|  9 | code             | autocompletion_entites_texte | /v1/bdnb/metadonnees/autocompletion_entites_texte | code (BDNB name: code)                         |
nom_colonne nom_table route description
0 colonne_gorenove_legacy metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Nom de la colonne dans l’ancienne API gorenove /v2/gorenove/buildings
1 contrainte_acces metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Contrainte d’accès de la colonne
2 contrainte_acces_table metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Contrainte d’accès de la table
3 couverture_spatiale metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Couverture spatiale du jeu de données
4 couverture_temporelle metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Couverture temporelle du jeu de données
5 date_publication metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Date de publication du jeu de données
6 denomination_serie metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Dénomination du jeu de données
7 description metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Description de la table
8 description_jeu_de_donnees metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Description du jeu de données
9 description_public metadonnees_complet /v1/bdnb/metadonnees/metadonnees_complet Description à destination du grand public

Utiliser une clef d’API :

Pour utiliser la clef d’API (disponible dans votre espace Applications -> souscriptions)

import requests
r = requests.get(f'https://api.bdnb.io/v1/bdnb/stats/batiment_groupe?',
                    params= {
                            'colonnes': 'nb_batiment,annee_construction',   # select 
                            'groupby': 'code_iris', 
                            'filter': '{ "code_epci_insee": "eq.200067049"}', 
                            },
                    headers= {"X-Gravitee-Api-Key": "ma-clef-d-api-secrete"} )
code_commune_insee nb_batiment annee_construction_avant1848 annee_construction_de1848_a1900 annee_construction_de1900_a1920 annee_construction_de1920_a1948 annee_construction_de1948_a1960 annee_construction_de1960_a1970 annee_construction_de1970_a1980 annee_construction_de1980_a1990 annee_construction_de1990_a2000 annee_construction_de2000_a2010 annee_construction_de2010_a2018 annee_construction_apres2018 annee_construction_indisponible
0 2A014 59 10 7 1 3 1 1 1 3 0 1 2 1 28
1 2A019 187 48 20 3 2 1 5 5 0 0 1 5 0 97
2 2A022 144 22 14 3 0 1 2 3 7 8 5 1 1 77
3 2A027 195 35 23 7 13 4 5 3 1 0 4 6 0 94
4 2A028 327 43 39 6 8 3 3 14 14 21 1 8 0 167
5 2A048 746 64 21 8 18 14 30 69 64 58 66 50 1 283
6 2A060 105 11 16 6 4 0 2 5 4 2 3 1 0 51
7 2A065 1561 167 50 23 17 14 68 141 109 71 82 72 10 737
8 2A070 552 29 17 10 15 7 25 50 32 31 45 29 0 262
9 2A090 832 74 25 9 12 9 39 105 51 67 61 24 6 350
10 2A100 131 34 25 6 7 1 1 0 4 0 3 4 1 45
11 2A108 412 89 33 11 27 11 24 23 16 10 14 7 2 145
12 2A131 375 120 43 7 19 5 9 10 14 6 8 1 2 131
13 2A141 356 77 47 23 32 0 7 12 13 3 7 3 2 130
14 2A144 234 36 24 11 15 5 7 11 10 8 3 3 0 101
15 2A154 330 91 32 9 5 6 0 17 15 13 5 5 2 130
16 2A174 236 28 37 6 6 2 5 13 12 3 2 8 0 114
17 2A196 178 54 17 3 6 0 4 6 1 1 2 2 2 80
18 2A197 297 22 13 21 14 2 9 7 27 16 11 9 0 146
19 2A198 548 25 91 13 20 18 34 26 22 15 16 19 2 247
20 2A203 226 9 9 15 9 4 25 25 24 3 2 3 1 97
21 2A204 339 97 30 19 21 12 3 8 3 4 0 2 4 136
22 2A212 719 127 40 13 17 11 15 20 62 38 34 27 12 303
23 2A240 222 25 17 7 11 5 6 10 7 12 6 1 0 115
24 2A258 338 89 39 9 2 1 2 7 19 18 4 4 2 142
25 2A259 161 30 18 12 10 1 0 5 4 0 5 5 0 71
26 2A262 201 39 29 7 7 2 3 4 5 5 3 2 0 95
27 2A266 240 49 26 12 14 4 5 6 13 4 3 2 1 101
28 2A270 417 93 22 11 11 3 3 21 12 15 17 16 4 189
29 2A279 225 16 27 10 6 0 3 29 18 8 6 6 0 96
30 2A282 319 81 36 11 7 3 11 18 5 5 8 4 1 129
31 2A295 190 32 4 0 5 0 1 4 8 9 9 38 3 77
32 2A348 1308 166 45 23 21 19 56 97 105 58 66 80 16 556
import requests
import pandas as pd

r =  requests.get(f'https://api.bdnb.io/v1/bdnb/autocompletion',
                  params  = {'search_term':'talant',
                            'select':'nom, code, type_entite, origine_nom, origine_code, similarity'},
                   headers= {"X-Gravitee-Api-Key": "ma-clef-d-api-secrete"},
                 )
r.json()
#print(pd.DataFrame(r.json()).to_markdown())
{'message': 'Unauthorized', 'http_status_code': 401}
nom code type_entite origine_nom origine_code similarity
0 Talant 21617 commune commune.libelle_commune commune.code_commune_insee 1
1 Étalante 21253 commune commune.libelle_commune commune.code_commune_insee 0.333333
2 Vieux Talant-Clinique 216170101 iris iris.libelle_iris iris.code_iris 0.318182
3 MR TALANT 811895945 proprietaire proprietaire.denomination proprietaire.siren 0.7
4 SCI TALANT 800778656 proprietaire proprietaire.denomination proprietaire.siren 0.636364
5 SCI TALANT KINE 798681052 proprietaire proprietaire.denomination proprietaire.siren 0.4375
6 MONTALANT 422823096 proprietaire proprietaire.denomination proprietaire.siren 0.416667
7 TALANT LES FASSOLES 451354179 proprietaire proprietaire.denomination proprietaire.siren 0.388889