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

Key Acquisition

Get your key at https://touripedia.nl/organisaties/api-aanvragen/

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

Limits

The current quota rules are as follows:

• Maximum 20 to 30 concurrent requests per client
• No more than ~10 requests/second over a prolonged period
• Limit of 1000 requests/hour

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

fields Parameter Syntax

This parameter allows you to precisely define the list of fields to return for each object. It allows optimizing response size.

Default Behavior

If the fields parameter is not specified, the API returns only a default selection of fields:

- 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: An exclamation mark ! at the beginning of a field indicates the exclusion of that sub-tree.

Custom Selection

If you need other fields not included in this default list, you must use the fields parameter to provide the exhaustive list of all fields you wish to obtain.

Warning: Using the fields parameter completely replaces the default selection.

Hierarchy

The selection is hierarchical: requesting a parent field will automatically return all its sub-properties.

# Request UUID, label, and all contact info
GET /v1/catalog?fields=uuid,label,hasContact

search Parameter Syntax

This parameter allows performing full-text search on the names and descriptions of Points of Interest.

The search supports advanced operators to refine your results.

Targeted Fields

The search is performed automatically and exclusively on the following fields:

• label.* (POI name in all languages)
• hasDescription.* (POI descriptions in all languages)

Examples

# Simple search
search=castle

# Search with operators (AND)
search=castle AND "loire"

# Search with exclusion
search=museum -art

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. Pagination information is included in the meta object of the response.

Response Example

{
  "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
  }
}

Method 1: Navigation Links (Recommended)

This is the simplest and most reliable method. Use the URLs provided directly in the next and previous fields of the meta object to navigate between pages.

Tip: Prefer this method to browse the entire catalog. It ensures no results are missed.

Method 2: page Parameter

You can request a specific page by using the page parameter. However, this method has technical limitations.

• Limit: Direct access by page number is limited to the first 10,000 results (i.e., 500 pages of 20 results).
• Usage: Useful for quickly accessing the first few pages of results.

Warning: Beyond the 10,000th resource, you must use the next links provided in the previous response to continue navigation.

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
}