Introduction

Title: Touripedia API

Version: 1.0.0

Description: This API provides access to Points of Interest (POIs). It offers search, filtering, and retrieval functionalities for POI details.

Server URL: /v1

Authentication

The API uses a unique authentication key to secure requests. You can provide this key in two ways.

Method 1: HTTP Header (Recommended)

Include the key in the X-API-Key header of your request.

X-API-Key: your_unique_api_key

Method 2: Query Parameter

Add the key as the api_key parameter in the URL of your request.

GET /v1/catalog?api_key=your_unique_api_key

List and Search POIs

GET/catalog

Retrieves a paginated list of all available Points of Interest, with numerous filtering and search options.

Query Parameters

Response (200 OK)

The response is a structured JSON object with two main keys:

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

• objects: An array containing the list of POI objects for the current page. The detailed structure of each object is available in the POI Schema section.
• meta: An object containing pagination metadata. See the Metadata Schema section for more details.

Pre-filtered Endpoints

These endpoints are shortcuts to /catalog with a pre-applied filter on the POI type. They accept all the same parameters as /catalog.

POI Details

GET/catalog/{uuid}

Retrieves detailed information for a specific Point of Interest using its UUID.

Path Parameters

Get a Thesaurus

GET/thesaurus/{code}

Retrieves controlled values (terms) for a given thesaurus, useful for building precise filters.

Path Parameters

lang Parameter Syntax

This parameter specifies the language for translatable fields in the response.

• Syntax: A comma-separated list of language codes (ex: fr, en).
• Default Value: If the parameter is omitted, the response will include French (fr) and English (en).
• Special Value `*`: Use lang=* to receive all available languages for a field.

# Request POIs with fields in French and Spanish
GET /v1/catalog?lang=fr,es

filters Parameter Syntax

The filters parameter offers a powerful syntax for building complex queries by combining multiple conditions.

Filter Operators

Operators are placed in brackets [] after the field name. They are case-insensitive.

Combining Expressions

Use the logical operators AND and OR to combine filters. Parentheses () are supported to manage priorities.

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

Geospatial Operators Syntax

These operators allow searching for POIs based on their geographic location.

[geo_distance] Operator

Searches for POIs within a given radius around a central point.

• Format: lat,lon,distanceunit
• Supported Units: m, km, mi, yd, ft, in, cm, mm.
• Constraints: Latitude must be between -90 and 90, longitude between -180 and 180, and the distance must be positive.

# POIs within 10km of Rennes
filters=isLocatedAt.geo[geo_distance]=48.1173,-1.6778,10km

[geo_bounding] Operator

Searches for POIs within a rectangular box defined by its top-left and bottom-right corners.

• Format: top_left_lat,top_left_lon,bottom_right_lat,bottom_right_lon
• Constraints: top_left_lat must be greater than bottom_right_lat, and top_left_lon must be less than bottom_right_lon.

# POIs in a neighborhood of Rennes
filters=isLocatedAt.geo[geo_bounding]=48.118,-1.675,48.115,-1.670

sort Parameter Syntax

The sort parameter allows sorting the results. You can sort by one or more fields, including nested fields.

Sorting Operators

Sorting on multiple fields

Separate fields with a comma ,. Sorting is applied in the order of the list.

# Sort by department (ascending), then by last update date (descending)
sort=isLocatedAt.address.hasAddressCity.isPartOfDepartment.insee,lastUpdate[desc]

Pagination

To navigate large result sets, the API uses a pagination system.

Recommendation: For optimal performance and access to the entire result set, it is strongly recommended to use the next and previous links provided in the meta object of the response.

Warning: Direct use of the page parameter can be slow and is limited to the first 10,000 results. Beyond this, using the next links is mandatory.

POI (PointOfInterest) Schema

This is the complete hierarchical structure of a POI object. Click on the properties to expand their content.

Metadata Schema

The meta object accompanies each list response and contains pagination information.

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