Review API uitleg - escapetalk.nl

Escapetalk review API uitleg

Met de review API kun je, indien je een abonnement hebt, reviews en scores van je kamer(s), locatie(s), game(s) of uitgever(s) op je eigen website tonen. De API retourneert een JSON string met info en alle reviews die hieraan gekoppeld zijn. Deze kun je vervolgens net zo tonen als je wil.

Overzicht

Klik op een onderdeel om daarheen te scrollen.

Basis

Alle verzoeken worden als POST naar onderstaande URL gestuurd. /api/reviews/public/ werkt ook en geeft exact hetzelfde resultaat.

POST https://escapetalk.nl/api/reviews

Authenticatie

Als eigenaar van een locatie of uitgever, met een actief abonnement, kun je bij instellingen een API code genereren. Stuur deze mee als POST parameter.

apikey Verplicht

De 'apikey' wordt gebruikt om verzoeken te authentiseren.

Standaard: geen standaard waarde
Accepteert: string (25)

Parameters

Alle parameters worden als POST (form data) meegestuurd. De API heeft sowieso een id en type nodig:
- room: alle reviews van deze kamer.
- location: alle reviews van alle online kamers van deze locatie.
- game: alle reviews van deze game.
- publisher: alle reviews van alle online games van deze uitgever.

De overige parameters zijn optionele filters.

id Verplicht

Het id van de kamer, locatie, game of uitgever waarvan je de reviews wilt ophalen.

Standaard: geen standaard waarde
Accepteert: Numerieke waarde

type Verplicht

Het type waar het id bij hoort.

Standaard: geen standaard waarde
Accepteert: roomlocationgamepublisher

version Optioneel

Laat leeg voor de huidige versie. Met 'legacy' krijg je de oude response terug (alleen voor room en location), zie legacy.

Standaard: geen standaard waarde
Accepteert: legacy

min_score Optioneel

Met de 'min_score' parameter kun je aangeven dat alleen reviews vanaf een bepaalde score meegestuurd mogen worden. Handig als je bepaalde minder positieve reviews liever niet op je site terug ziet.

Standaard: geen standaard waarde
Accepteert: Numerieke waarde (0-10)

max_score Optioneel

Met de 'max_score' parameter kun je aangeven dat je alleen reviews tot een bepaalde score terug wilt ontvangen. In de praktijk zal je dit niet snel gebruiken :)

Standaard: geen standaard waarde
Accepteert: Numerieke waarde (0-10)

exclude_reviews Optioneel

Hiermee kun je uitsluiten dat specifieke reviews meegenomen worden.

Standaard: geen standaard waarde
Accepteert: Numerieke waardes, accepteert meerdere id's als deze gescheiden zijn door komma's

include_reviews Optioneel

Hiermee kun je aangeven dat alleen deze specifieke reviews meegenomen worden.

Standaard: geen standaard waarde
Accepteert: Numerieke waardes, accepteert meerdere id's als deze gescheiden zijn door komma's

sort_type Optioneel

'sort_type' sorteert standaard op de bezoekdatum ('visit_date', bij games de speeldatum). Optioneel kun je sorteren op 'score' of op de datum van het plaatsen van de review ('review_date').

Standaard: visit_date
Accepteert: visit_datescorereview_date

sort Optioneel

'sort' bepaald of het sorteren van boven naar beneden of andersom wordt uitgevoerd. Deze waarde staat standaard op 'DESC' (omlaag)

Standaard: DESC
Accepteert: ASCDESC

limit Optioneel

De waarde die je aan de 'limit' parameter meegeeft bepaald hoeveel reviews er maximaal teruggestuurd worden.

Standaard: geen standaard waarde
Accepteert: Numerieke waarde

from Optioneel

De startdatum vanaf welke datum je de reviews wilt ontvangen

Standaard: geen standaard waarde
Accepteert: Een datum (YYYY-MM-DD)

to Optioneel

De einddatum tot welke datum je de reviews wilt ontvangen

Standaard: geen standaard waarde
Accepteert: Een datum (YYYY-MM-DD)

Reactie

Geeft de info en gemiddelde scores van de opgevraagde kamer, locatie, game of uitgever terug, met daarbij de lijst met reviews als JSON. Bij een game of uitgever staat er in een review 'game' en 'publisher' in plaats van 'room' en 'location'.

Een voorbeeld van de JSON reactie er uit zou kunnen zien.

