FR:Taginfo/API

Taginfo dispose d'une API qui vous permet d'accéder au contenu de ses bases de données de plusieurs manières. L'API est utilisée en interne pour l'interface utilisateur web et peut également être utilisée par toute personne souhaitant intégrer des données taginfo dans ses sites web ou applications.

L'API est destinée à l'utilisation de la communauté OpenStreetMap. Ne l'utilisez pas pour d'autres services. Si vous n'êtes pas sûr, posez la question sur la liste de diffusion (voir ci-dessous).

Utilisez toujours un header avec un User-agent significatif avec suffisamment d'informations pour que nous puissions vous contacter en cas de problème.

Le serveur exécutant l'API taginfo ne dispose pas de ressources illimitées. Veuillez utiliser l'API de manière responsable. Ne créez pas d'énormes quantités de requêtes pour obtenir la base de données entière ou de gros morceaux de celle-ci, utilisez plutôt les téléchargements de base de données fournis. Si vous utilisez l'API et que vous trouvez qu'elle est lente, vous en abusez probablement.

Si vous utilisez l'API taginfo, il est recommandé de rejoindre la mailing list taginfo-dev. Des mises à jour de l'API y seront annoncées et c'est également le bon endroit pour poser vos questions.

Bases

L'API est une API HTTP RESTful. Toutes les demandes sont effectuées via des URL commençant par https://taginfo.openstreetmap.org/api/VERSION. La version 4 de l'API est celle à jour.

Tous les appels de l'API sont en lecture seule et utilisent la requête HTTP GET, tous les paramètres sont donnés dans l'URL comme d'habitude.

Tous les résultats de l'API sont au format JSON (à l'exception de quelques appels qui renvoient un PNG). Vous devez ignorer les noms (clés) inconnus dans les objets JSON, les nouvelles versions de l'API peuvent ajouter de nouveaux noms à n'importe quel objet sans incrémenter le numéro de version.

Pagination

De nombreux appels de l'API renvoient leurs données "page par page", de sorte que vous pouvez obtenir, par exemple, les 20 premiers résultats en une seule requête, puis les 20 suivants et ainsi de suite. Vous pouvez décider du nombre de résultats que vous souhaitez et de la "page" ou vous pouvez tout obtenir en même temps.

Si vous souhaitez paginer, ajoutez les paramètres page et rp (résultats par page) à l'URL. La première page porte le numéro 1. L'URL ressemblera donc à

https://taginfo.openstreetmap.org/api/VERSION/some/thing?rp=20&page=1&foo=bar

Les résultats de l'appel de l'API ressembleront à ceci :

{
  "total": 587, // le nombre total de résultats
  "page": 7, // le numéro de page (le même que dans votre demande)
  "rp": 20, // le nombre de résultats par page (comme dans votre demande)
  "url": "https: //taginfo.openstreetmap.org/api ..." // l'URL complète utilisée pour obtenir ce résultat
  "data": [...] // les données
}

Le tableau data contiendra les résultats réels de l'élément rp*(page-1) à rp*page -1.

Si vous ne voulez pas de pagination, n'ajoutez pas les paramètres page et rp, dans le résultat ces champs seront alors 0.

Tri

De nombreux appels de l'API prennent en charge le tri des résultats. Pour obtenir autre chose que le tri par défaut, vous pouvez ajouter les paramètres sortname et sortorder à l'URL. Chaque requête de l'API a différentes options pour sortname. L'ordre de tri peut être soit asc pour croissant ou desc pour décroissant.

Filtres

Certains appels de l'API ont un paramètre spécial filter qui vous permet de filtrer les résultats. Vous pouvez utiliser plusieurs filtres comme celui-ci: filter=FILTER1,FILTER2.

Voir les descriptions de "Filtre" dans l'API Documentation pour des informations sur les appels qui acceptent les filtres.

Exemple de code

L'outil simple tapi (https://github.com/joto/taginfo/blob/master/examples/tapi) peut être utilisé pour créer des requêtes API et pourrait vous aider à développer votre propre code d'accès à l'API.

Appels API

En général, il y a un appel API pour chaque table dans l'interface utilisateur web (c'est parce que ces tables sont remplies à partir des appels API). Parfois, les appels de l'API renvoient plus de champs de données que ceux affichés dans l'interface utilisateur.

Voir https://taginfo.openstreetmap.org/taginfo/apidoc pour une liste des appels d'API.

Problèmes XSS

Veuillez noter que les clés et valeurs de balises OSM peuvent contenir n'importe quel caractère UTF-8 valide, de même que les pages wiki. Lorsque vous utilisez l'API taginfo, il est toujours possible qu'elle renvoie des données contenant des caractères spéciaux. Veuillez vous assurer dans votre application que ces caractères sont gérés correctement.

JSON indenté

Vous pouvez ajouter le paramètre format=json_pretty pour obtenir une sortie JSON imprimée lisiblement avec des espaces et des retours à la ligne. La valeur par défaut est de compresser le JSON aussi étroitement que possible.

CORS et JSONP

Taginfo prend en charge le Cross-Origin Resource Sharing (CORS) en définissant l'entête Access-Control-Allow-Origin:* sur toutes les API les résultats des appels. C'est la méthode préférée pour utiliser l'API taginfo à partir d'autres pages Web.

Taginfo prend également en charge l'ancienne technique JSONP. Vous pouvez ajouter le paramètre callback à tout appel d'API renvoyant JSON et il renverra le résultat emballé dans un appel de fonction nommée par le paramètre callback.

Exemple: ... &callback=foo

renverra foo(... des données en json ...).