Toeristenradar - API Documentation (v0.0.1)

Introduction

The goal of the documentation is to give an overview on how to consume the API. The API recommends activities based on a subset of parameters defined further down this page. The goal is to ensure that activities are offered on a fair basis meaning that an activity that was offered fewer times compared to another activity it is more likely the latter activity is offered as a option.

Base url to consume the API:

"https://toeristenradar.crispcode.nl/api/{path}

Obtaining a company token

To ensure the 'fairness' system discussed above does not interfere between different API consumers a token should be provided enabling us to uniquely identify consumers.

Path

[POST] /company

[Request Params] // Parameters that should be provided with the request
name: string

As a result you will receive a JSON response using the following structure. Ensure you store your token somewhere safe. Once it is retrieved it is not possible to see your token again.

{
   "token": "YOUR-COMPANY-TOKEN-HERE"
}

Using your token

Now that you've obtained your token we should teach how this token should be used. The token should be provided in the header for all the request described in this document.

{
    "x-company-id": "YOUR-COMPANY-TOKEN-HERE"
}

Failing to provide the token in any of the request shown below will result in the error described below.

{
    "status": 401,
    "message": "Unauthorized"
}

Getting activity types

Before we can start retrieving activity recommendations we first need to determine for what kind of activity we want to get recommendations. This can be done by retrieving all available activity types the API currently supports. Although we do not update them regularly we recommend to update it as often as possible to ensure you always get access to the latest activities.

Path

[GET] /activity-types

[Request Params] // Parameters that should be provided with the request
// none

Example result

[
    {
        "id": 1, // ID used to filter other API calls
        "icon_id": 336, // used internally
        "title": "Walking", // title of the activity type
        "created_at": "2023-03-01T20:27:25.000000Z",
        "updated_at": "2023-03-01T20:27:25.000000Z",
    }
],

Getting activity recommendations

This is the main API call that we expose to our clients. Using this call you can get our activities recommendations based on the filters you've provided.

Path

[POST] /activities/filtered

[Request Params] // Parameters that should be provided with the request
'activity_type': int // use the id of one of the activity types retrieved in the call above
'relative_date': string // one of: today,tomorrow,weekend
'limit': int // max 10
'recommender': // optional see section below

Defining a recommender

Recommenders customize the result and handling of the activities offered through our API. We combine a lot of datasources and sometimes we want to customize how consumers of these sources get the results back.

Recommender name	Request string
Default	[Dont provide the argument]
Marketing Oost	marketing-oost

Based on the recommender you've selected the API call may behave differently, for each of the recommender we will show an example response

Default recommender

When you don't provide a recommender (recommended) unless communicated an example result may look like this

[
    {
        "id": 31,
        "title": "title of the activity",
        "latitude": 52.4671173,
        "longitude": 6.4281149,
        "created_at": "2023-03-01T20:27:43.000000Z",
        "updated_at": "2023-03-01T20:27:43.000000Z",
        "description": "Description belong to the activity",
        "length": "6.85",
        "is_free": true,
        "datasource": {
            "id": 1,
            "title": "Name of the datasource",
        },
        "images": [{
            "id": 1,
            "name": "image name",
            "picture": "path to the image",
            "file_type": "jpeg",
            "created_at": "2023-03-01T20:27:43.000000Z",
            "updated_at": "2023-03-01T20:27:43.000000Z",
        }],
        "activity_types": [{
            "id": 1,
            "icon_id": 336,
            "title": "Walking",
            "created_at": "2023-03-01T20:27:25.000000Z",
            "updated_at": "2023-03-01T20:27:25.000000Z",
        }],
        "tripkinds": [{
            "id": 1,
            "icon_id": 318,
            "tripkind": "Roundtrip",
            "created_at": "2023-03-01T20:27:25.000000Z",
            "updated_at": "2023-03-01T20:27:25.000000Z",
        }],
        "themes": [{
            "id": 1,
            "icon_id": 384,
            "theme": "Nature",
            "created_at": "2023-03-01T20:27:25.000000Z",
            "updated_at": "2023-03-01T20:27:25.000000Z",
        }]
    }
]

Marketing oost recommender

When you provide the 'marketing-oost' recommender specified in the table above an example result may look like this

[
    {
        "activity_id": int // The unique identifier used in the original datasource so it can be matched to that dataset
        "is_closed": boolean // indicates a route is closed due to various reasons (e.g. breeding season)
        "score": int // limited between 0 - 100
    }
]

Using our Wordpress plugin

Do you want to use this API within your wordpress website? We already build a plugin you can easily integrate within your website. For more information reach out to us. or check the documentation