{
    "type": "room",
    "info": {
        "id": 22,
        "title": "Best Escape Room Ever",
        "slug": "escaperoom-room",
        "scores": {
            "score": "9.6",
            "ambiance": "9.7",
            "puzzles": "9.5",
            "quality": "9.7",
            "total_reviews": 55
        }
    },
    "reviews": [
        {
            "id": 1234,
            "parent_id": 22,
            "plugin": "room",
            "user": {
                "id": 5678,
                "name": "reviewer",
                "nickname": "Name of reviewer",
                "avatar": "https://...",
                "has_account": true
            },
            "title": "title",
            "description": "description",
            "date": "2026-05-17",
            "placed_date": "2026-05-17 14:52:42",
            "escaped": "ja",
            "escape_time": 0,
            "images": false,
            "room": { "title": "Best Escape Room Ever", "slug": "escaperoom-room" },
            "location": { "title": "Escaperoom Location", "slug": "escaperoom-location" },
            "score": 10,
            "ambiance": 10,
            "puzzles": 10,
            "quality": 10,
            "likes": 3,
            "amount_players": 4,
            "pros": ["Sfeer", "Puzzels"],
            "cons": false
        },
        ... //more reviews would follow in the same format
    ],
    "count": 55
}

Foutmeldingen

Bij een fout geeft de API een HTTP foutcode terug met een JSON object met daarin de foutmelding.

Voorbeeld van een foutmelding en alle mogelijke foutmeldingen.

{"error": "INVALID_API_KEY"}

401	`INVALID_API_KEY`
403	`FEATURE_NOT_AVAILABLE`
403	`NOT_OWNED_BY_USER`
422	`MISSING_PARAMETERS`
422	`FAULTY_PARAMETERS`
422	`INVALID_TYPE`
422	`INVALID_MIN_SCORE`
422	`INVALID_MAX_SCORE`
422	`INVALID_LIMIT`
422	`INVALID_DATE`
422	`NOT_NUMERIC`
422	`INVALID_SORT_TYPE`
422	`INVALID_SORT`
422	`TYPE_NOT_SUPPORTED_IN_LEGACY`

Voorbeeld

Een voorbeeld van PHP code om de API aan te roepen. Dit kan natuurlijk ook in JavaScript gedaan worden.

$url = 'https://escapetalk.nl/api/reviews/';

$data = array(
    'apikey' => 'REPLACE_WITH_API_KEY',
    'type' => 'REPLACE_WITH_ITEM_TYPE',
    'id' => 'REPLACE_WITH_ITEM_ID',
    'min_score' => '7',
    'sort_type' => 'review_date',
    'sort' => 'desc',
    'limit' => '10'
);

$options = array(
    'http' => array(
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$result = json_decode($result);

Legacy gebruik

Gebruik je de API al langer? Dan blijft je bestaande koppeling gewoon werken en krijg je exact dezelfde response als voorheen. Dit kan alleen voor kamers en locaties, en foutmeldingen worden als platte tekst teruggegeven. Voor nieuwe koppelingen raden we de huidige versie aan, de legacy manier word mogelijk in de toekomst uitgefuseerd (voordat dit gebeurd word je op de hoogte gebracht).

Optie 1, zoals het altijd werkte: stuur room_id of loc_id mee.

apikey=REPLACE_WITH_YOUR_API_KEY
room_id=REPLACE_WITH_ITEM_ID    // or loc_id=REPLACE_WITH_ITEM_ID

Optie 2: gebruik id en type met version 'legacy'.

apikey=REPLACE_WITH_YOUR_API_KEY
id=REPLACE_WITH_ITEM_ID
type=REPLACE_WITH_ITEM_TYPE    // room or location
version=legacy

De legacy response voor een kamer (room_id) en locatie (loc_id).

{"room_info":{
    "title":"Best Escape Room Ever",
    "description":"Lorem ipsum dolor sit amet...",
    "loc_slug":"escaperoom-location",
    "room_slug":"escaperoom-room",
    "link":"https://escapetalk.nl/escaperoom/escaperoom-location/escaperoom-room/",
    "score":"9.5",
    "sfeer":"9.0",
    "puzzels":"9.0",
    "spelbeleving":"9.0",
    "service":"9.8"
},
    "total_review_count":55,
    "reviews":[
        {
            "id":22,
            "title":"title",
            "description":"description",
            "score":"10.0",
            "sfeer":"10.0",
            "puzzels":"10.0",
            "review_date":"2021-08-01",
            "spelbeleving":"10.0",
            "service":"10.0",
            "visit_date":"June 2021",
            "escaped":"ja",
            "nickname":"Name of reviewer",
            "profile_url":"https://escapetalk.nl/profiel/reviewer/",
            "review_link":"https://escapetalk.nl/escaperoom/escaperoom-location/escaperoom-room/#rev_22"
        },
        ... //more reviews would follow in the same format
    ]
}

// loc_id / type=location:
{"location": {"id":319, "title":"...", "intro_txt":"...", "description":"...", "opened":"2015-07-18", "scores":{...}, "total_reviews":55}, "rooms": [ /* per room the structure above */ ]}