Pour essayer les exemples présents dans ce tutoriel :
1 Introduction : Qu’est-ce qu’une API ?
Nous avons vu dans les chapitres précédents comment consommer des données depuis un fichier (le mode d’accès le plus simple) ou comment récupérer des données par le biais du webscraping, une méthode qui permet à Python de singer le comportement d’un navigateur web et de récupérer de l’information en moissonnant le HTML auquel accède un site web.
Le webscraping est un pis-aller pour accéder à de la donnée. Heureusement, il existe d’autres manières d’accéder à des données : les API de données. En informatique, une API est un ensemble de protocoles permettant à deux logiciels de communiquer entre eux. Par exemple, on parle parfois d’API Pandas ce qui désigne le fait que Pandas est une interface entre votre code Python et un langage compilé plus efficace (C) qui fait les calculs que vous demandez au niveau de Python. L’objectif d’une API est ainsi de fournir un point d’accès à une fonctionnalité qui soit facile à utiliser et qui masque les détails de la mise en oeuvre.
Dans ce chapitre, nous nous intéressons principalement aux API de données. Ces dernières sont simplement une façon de mettre à disposition des données : plutôt que de laisser l’utilisateur consulter directement des bases de données (souvent volumineuses et complexes), l’API lui propose de formuler une requête qui est traitée par le serveur hébergeant la base de données, puis de recevoir des données en réponse à sa requête.
L’utilisation accrue d’API dans le cadre de stratégies open-data est l’un des piliers des 15 feuilles de route ministérielles françaises en matière d’ouverture, de circulation et de valorisation des données publiques.
Note
Depuis quelques années, un service officiel de géocodage a été mis en place pour le territoire français. Celui-ci est gratuit et permet de manière efficace de coder des adresses à partir d’une API. Cette API, connue sous le nom de la Base d’Adresses Nationale (BAN) a bénéficié de la mise en commun de données de plusieurs acteurs (collectivités locales, Poste, IGN) et de compétences d’acteurs comme Etalab. La documentation de celle-ci est disponible à l’adresse https://api.gouv.fr/les-api/base-adresse-nationale.
On prend souvent comme exemple pour illustrer les API l’exemple du restaurant. La documentation est votre menu : elle liste les plats (les bases de données) que vous pouvez commander et les éventuels ingrédients de celle-ci que vous pouvez choisir (les paramètres de votre requête) : poulet, boeuf ou option végé ? Lorsque vous faites ceci, vous ne connaissez pas la recette utilisée en arrière cuisine pour faire votre plat: vous recevez seulement celui-ci. De manière logique, plus le plat que vous avez demandé est raffiné (calculs complexes côté serveur), plus votre plat mettra du temps à vous arriver.
Illustration avec l’API BAN
Pour illustrer ceci, imaginons ce qu’il se passe lorsque, dans la suite du chapitre, nous ferons des requêtes à l’API BAN.
Via Python, on envoie notre commande à celle-ci: des adresses plus ou moins complètes avec des instructions annexes comme le code commune. Ces instructions annexes peuvent s’apparenter à des informations fournies au serveur du restaurant comme des interdits alimentaires qui vont personnaliser la recette.
A partir de ces instructions, le plat est lancé. En l’occurrence, il s’agit de faire tourner sur les serveurs d’Etalab une routine qui va chercher dans un référentiel d’adresse celle qui est la plus similaire à celle qu’on a demandé en adaptant éventuellement en fonction des instructions annexes qu’on a fourni. Une fois que côté cuisine on a fini cette préparation, on renvoie le plat au client. En l’occurrence, le plat sera des coordonnées géographiques qui correspondent à l’adresse la plus similaire.
Le client n’a donc qu’à se préoccuper de faire une bonne requête et d’apprécier le plat qui lui est fourni. L’intelligence dans la mise en oeuvre est laissée aux spécialistes qui ont conçu l’API. Peut-être que d’autres spécialistes, par exemple Google Maps, mettent en oeuvre une recette différente pour ce même plat (des coordonnées géographiques) mais ils vous proposeront probablement un menu très similaire. Ceci vous simplifie beaucoup la vie: il vous suffit de changer quelques lignes de code d’appel à une API plutôt que de modifier un ensemble long et complexe de méthodes d’identification d’adresses.
Approche pédagogique
Après une première présentation du principe général des API, ce chapitre illustre l’usage de celles-ci via Python par le biais d’un use case assez standard: on dispose d’un jeu de données qu’on désire d’abord géolocaliser. Pour cela, on va demander à une API de nous renvoyer des coordonnées géographiques à partir d’adresses. Ensuite on ira chercher des informations un peu plus complexes par le biais d’autres API.
2 Première utilisation d’API
Une API a donc vocation à servir d’intermédiaire entre un client et un serveur. Ce client peut être de deux types: une interface web ou un logiciel de programmation. L’API ne fait pas d’a priori sur l’outil qui sert lui passe une commande, elle lui demande seulement de respecter un standard (en général une requête http), une structure de requête (les arguments) et d’attendre le résultat.
2.1 Comprendre le principe avec un exemple interactif
Le premier mode (accès par un navigateur) est principalement utilisé lorsqu’une interface web permet à un utilisateur de faire des choix afin de lui renvoyer des résultats correspondant à ceux-ci. Prenons à nouveau l’exemple de l’API de géolocalisation que nous utiliserons dans ce chapitre. Imaginons une interface web permettant à l’utilisateur deux choix: un code postal et une adresse. Cela sera injecté dans la requête et le serveur répondra avec la géolocalisation adaptée.
Voici donc nos deux widgets pour permettre au client (l’utilisateur de la page web) de choisir son adresse.
Définition 2.1
Une petite mise en forme des valeurs renseignées par ce widget permet d’obtenir la requête voulue:
Ce qui nous donne un output au format JSON, le format de sortie d’API le plus commun.
Si on veut un beau rendu, comme la carte ci-dessus, il faudra que le navigateur retravaille cet output, ce qui se fait normalement avec Javascript, le langage de programmation embarqué par les navigateurs.
2.3 Comment connaître les inputs et outputs des API ?
Ici on a pris l’API BAN comme un outil magique dont on connaissait les principaux inputs (l’endpoint, les paramètres et leur formattage…). Mais comment faire, en pratique, pour en arriver là ? Tout simplement en lisant la documentation lorsqu’elle existe et en testant celle-ci via des exemples.
Les bonnes API proposent un outil interactif qui s’appelle le swagger. C’est un site web interactif où sont décrites les principales fonctionnalités de l’API et où l’utilisateur peut tester des exemples interactivement. Ces documentations sont souvent créées automatiquement lors de la construction d’une API et mises à disposition par le biais d’un point d’entrée /docs. Elles permettent souvent d’éditer certains paramètres dans le navigateur, voir le JSON obtenu (ou l’erreur générée) et récupérer la requête formattée qui permet d’obtenir celui-ci. Ces consoles interactives dans le navigateur permettent de répliquer le tâtonnement qu’on peut faire par ailleurs dans des outils spécialisés comme postman.
Concernant l’API BAN, la documentation se trouve sur https://adresse.data.gouv.fr/api-doc/adresse. Elle n’est pas interactive, malheureusement. Mais elle présente de nombreux exemples qui peuvent être testés directement depuis le navigateur. Il suffit d’utiliser les URL proposées comme exemple. Ceux-ci sont présentés par le biais de curl (un équivalent de requests en ligne de commande Linux):
curl "https://api-adresse.data.gouv.fr/search/?q=8+bd+du+port&limit=15"Il suffit de copier l’URL en question (https://api-adresse.data.gouv.fr/search/?q=8+bd+du+port&limit=15), d’ouvrir un nouvel onglet et vérifier que cela produit bien un résultat. Puis de changer un paramètre et vérifier à nouveau, jusqu’à trouver la structure qui convient. Et après, on peut passer à Python comme le propose l’exercice suivant.
2.4 Application
Pour commencer cet exercice, vous aurez besoin de cette variable:
adresse = "88 Avenue Verdier"
Exercice 1: Structurer un appel à une API depuis Python
- Tester sans aucun autre paramètre, le retour de notre API. Transformer en
DataFramele résultat. - Se restreindre à Montrouge avec le paramètre ad hoc et la recherche du code insee ou code postal adéquat sur google.
- (Optionnel): Représenter l’adresse trouvée sur une carte
Les deux premières lignes du dataframe obtenu à la question 1 devraient être
| label | score | housenumber | id | banId | name | postcode | citycode | x | y | city | context | type | importance | street | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 88 Avenue Verdier 92120 Montrouge | 0.973564 | 88 | 92049_9625_00088 | 92dd3c4a-6703-423d-bf09-fc0412fb4f89 | 88 Avenue Verdier | 92120 | 92049 | 649270.67 | 6857572.24 | Montrouge | 92, Hauts-de-Seine, Île-de-France | housenumber | 0.7092 | Avenue Verdier |
| 1 | Avenue Verdier 44500 La Baule-Escoublac | 0.719373 | NaN | 44055_3690 | NaN | Avenue Verdier | 44500 | 44055 | 291884.83 | 6701220.48 | La Baule-Escoublac | 44, Loire-Atlantique, Pays de la Loire | street | 0.6006 | Avenue Verdier |
A la question 2, on ressort cette fois qu’une seule observation, qu’on pourrait retravailler avec GeoPandas pour vérifier qu’on a bien placé ce point sur une carte
| label | score | housenumber | id | banId | name | postcode | citycode | x | y | city | context | type | importance | street | _type | geometry | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 88 Avenue Verdier 92120 Montrouge | 0.973564 | 88 | 92049_9625_00088 | 92dd3c4a-6703-423d-bf09-fc0412fb4f89 | 88 Avenue Verdier | 92120 | 92049 | 649270.67 | 6857572.24 | Montrouge | 92, Hauts-de-Seine, Île-de-France | housenumber | 0.7092 | Avenue Verdier | address | POINT (2.30914 48.81622) |
Enfin, à la question 3, on obtient cette carte (plus ou moins la même que précédemment):
Make this Notebook Trusted to load map: File -> Trust Notebook
Quelques API à connaître
Les principaux fournisseurs de données officielles proposent des API. C’est le cas notamment de l’Insee, d’Eurostat, de la BCE, de la FED, de la Banque Mondiale…
Néanmoins, la production de données par les institutions étatiques est loin d’être restreinte aux producteurs de statistiques publiques. Le portail API gouv est le point de référencement principal pour les API produites par l’administration centrale française ou des administrations territoriales. De nombreuses villes publient également des données sur leurs infrastructures par le biais d’API, par exemple la ville de Paris.
Les producteurs de données privées proposent également des API. Par exemple, la SNCF ou la RATP proposent des API pour certains usages. Les grands acteurs du numérique, par exemple Spotify proposent généralement des API pour intégrer certains de leurs services à des applications externes.
Cependant, il faut être conscient des limites de certaines API. En premier lieu, les données partagées ne sont pas forcément très riches pour ne pas compromettre la confidentialité des informations partagées par les utilisateurs du service ou la part de marché du producteur qui n’a pas intérêt à vous partager ses données à forte valeur. Il faut également être conscient du fait qu’une API peut disparaître ou changer de structure du jour au lendemain. Les codes de restructuration de données étant assez adhérents à une structure d’API, on peut se retrouver à devoir changer un volume conséquent de code si une API critique change substantiellement.
3 Plus d’exemples de requêtes GET
3.1 Source principale
Nous allons utiliser comme base principale pour ce tutoriel la base permanente des équipements, un répertoire d’équipements publics accueillant du public.
On va commencer par récupérer les données qui nous intéressent. On ne récupère pas toutes les variables du fichier mais seulement celles qu’ils nous intéressent: quelques variables sur l’équipement, son adresse et sa commune d’appartement.
Nous allons nous restreindre aux établissements d’enseignement primaire, secondaire et supérieur du département de la Haute-Garonne (le département 31). Ces établissements sont identifiés par un code particulier, entre C1 et C5.
import duckdb
query = """
FROM read_parquet('https://minio.lab.sspcloud.fr/lgaliana/diffusion/BPE23.parquet')
SELECT NOMRS, NUMVOIE, INDREP, TYPVOIE, LIBVOIE,
CADR, CODPOS, DEPCOM, DEP, TYPEQU,
concat_ws(' ', NUMVOIE, INDREP, TYPVOIE, LIBVOIE) AS adresse, SIRET
WHERE DEP = '31'
AND starts_with(TYPEQU, 'C')
AND NOT (starts_with(TYPEQU, 'C6') OR starts_with(TYPEQU, 'C7'))
"""
bpe = duckdb.sql(query)
bpe = bpe.to_df()3.2 Récupérer des données à façon grâce aux API
Nous avons vu précédemment le principe général d’une requête d’API. Pour illustrer, de manière plus massive, la récupération de données par le biais d’une API, essayons de récupérer des données complémentaires à notre source principale. Nous allons utiliser l’annuaire de l’éducation qui fournit de nombreuses informations sur les établissements scolaires. Nous utiliserons le SIRET pour croiser les deux sources de données.
L’exercice suivant viendra illustrer l’intérêt d’utiliser une API pour avoir des données à façon et la simplicité à récupérer celles-ci via Python. Néanmoins, cet exercice illustrera également une des limites de certaines API, à savoir la volumétrie des données à récupérer.
Exercice 2
- Visiter le swagger de l’API de l’Annuaire de l’Education nationale sur api.gouv.fr/documentation et tester une première récupération de données en utilisant le endpoint
recordssans aucun paramètre. - Puisqu’on n’a conservé que les données de la Haute Garonne dans notre base principale, on désire ne récupérer que les établissements de ce département par le biais de notre API. Faire une requête avec le paramètre ad hoc, sans en ajouter d’autres.
- Augmenter la limite du nombre de paramètres, voyez-vous le problème ?
- On va tenter de récupérer ces données par le biais de l’API tabular de
data.gouv. Sa documentation est ici et l’identifiant de la ressource estb22f04bf-64a8-495d-b8bb-d84dbc4c7983(source). Avec l’aide de la documentation, essayer de récupérer des données par le biais de cette API en utilisant le paramètreCode_departement__exact=031pour ne garder que le département d’intérêt. - Voyez-vous le problème et comment nous pourrions automatiser la récupération de données ?
La première question nous permet de récupérer un premier jeu de données
| identifiant_de_l_etablissement | nom_etablissement | type_etablissement | statut_public_prive | adresse_1 | adresse_2 | adresse_3 | code_postal | code_commune | nom_commune | ... | libelle_nature | code_type_contrat_prive | pial | etablissement_mere | type_rattachement_etablissement_mere | code_circonscription | code_zone_animation_pedagogique | libelle_zone_animation_pedagogique | code_bassin_formation | libelle_bassin_formation | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 0010953F | Ecole primaire | Ecole | Public | Grande rue | None | 01150 SAULT BRENAZ | 01150 | 01396 | Sault-Brénaz | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | 0010026Y | None | None | 0010064P | None | None | 10013 | AIN SUD |
| 1 | 0021328H | Ecole élémentaire L Lagrange / CA Demoustier | Ecole | Public | Rue Léo Lagrange | None | 02600 VILLERS COTTERETS | 02600 | 02810 | Villers-Cotterêts | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | 0021688Z | None | None | 0022137M | None | None | 20029 | SUD-AISNE |
2 rows × 72 columns
Néanmoins, on a deux problèmes : le nombre de lignes et le département d’intérêt. Essayons déjà avec la question 2 de changer ce dernier.
| identifiant_de_l_etablissement | nom_etablissement | type_etablissement | statut_public_prive | adresse_1 | adresse_2 | adresse_3 | code_postal | code_commune | nom_commune | ... | libelle_nature | code_type_contrat_prive | pial | etablissement_mere | type_rattachement_etablissement_mere | code_circonscription | code_zone_animation_pedagogique | libelle_zone_animation_pedagogique | code_bassin_formation | libelle_bassin_formation | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 0313237A | Ecole primaire publqiue Claire Roman | Ecole | Public | Chemin du château d'eau | None | 31600 SEYSSES | 31600 | 31547 | Seysses | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | None | None | None | 0312628N | None | None | None | None |
| 1 | 0310212M | Ecole maternelle publique André Daste | Ecole | Public | 29 rue de Toulon | None | 31400 TOULOUSE | 31400 | 31555 | Toulouse | ... | ECOLE MATERNELLE | 99 | 0311338L | None | None | 0312793T | None | None | 16109 | TOULOUSE CENTRE |
| 2 | 0311923X | Ecole élémentaire publique Montaudran | Ecole | Public | Impasse Gaston Génin | None | 31400 TOULOUSE | 31400 | 31555 | Toulouse | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | 0310085Z | None | None | 0312825C | None | None | 16128 | TOULOUSE EST |
| 3 | 0312312V | Ecole maternelle publique Léonard de Vinci | Ecole | Public | Allée de l'Europe | None | 31840 SEILH | 31840 | 31541 | Seilh | ... | ECOLE MATERNELLE | 99 | 0312423R | None | None | 0312602K | None | None | 16110 | TOULOUSE NORD |
| 4 | 0310302K | Ecole élémentaire publique Gaston Bonheur | Ecole | Public | 2 rue de Noncesse | None | 31130 BALMA | 31130 | 31044 | Balma | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | 0312698P | None | None | 0311101D | None | None | 16110 | TOULOUSE NORD |
5 rows × 72 columns
C’est mieux, mais nous avons toujours seulement 10 observations. Si on essaie d’ajuster le nombre de lignes (question 3), on obtient le retour suivant de l’API :
b'{\n "error_code": "InvalidRESTParameterError",\n "message": "Invalid value for limit API parameter: 200 was found but -1 <= limit <= 100 is expected."\n}'Essayons avec des données plus exhaustives : le fichier brut sur data.gouv. Comme on peut le voir dans les métadonnées, on sait qu’on a plus de 1000 écoles dont on peut récupérer des données, mais qu’on en a ici extrait seulement 20. Le champ next nous donne directement l’URL à utiliser pour récupérer les 20 pages suivantes : c’est grâce à lui qu’on a une chance de récupérer toutes nos données d’intérêt.
La partie intéressante pour automatiser la récupération de nos données est la clé links du JSON :
{'profile': 'https://tabular-api.data.gouv.fr/api/resources/b22f04bf-64a8-495d-b8bb-d84dbc4c7983/profile/',
'swagger': 'https://tabular-api.data.gouv.fr/api/resources/b22f04bf-64a8-495d-b8bb-d84dbc4c7983/swagger/',
'next': 'https://tabular-api.data.gouv.fr/api/resources/b22f04bf-64a8-495d-b8bb-d84dbc4c7983/data/?Code_departement__exact=031&page=2&page_size=20',
'prev': None}En bouclant sur celui-ci pour parcourir la liste des URL accessibles, on peut récupérer des données. Comme le code d’automatisation est assez fastidieux à écrire, le voici :
import requests
import pandas as pd
# Initialize the initial API URL
url_api_datagouv = "https://tabular-api.data.gouv.fr/api/resources/b22f04bf-64a8-495d-b8bb-d84dbc4c7983/data/?Code_departement__exact=031&page_size=50"
# Initialize an empty list to store all data entries
all_data = []
# Initialize the URL for pagination
current_url = url_api_datagouv
# Loop until there is no next page
while current_url:
try:
# Make a GET request to the current URL
response = requests.get(current_url)
response.raise_for_status() # Raise an exception for HTTP errors
# Parse the JSON response
json_response = response.json()
# Extract data and append to the all_data list
page_data = json_response.get('data', [])
all_data.extend(page_data)
print(f"Fetched {len(page_data)} records from {current_url}")
# Get the next page URL
links = json_response.get('links', {})
current_url = links.get('next') # This will be None if there's no next page
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
breakLe DataFrame obtenu est le suivant:
schools_dep31 = pd.DataFrame(all_data)
schools_dep31.head()| __id | Identifiant_de_l_etablissement | Nom_etablissement | Type_etablissement | Statut_public_prive | Adresse_1 | Adresse_2 | Adresse_3 | Code_postal | Code_commune | ... | libelle_nature | Code_type_contrat_prive | PIAL | etablissement_mere | type_rattachement_etablissement_mere | code_circonscription | code_zone_animation_pedagogique | libelle_zone_animation_pedagogique | code_bassin_formation | libelle_bassin_formation | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 454 | 0310164K | Ecole maternelle publique Marie Laurencin | Ecole | Public | Route de Lasbordes | None | 31130 BALMA | 31130 | 31044 | ... | ECOLE MATERNELLE | 99 | 0312698P | None | None | 0311101D | None | None | 16110 | TOULOUSE NORD |
| 1 | 455 | 0310172U | Ecole maternelle publique Jean Jaurès | Ecole | Public | Impasse des Ecoles | None | 31270 CUGNAUX | 31270 | 31157 | ... | ECOLE MATERNELLE | 99 | 0311093V | None | None | 0311105H | None | None | 16108 | TOULOUSE SUD-OUEST |
| 2 | 456 | 0310174W | Ecole maternelle publique | Ecole | Public | Rue des Ecoles | None | 31230 L ISLE EN DODON | 31230 | 31239 | ... | ECOLE MATERNELLE | 99 | 0310003K | None | None | 0311108L | None | None | 16106 | COMMINGES |
| 3 | 457 | 0310183F | Ecole maternelle publique le pilat | Ecole | Public | 1 rue du Dr Ferrand | None | 31800 ST GAUDENS | 31800 | 31483 | ... | ECOLE MATERNELLE | 99 | 0310083X | None | None | 0311108L | None | None | 16106 | COMMINGES |
| 4 | 458 | 0310200Z | Ecole maternelle publique Léo Lagrange | Ecole | Public | 35 allée Henri Sellier | None | 31400 TOULOUSE | 31400 | 31555 | ... | ECOLE MATERNELLE | 99 | 0311338L | None | None | 0312793T | None | None | 16109 | TOULOUSE CENTRE |
5 rows × 73 columns
On peut fusionner ces nouvelles données avec nos données précédentes pour enrichir celles-ci. Pour faire une production fiable, il faudrait faire attention aux écoles qui ne s’apparient pas, mais ce n’est pas grave pour cette série d’exercices.
bpe_enriched = bpe.merge(
schools_dep31,
left_on = "SIRET",
right_on = "SIREN_SIRET"
)
bpe_enriched.head(2)| NOMRS | NUMVOIE | INDREP | TYPVOIE | LIBVOIE | CADR | CODPOS | DEPCOM | DEP | TYPEQU | ... | libelle_nature | Code_type_contrat_prive | PIAL | etablissement_mere | type_rattachement_etablissement_mere | code_circonscription | code_zone_animation_pedagogique | libelle_zone_animation_pedagogique | code_bassin_formation | libelle_bassin_formation | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | ECOLE PRIMAIRE PUBLIQUE DENIS LATAPIE | LD | LA BOURDETTE | 31230 | 31001 | 31 | C108 | ... | ECOLE DE NIVEAU ELEMENTAIRE | 99 | 0310003K | None | None | 0311108L | None | None | 16106 | COMMINGES | |||
| 1 | ECOLE MATERNELLE PUBLIQUE | 21 | CHE | DE L AUTAN | 31280 | 31003 | 31 | C107 | ... | ECOLE MATERNELLE | 99 | 0311335H | None | None | 0311102E | None | None | 16128 | TOULOUSE EST |
2 rows × 85 columns
Cela nous donne des données enrichies de nouvelles caractéristiques sur les établissements. Il y a des coordonnées géographiques dans celles-ci, mais nous allons faire comme s’il n’y en avait pas pour réutiliser notre API de géolocalisation.
4 Découverte des requêtes POST
4.1 Logique
Nous avons jusqu’à présent évoqué les requêtes GET. Nous allons maintenant présenter les requêtes POST qui permettent d’interagir de manière plus complexe avec des serveurs de l’API.
Pour découvrir celles-ci, nous allons reprendre l’API de géolocalisation précédente mais utiliser un autre point d’entrée qui nécessite une requête POST.
Ces dernières sont généralement utilisées quand il est nécessaire d’envoyer des données particulières pour déclencher une action. Par exemple, dans le monde du web, si vous avez une authentification à mettre en oeuvre, une requête POST permettra d’envoyer un token au serveur qui répondra en acceptant votre authentification.
Dans notre cas, nous allons envoyer des données au serveur, ce dernier va les recevoir, les utiliser pour la géolocalisation puis nous envoyer une réponse. Pour continuer sur la métaphore culinaire, c’est comme si vous donniez vous-mêmes à la cuisine un tupperware pour récupérer votre plat à emporter.
4.2 Principe
Prenons cette requête proposée sur le site de documentation de l’API de géolocalisation:
curl -X POST -F data=@path/to/file.csv -F columns=voie -F columns=ville -F citycode=ma_colonne_code_insee https://api-adresse.data.gouv.fr/search/csv/Comme nous avons pu l’évoquer précédemment, curl est un outil en ligne de commande qui permet de faire des requêtes API. L’option -X POST indique, de manière assez transparente, qu’on désire faire une requête POST.
Les autres arguments sont passés par le biais des options -F. En l’occurrence, on envoie un fichier et on ajoute des paramètres pour aider le serveur à aller chercher la donnée dedans. L’@ indique que file.csv doit être lu sur le disque et envoyé dans le corps de la requête comme une donnée de formulaire.
4.3 Application avec Python
Nous avions requests.get, il est donc logique que nous ayons requests.post. Cette fois, il faudra passer des paramètres à notre requête sous la forme d’un dictionnaire dont les clés sont le nom de l’argument et les valeurs sont des objets Python.
Le principal défi, illustré dans le prochain exercice, est le passage de l’argument data: il faudra renvoyer le fichier comme un objet Python par le biais de la fonction open.
Exercice 3: une requête POST pour géolocaliser en masse nos données
- Enregistrer au format CSV les colonnes
adresse,DEPCOMetNom_communede la base d’équipements fusionnée avec notre répertoire précédent (objetbpe_enriched). Il peut être utile, avant l’écriture au format CSV, de remplacer les virgules dans la colonneadressepar des espaces. - Créer l’objet
responseavecrequests.postet les bons arguments pour géocoder votre CSV. - Transformer votre output en objet
geopandasavec la commande suivante:
bpe_loc = pd.read_csv(io.StringIO(response.text))Les géolocalisations obtenues prennent cette forme
| index | adresse | DEPCOM | Nom_commune | result_score | latitude | longitude | |
|---|---|---|---|---|---|---|---|
| 0 | 0 | LD LA BOURDETTE | 31001 | Agassac | 0.404609 | 43.374288 | 0.880679 |
| 1 | 1 | 21 CHE DE L AUTAN | 31003 | Aigrefeuille | 0.730293 | 43.567530 | 1.585745 |
En enrichissant les données précédentes, cela donne:
| NOMRS | NUMVOIE | INDREP | TYPVOIE | LIBVOIE | CADR | CODPOS | DEPCOM | DEP | TYPEQU | ... | etablissement_mere | type_rattachement_etablissement_mere | code_circonscription | code_zone_animation_pedagogique | libelle_zone_animation_pedagogique | code_bassin_formation | libelle_bassin_formation | result_score | latitude_ban | longitude_ban | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | ECOLE PRIMAIRE PUBLIQUE DENIS LATAPIE | LD | LA BOURDETTE | 31230 | 31001 | 31 | C108 | ... | None | None | 0311108L | None | None | 16106 | COMMINGES | 0.404609 | 43.374288 | 0.880679 | |||
| 1 | ECOLE MATERNELLE PUBLIQUE | 21 | CHE | DE L AUTAN | 31280 | 31003 | 31 | C107 | ... | None | None | 0311102E | None | None | 16128 | TOULOUSE EST | 0.730293 | 43.567530 | 1.585745 |
2 rows × 88 columns
On peut vérifier que la géolocalisation ne soit pas trop délirante en comparant avec les longitudes et latitudes de l’annuaire de l’éducation ajouté précédemment:
| NOMRS | Nom_commune | longitude_annuaire | longitude_ban | latitude_annuaire | latitude_ban | |
|---|---|---|---|---|---|---|
| 852 | ECOLE PRIMAIRE PRIVEE HC JEAN CALVIN | Toulouse | 1.406639 | 1.399550 | 43.564864 | 43.594497 |
| 1088 | ECOLE ELEMENTAIRE PUBLIQUE COMTESSE DE SEGUR | Verfeil | 1.663350 | 1.663512 | 43.659332 | 43.659041 |
| 333 | ECOLE MATERNELLE PUBLIQUE | L'Isle-en-Dodon | 0.838201 | 0.837643 | 43.381447 | 43.381244 |
| 86 | COLLEGE PRIVE LE FERRADOU | Blagnac | 1.386420 | 1.387580 | 43.654232 | 43.654765 |
| 217 | ECOLE 2D DEGRE GENERAL PRIVEE INTERNATIONAL SC... | Colomiers | 1.302909 | 1.303290 | 43.615003 | 43.615140 |
Sans rentrer dans le détail, les positions semblent très similaires à quelques imprécisions près.
Pour profiter de nos données enrichies, on peut faire une carte. Pour ajouter un peu de contexte à celle-ci, on peut mettre un fond de carte des communes en arrière plan. Celui-ci peut être récupéré avec cartiflette:
from cartiflette import carti_download
shp_communes = carti_download(
crs = 4326,
values = ["31"],
borders="COMMUNE",
vectorfile_format="topojson",
filter_by="DEPARTEMENT",
source="EXPRESS-COG-CARTO-TERRITOIRE",
year=2022
)
shp_communes.crs = 4326This is an experimental version of cartiflette published on PyPi.
To use the latest stable version, you can install it directly from GitHub with the following command:
pip install git+https://github.com/inseeFrLab/cartiflette.gitERROR 1: PROJ: proj_create_from_database: Open of /opt/conda/share/proj failedReprésentées sur une carte, cela donne la carte suivante:
Make this Notebook Trusted to load map: File -> Trust Notebook
2.2 Comment faire avec
Python?Le principe est le même sauf que nous perdons l’aspect interactif. Il s’agira donc, avec
Python, de construire l’URL voulue et d’aller chercher via une requête HTTP le résultat.Nous avons déjà vu dans le chapitre de webscraping la manière dont
Pythoncommunique avec internet: via le packagerequests. Ce package suit le protocole HTTP où on retrouve principalement deux types de requêtes:GETetPOST:GETest utilisée pour récupérer des données depuis un serveur web. C’est la méthode la plus simple et courante pour accéder aux ressources d’une page web. Nous allons commencer par décrire celle-ci.POSTest utilisée pour envoyer des données au serveur, souvent dans le but de créer ou de mettre à jour une ressource. Sur les pages web, elle sert souvent à la soumission de formulaires qui nécessitent de mettre à jour des informations sur une base (mot de passe, informations clients, etc.). Nous verrons son utilité plus tard, lorsque nous commencerons à rentrer dans les requêtes authentifiées où il faudra soumettre des informations supplémentaires à notre requête.Faisons un premier test avec
Pythonen faisant comme si nous connaissions bien cette API.Qu’est-ce qu’on obtient ? Un code HTTP. Le code 200 correspond aux requêtes réussies, c’est-à-dire pour lesquelles le serveur est en mesure de répondre. Si ce n’est pas le cas, pour une raison x ou y, vous aurez un code différent.
Les codes de statut HTTP sont des réponses standard envoyées par les serveurs web pour indiquer le résultat d’une requête effectuée par un client (comme un navigateur ou un script Python). Ils sont classés en différentes catégories selon le premier chiffre du code :
Ceux à retenir sont : 200 (succès), 400 (requête mal structurée), 401 (authentification non réussie), 403 (accès interdit), 404 (ressource demandée n’existe pas), 503 (le serveur n’est pas en capacité de répondre)
Pour récupérer le contenu renvoyé par
requests, il existe plusieurs méthodes. Quand on un JSON bien formatté, le plus simple est d’utiliser la méthodejsonqui transforme cela en dictionnaire :En l’occurrence, on voit que les données sont dans un JSON imbriqué. Il faut donc développer un peu de code pour récupérer les informations voulues dans celui-ci:
C’est là l’inconvénient principal de l’usage des API: le travail ex post sur les données renvoyées. Le code nécessaire est propre à chaque API puisque l’architecture du JSON dépend de chaque API.