Introduction

Titre : API DATAtourisme

Version : 1.0.0

Description : Cette API permet d'accéder aux points d'intérêt (POIs). Elle offre des fonctionnalités de recherche, de filtrage et de récupération des détails des POIs.

URL du serveur : /v1

Authentification

L'API utilise une clé d'authentification unique pour sécuriser les requêtes. Vous pouvez fournir cette clé de deux manières.

Méthode 1 : En-tête HTTP (Recommandée)

Incluez la clé dans l'en-tête X-API-Key de votre requête.

X-API-Key: votre_clé_api_unique

Méthode 2 : Paramètre de requête

Ajoutez la clé comme paramètre api_key dans l'URL de votre requête.

GET /v1/catalog?api_key=votre_clé_api_unique

Lister et rechercher les POIs

GET/catalog

Récupère une liste paginée de l'ensemble des points d'intérêt disponibles, avec de nombreuses options de filtrage et de recherche.

Paramètres de requête

Réponse (200 OK)

La réponse est un objet JSON structuré avec deux clés principales :

{
  "objects": [ ... ],
  "meta": { ... }
}

• objects: Un tableau contenant la liste des objets POI pour la page actuelle. La structure détaillée de chaque objet est disponible dans la section Schéma POI.
• meta: Un objet contenant les métadonnées de pagination. Voir la section Schéma Metadata pour plus de détails.

Endpoints Pré-filtrés

Ces endpoints sont des raccourcis vers /catalog avec un filtre pré-appliqué sur le type de POI. Ils acceptent tous les mêmes paramètres que /catalog.

Détail d'un POI

GET/catalog/{uuid}

Récupère les informations détaillées d'un point d'intérêt spécifique à partir de son UUID.

Paramètres de chemin

Obtenir un Thésaurus

GET/thesaurus/{code}

Récupère les valeurs contrôlées (termes) pour un thésaurus donné, utiles pour construire des filtres précis.

Paramètres de chemin

Syntaxe du paramètre lang

Ce paramètre permet de spécifier la langue des champs traduisibles dans la réponse.

• Syntaxe : Une liste de codes de langue (ex: fr, en) séparés par des virgules.
• Valeur par défaut : Si le paramètre est omis, la réponse inclura le français (fr) et l'anglais (en).
• Valeur spéciale `*` : Utilisez lang=* pour recevoir toutes les langues disponibles pour un champ.

# Demander les POIs avec les champs en français et espagnol
GET /v1/catalog?lang=fr,es

Syntaxe du paramètre filters

Le paramètre filters offre une syntaxe puissante pour construire des requêtes complexes en combinant plusieurs conditions.

Opérateurs de filtre

Les opérateurs sont placés entre crochets [] après le nom du champ. Ils sont insensibles à la casse.

Combinaison d'expressions

Utilisez les opérateurs logiques AND et OR pour combiner des filtres. Les parenthèses () sont supportées pour gérer les priorités.

# Restaurants avec Wifi OU Parking
type=Restaurant AND (isEquippedWith=Wifi OR isEquippedWith=CarPark)

Syntaxe des opérateurs géospatiaux

Ces opérateurs permettent de rechercher des POIs en fonction de leur localisation géographique.

Opérateur [geo_distance]

Recherche les POIs dans un rayon donné autour d'un point central.

• Format : lat,lon,distanceunité
• Unités supportées : m, km, mi, yd, ft, in, cm, mm.
• Contraintes : La latitude doit être entre -90 et 90, la longitude entre -180 et 180, et la distance doit être positive.

# POIs à moins de 10km de Rennes
filters=isLocatedAt.geo[geo_distance]=48.1173,-1.6778,10km

Opérateur [geo_bounding]

Recherche les POIs dans une boîte rectangulaire définie par ses coins supérieur-gauche et inférieur-droit.

• Format : top_left_lat,top_left_lon,bottom_right_lat,bottom_right_lon
• Contraintes : top_left_lat doit être supérieur à bottom_right_lat, et top_left_lon doit être inférieur à bottom_right_lon.

# POIs dans un quartier de Rennes
filters=isLocatedAt.geo[geo_bounding]=48.118,-1.675,48.115,-1.670

Syntaxe du paramètre sort

Le paramètre sort permet de trier les résultats. Vous pouvez trier par un ou plusieurs champs, y compris des champs imbriqués.

Opérateurs de tri

Tri sur plusieurs champs

Séparez les champs par une virgule ,. Le tri est appliqué dans l'ordre de la liste.

# Trier par département (croissant), puis par date de mise à jour (décroissant)
sort=isLocatedAt.address.hasAddressCity.isPartOfDepartment.insee,lastUpdate[desc]

Pagination

Pour naviguer dans de grands ensembles de résultats, l'API utilise un système de pagination.

Recommandation : Pour des performances optimales et un accès à l'ensemble des résultats, il est fortement conseillé d'utiliser les liens next et previous fournis dans l'objet meta de la réponse.

Attention : L'utilisation directe du paramètre page peut être lente et est limitée aux 10 000 premiers résultats. Au-delà, l'utilisation des liens next est obligatoire.

Schéma POI (PointOfInterest)

Ceci est la structure complète et hiérarchique d'un objet POI. Cliquez sur les propriétés pour déplier leur contenu.

Schéma Metadata

L'objet meta accompagne chaque réponse de liste et contient les informations de pagination.

{
  "total": 15320,
  "page": 1,
  "page_size": 20,
  "total_pages": 766,
  "next": "/v1/catalog?page=2...",
  "previous": null
}