Introduction

Titre : Touripedia API

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

Obtention de la clé

Obtention de la clé sur https://touripedia.nl/organisaties/api-aanvragen/

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

Limites

Les règles de quotas à date sont les suivantes :

• Maximum 20 à 30 requêtes concurrentes par client,
• Pas plus de ~10 requêtes/seconde de manière prolongée,
• Limite de 1000 requêtes/heure.

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 fields

Ce paramètre permet de définir précisément la liste des champs à retourner pour chaque objet. Il permet d'optimiser la taille des réponses.

Comportement par défaut

Si le paramètre fields n'est pas précisé, l'API ne renvoie qu'une sélection de champs par défaut :

- uuid
- uri
- label
- type
- isLocatedAt.geo
- isLocatedAt.address
- !isLocatedAt.address.hasAddressCity.isPartOfDepartment
- COVID19SpecialMeasures
- hasBeenCreatedBy
- !hasBeenCreatedBy.address
- lastUpdate
- lastUpdateDatatourisme
- hasContact
- !hasContact.address.hasAddressCity.isPartOfDepartment
- hasReview
- hasMainRepresentation
- hasDescription

Note : Un point d'exclamation ! au début d'un champ indique l'exclusion de cette sous-arborescence.

Sélection personnalisée

Si vous avez besoin d'autres champs non inclus dans cette liste par défaut, vous devez utiliser le paramètre fields pour fournir la liste exhaustive de tous les champs que vous souhaitez obtenir.

Attention : L'utilisation du paramètre fields remplace totalement la sélection par défaut.

Hiérarchie

La sélection est hiérarchique : demander un champ parent retournera automatiquement toutes ses sous-propriétés.

# Demander l'UUID, le nom, et toutes les infos de contact
GET /v1/catalog?fields=uuid,label,hasContact

Syntaxe du paramètre search

Ce paramètre permet d'effectuer une recherche textuelle sur les noms et descriptions des points d'intérêt.

La recherche supporte des opérateurs avancés pour affiner vos résultats.

Champs ciblés

La recherche s'effectue automatiquement et uniquement sur les champs suivants :

• label.* (le nom du POI dans toutes les langues)
• hasDescription.* (les descriptions du POI dans toutes les langues)

Exemples

# Recherche simple
search=château

# Recherche avec opérateurs (ET)
search=château AND "loire"

# Recherche avec exclusion
search=musée -art

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. Les informations de pagination sont incluses dans l'objet meta de la réponse.

Exemple de réponse

{
  "objects": [...],
  "meta": {
    "total": 471688,
    "page": 1,
    "page_size": 20,
    "total_pages": 23585,
    "next": "http://api.datatourisme.fr/v1/catalog?api_key=...&page=2",
    "previous": null
  }
}

Méthode 1 : Liens de navigation (Recommandée)

C'est la méthode la plus simple et la plus fiable. Utilisez directement les URL fournies dans les champs next et previous de l'objet meta pour naviguer entre les pages.

Conseil : Privilégiez cette méthode pour parcourir l'intégralité du catalogue. Elle garantit de ne manquer aucun résultat.

Méthode 2 : Paramètre page

Vous pouvez demander une page spécifique en utilisant le paramètre page. Cependant, cette méthode a des limites techniques.

• Limite : L'accès direct par numéro de page est limité aux 10 000 premiers résultats (soit 500 pages de 20 résultats).
• Usage : Utile pour accéder rapidement aux premières pages de résultats.

Attention : Au-delà de la 10 000ème ressource, vous devez utiliser les liens next fournis dans la réponse précédente pour continuer la navigation.

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
}