Utiliser l'API géographique du gouvernement

Dans l'application Papillon, lorsque vous vous connectez au service PRONOTE, vous avez la possibilité de rechercher l'URL de votre établissement en utilisant soit le nom de votre ville, soit son code postal.

Pour récupérer les établissements qui utilisent PRONOTE dans une certaine localisation, on utilise l'API non documentée d'Index-Education situé à l'adresse suivante : https://www.index-education.com/swie/geoloc.php

Cette API prend en paramètre la longitude et la latitude de la localisation que l'on recherche. Pour plus d'information, voir le code de Pawnote.

Cependant, comment peut-on récupérer la latitude et la longitude d'une ville dont on a seulement entré le nom ou le code postal ?

Le géocodage

Le procédé qui permet de convertir une adresse en coordonnées géographiques (latitude et longitude) est appelé le géocodage.

Il nous faut maintenant un service qui expose une API permettant de faire du géocodage en France.

La galère des APIs

Il existe de nombreux services proposant cette fonctionnalité, mais beaucoup d'entre eux ne sont pas adaptés à l'utilisation dans Papillon.

Voici quelques exemples de services que nous ne pouvons pas utiliser, car ils nécessitent un compte avec une clé API pour effectuer des requêtes, parfois avec des limitations sur les comptes gratuits :

• Bing Maps
• Google Maps
• OpenWeatherMap
• MapBox

...et d'autres encore.

Pourtant, cette fonctionnalité existe dans Papillon. Alors, quel service avons-nous finalement choisi ?

L'option gouvernementale

On oublie souvent que le gouvernement français offre un large éventail d'API accessibles gratuitement pour accéder à des données.

Ici, notre intérêt se porte sur l'API "geo", qui donne accès aux référentiels géographiques : https://geo.api.gouv.fr/

L'API que nous recherchons pour le géocodage est l'API Adresse.

Elle impose une limite de 50 appels par seconde par adresse IP, ce qui est largement suffisant, et aucune clé API n'est requise : exactement ce que nous recherchons !

Utilisation

Vu que cette API ne requiert aucune authentification au préalable et fonctionne directement, on peut tout simplement implémenter la requête vers l'API.

const query = "Limoges"; // La recherche que l'on veut faire.

const response = await fetch(`https://api-adresse.data.gouv.fr/search/?type=municipality&q=${encodeURIComponent(query)}`);

// La sortie est en JSON.
const json = await response.json(); 
// On affiche la liste des résultats.
console.log(json.features); 

// On prend le premier item des résultats, par exemple.
const item = json.features[0];
// On récupère les coordonnées.
const [longitude, latitude] = item.geometry.coordinates; 

// On affiche le résultat !
console.log(item.properties.name, "se situe à", longitude, latitude);
// >>> Limoges se situe à 1.221254 45.856159

Une fois les coordonnées récupérés, on peut les donner dans l'API d'Index-Education et récupérer la liste des établissements dans, cet exemple, Limoges.

import { findPronoteInstances, defaultPawnoteFetcher } from "pawnote";

const instances = await findPronoteInstances(defaultPawnoteFetcher, {
  // On utilise les coordonnées récupérées.
  latitude: 45.856159,
  longitude: 1.221254
});

console.log("Found", instances.length, "instances in the 20 km radius.");
// >>> Found 30 instances in the 20 km radius.

Conclusion

L'intégration de la fonction de localisation par recherche dans l'application Papillon a été réalisée en optant pour l'API gouvernementale qui offre des données précises sans nécessiter d'authentification préalable ni de clé API.

Cette solution a permis de simplifier le processus de géocodage et d'obtenir les coordonnées géographiques des villes recherchées de manière efficace pour permettre d'offrir une expérience utilisateur optimale.