Aller au contenu

Chapitre 1 : Interfaces de programmation d'applications⚓︎

Carnet Jupyter à télécharger ici

Une API (Application Programming Interface), ou une interface de programmation d’applications, est un ensemble de classes, fonctions, constantes grâce auquel un programme fournisseur met à disposition diverses fonctionnalités pour des programmes consommateurs.

C'est le programme fournisseur qui définit de quelle façon les fonctionnalités sont mises à disposition des consommateurs, en imposant éventuellement un certain nombre de contraintes d'accès à l'API.

On s'intéresse ici à la Base Adresse Nationale qui est une API gratuite du gouvernement français permettant d'obtenir un certain nombre d'informations à partir d'une adresse postale.

Interrogation de l'API⚓︎

On souhaite, grâce à l'API, obtenir des informations sur l'adresse postale du lycée Louis Armand. Pour interroger l'API, il suffit d'envoyer une requête GET à l'URL https://api-adresse.data.gouv.fr/search/?q=173-boulevard-de-strasbourg&postcode=94130.

On remarque que l'adresse postale sur laquelle on souhaite interroger l'API est indiquée dans l'URL. La réponse renvoyée par l'API est la suivante :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{"type": "FeatureCollection",
 "version": "draft",
 "features": [{"type": "Feature",
               "geometry": {"type": "Point",
                            "coordinates": [2.491306, 48.846716]},
               "properties": {"label": "173 Boulevard de Strasbourg 94130 Nogent-sur-Marne",
                              "score": 0.88381,
                              "housenumber": "173",
                              "id": "94052_8560_00173",
                              "name": "173 Boulevard de Strasbourg",
                              "postcode": "94130",
                              "citycode": "94052",
                              "x": 662668.4,
                              "y": 6860861.49,
                              "city": "Nogent-sur-Marne",
                              "context": "94, Val-de-Marne, Île-de-France",
                              "type": "housenumber",
                              "importance": 0.72191,
                              "street": "Boulevard de Strasbourg"}}],
 "attribution": "BAN",
 "licence": "ETALAB-2.0",
 "query": "173-boulevard-de-strasbourg",
 "filters": {"postcode": "94130"},
 "limit": 5}

La réponse reçue est au format JSON (JavaScript Object Notation). La signification des champs de la réponse est donnée dans la documentation de l'API.

L'interrogation de l'API peut être réalisée grâce au code Python ci-dessous. Lors de son exécution, la réponse renvoyée par l'API est stockée dans la variable reponse.

Implémentation

1
2
3
4
import requests
url = "https://api-adresse.data.gouv.fr/search/?q=173-boulevard-de-strasbourg&postcode=94130"
reponse = requests.get(url)
reponse = reponse.json()

La fonction get du module requests permet d'envoyer une requête GET à l'URL spécifiée et ensuite de récupérer la réponse.

La commande reponse.json() extrait de la réponse les données encodées dans le format JSON, qui est un format de données textuelles que l'on peut traiter comme s'il s'agissait d'un dictionnaire Python.

Traitement de la réponse renvoyée par l'API⚓︎

Il est possible de définir une fonction qui interroge l'API à partir d'une adresse postale au choix, passée en paramètre.

Fonction interroger_API_BAN

Interroge l'API Base Adresse Nationale.

Entrées

  • adresse : chaîne de caractères
  • code_postal : entier ou chaîne de caractères

Sortie

  • reponse : dictionnaire contenant l'ensemble des données renvoyées par l'API

Penser à importer le module requests !

Implémentation

1
2
3
4
5
def interroger_API_BAN(adresse, code_postal):
    url = f"https://api-adresse.data.gouv.fr/search/?q={adresse}&postcode={code_postal}"
    reponse = requests.get(url)
    reponse = reponse.json()
    return reponse

L'utilisation d'une f-string pour l'écriture de l'URL permet d'y intégrer simplement et lisiblement les paramètres d'entrée de la fonction.

Ici, la fonction renvoie l'ensemble des données récupérées via l'API. La plupart du temps, on souhaite néanmoins isoler les données qui nous intéressent et elles seules.

Fonction interroger_API_BAN

Renvoie les coordonnées géographiques d'un lieu après interrogation de l'API Base Adresse Nationale.

Entrées

  • adresse : chaîne de caractères
  • code_postal : entier ou chaîne de caractères

Sortie

  • (lat, long) : couple de coordonnées géographiques

Penser à importer le module requests !

Implémentation

1
2
3
4
5
6
7
8
def interroger_API_BAN(adresse, code_postal):
    url = f"https://api-adresse.data.gouv.fr/search/?q={adresse}&postcode={code_postal}"
    reponse = requests.get(url)
    reponse = reponse.json()
    coord = reponse['features'][0]['geometry']['coordinates']
    long = coord[0]
    lat = coord[1]
    return (lat, long)

Une fois la réponse de l'API transformée en dictionnaire, il suffit de naviguer pour récupérer les données qui nous intéressent, comme par exemple les coordonnées géographiques de l'adresse passée en paramètre.

  • reponse est un dictionnaire possédant huit clés : 'type', 'version', 'features', 'attribution', 'licence', 'query', 'filters' et 'limit'.
  • reponse['features'] est un tableau contenant un ou plusieurs éléments de type dictionnaire : chaque dictionnaire correspond à une adresse potentielle, la première (indice 0) étant la plus susceptible de correspondre à notre demande.
  • reponse['features'][0] est un dictionnaire possédant trois clés : 'type', 'geometry' et 'properties'.
  • reponse['features'][0]['geometry'] est un dictionnaire possédant deux clés : 'type' et 'coordinates'.
  • reponse['features'][0]['geometry']['coordinates'] est un tableau contenant deux éléments de type flottant : la longitude (indice 0) et la latitude (indice 1) du lieu.

Ce qu'il faut savoir et savoir faire⚓︎

  • Envoyer une requête à une API avec le module requests.
  • Sélectionner des informations dans la réponse renvoyée par une API.
  • Consulter la documentation d'une API.

Exercices et activités⚓︎

Exercices

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici

Activités

L'objectif de l'activité est d'utiliser une API pour réaliser une carte de vigilance météorologique.

Carte de vigilance météo du 26/12/1999 Carte de vigilance météo du 27/12/1999

Carnet Jupyter à télécharger ici

⚠️ Le fichier carte_france.py doit être placé dans le même répertoire que le carnet act_vigilance_meteo.ipynb.

Corrigé disponible ici

L'objectif de l'activité est d'utiliser une API pour cartographier les centres de vaccination anti-Covid d'un département.

Vaccination anti-Covid

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici

L'objectif de l'activité est d'utiliser une API pour suivre les déplacements de la station spatiale internationale.

Station spatiale internationale

Carnet Jupyter à travailler sur le site CAPYTALE ou à télécharger ici

Corrigé disponible ici