Inleiding

Titel: Touripedia API

Versie: 1.0.0

Beschrijving: Deze API biedt toegang tot Points of Interest (POI's). Het biedt zoek-, filter- en ophaalmogelijkheden voor POI-details.

Server URL: /v1

Authenticatie

Sleutel Verkrijgen

Verkrijg uw sleutel op https://touripedia.nl/organisaties/api-aanvragen/

De API gebruikt een unieke authenticatiesleutel om verzoeken te beveiligen. U kunt deze sleutel op twee manieren verstrekken.

Methode 1: HTTP Header (Aanbevolen)

Voeg de sleutel toe in de X-API-Key header van uw verzoek.

X-API-Key: your_unique_api_key

Methode 2: Query Parameter

Voeg de sleutel toe als de api_key parameter in de URL van uw verzoek.

GET /v1/catalog?api_key=your_unique_api_key

Limieten

De huidige quotumregels zijn als volgt:

• Maximaal 20 tot 30 gelijktijdige verzoeken per klant
• Niet meer dan ~10 verzoeken/seconde over een langere periode
• Limiet van 1000 verzoeken/uur

POI's Weergeven en Zoeken

GET/catalog

Haalt een gepagineerde lijst op van alle beschikbare Points of Interest, met talrijke filter- en zoekopties.

Query Parameters

Reactie (200 OK)

De reactie is een gestructureerd JSON-object met twee hoofdsleutels:

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

• objects: Een array met de lijst van POI-objecten voor de huidige pagina. De gedetailleerde structuur van elk object is beschikbaar in de POI Schema sectie.
• meta: Een object met metadata voor paginering. Zie de Metadata Schema sectie voor meer details.

Voorgefilterde Endpoints

Deze endpoints zijn snelkoppelingen naar /catalog met een vooraf toegepast filter op het POI- type. Ze accepteren alle dezelfde parameters als /catalog.

POI Details

GET/catalog/{uuid}

Haalt gedetailleerde informatie op voor een specifieke Point of Interest met behulp van zijn UUID.

Pad Parameters

Een Thesaurus Ophalen

GET/thesaurus/{code}

Haalt gecontroleerde waarden (termen) op voor een bepaalde thesaurus, nuttig voor het bouwen van precieze filters.

Pad Parameters

lang Parameter Syntax

Deze parameter specificeert de taal voor vertaalbare velden in de reactie.

• Syntax: Een door komma's gescheiden lijst van taalcodes (bijv.: fr, en).
• Standaardwaarde: Als de parameter wordt weggelaten, bevat de reactie Frans (fr) en Engels (en).
• Speciale Waarde `*`: Gebruik lang=* om alle beschikbare talen te ontvangen voor een veld.

# Verzoek POI's met velden in Frans en Spaans
GET /v1/catalog?lang=fr,es

fields Parameter Syntax

Deze parameter stelt u in staat om precies de lijst met terug te geven velden voor elk object te definiëren. Het stelt u in staat om de antwoordgrootte te optimaliseren.

Standaardgedrag

Als de fields parameter niet is gespecificeerd, retourneert de API alleen een standaardselectie van velden:

- 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

Opmerking: Een uitroepteken ! aan het begin van een veld duidt de uitsluiting van die subboom aan.

Aangepaste Selectie

Als u andere velden nodig heeft die niet in deze standaardlijst zijn opgenomen, moet u de fields parameter gebruiken om de volledige lijst van alle velden die u wilt verkrijgen te verstrekken.

Waarschuwing: Het gebruik van de fields parameter vervangt volledig de standaard selectie.

Hiërarchie

De selectie is hiërarchisch: het aanvragen van een bovenliggend veld zal automatisch al zijn subeigenschappen retourneren.

# Verzoek UUID, label en alle contactinformatie
GET /v1/catalog?fields=uuid,label,hasContact

search Parameter Syntax

Deze parameter stelt u in staat om een volledige tekstzoekopdracht uit te voeren op de namen en beschrijvingen van Points of Interest.

De zoekopdracht ondersteunt geavanceerde operators om uw resultaten te verfijnen.

Doelvelden

De zoekopdracht wordt automatisch en uitsluitend uitgevoerd op de volgende velden:

• label.* (POI-naam in alle talen)
• hasDescription.* (POI-beschrijvingen in alle talen)

Voorbeelden

# Eenvoudige zoekopdracht
search=castle

# Zoekopdracht met operators (AND)
search=castle AND "loire"

# Zoekopdracht met uitsluiting
search=museum -art

filters Parameter Syntax

De filters parameter biedt een krachtige syntax voor het bouwen van complexe query's door meerdere voorwaarden te combineren.

Filter Operators

Operators worden tussen vierkante haken [] na de veldnaam geplaatst. Ze zijn niet hoofdlettergevoelig.

Expressies Combineren

Gebruik de logische operators AND en OR om filters te combineren. Haakjes () worden ondersteund om prioriteiten te beheren.

# Restaurants met Wifi OF Parkeren
type=Restaurant AND (isEquippedWith=Wifi OR isEquippedWith=CarPark)

Geospatiale Operators Syntax

Deze operators stellen u in staat om te zoeken naar POI's op basis van hun geografische locatie.

[geo_distance] Operator

Zoekt naar POI's binnen een bepaalde straal rond een centraal punt.

• Formaat: lat,lon,afstandeenheid
• Ondersteunde Eenheden: m, km, mi, yd, ft, in, cm, mm.
• Beperkingen: Breedtegraad moet tussen -90 en 90 liggen, lengtegraad tussen -180 en 180, en de afstand moet positief zijn.

# POI's binnen 10 km van Rennes
filters=isLocatedAt.geo[geo_distance]=48.1173,-1.6778,10km

[geo_bounding] Operator

Zoekt naar POI's binnen een rechthoekige box gedefinieerd door de linkerbovenhoek en rechteronderhoek.

• Formaat: top_left_lat,top_left_lon,bottom_right_lat,bottom_right_lon
• Beperkingen: top_left_lat moet groter zijn dan bottom_right_lat, en top_left_lon moet kleiner zijn dan bottom_right_lon.

# POI's in een buurt van Rennes
filters=isLocatedAt.geo[geo_bounding]=48.118,-1.675,48.115,-1.670

sort Parameter Syntax

De sort parameter stelt u in staat om de resultaten te sorteren. U kunt sorteren op een of meer velden, inclusief geneste velden.

Sorteeroperators

Sorteren op meerdere velden

Scheid velden met een komma ,. Sorteren wordt toegepast in de volgorde van de lijst.

# Sorteer op departement (oplopend), daarna op laatste updatedatum (aflopend)
sort=isLocatedAt.address.hasAddressCity.isPartOfDepartment.insee,lastUpdate[desc]

Paginering

Om door grote resultatensets te navigeren, gebruikt de API een pagineringssysteem. Paginering-informatie is opgenomen in het meta object van de reactie.

Reactievoorbeeld

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

Methode 1: Navigatielinks (Aanbevolen)

Dit is de eenvoudigste en meest betrouwbare methode. Gebruik de URL's die direct worden verstrekt in de next en previous velden van het meta object om te navigeren tussen pagina's.

Tip: Geef de voorkeur aan deze methode om door de hele catalogus te bladeren. Het zorgt ervoor dat geen resultaten worden gemist.

Methode 2: page Parameter

U kunt een specifieke pagina aanvragen door de page parameter te gebruiken. Deze methode heeft echter technische beperkingen.

• Limiet: Directe toegang per paginanummer is beperkt tot de eerste 10.000 resultaten (d.w.z. 500 pagina's van 20 resultaten).
• Gebruik: Nuttig voor snelle toegang tot de eerste paar pagina's met resultaten.

Waarschuwing: Buiten het 10.000ste resultaat, moet u de next links gebruiken die in de vorige reactie zijn verstrekt om door te gaan met navigeren.

POI (PointOfInterest) Schema

Dit is de volledige hiërarchische structuur van een POI-object. Klik op de eigenschappen om hun inhoud uit te vouwen.

Metadata Schema

Het meta object begeleidt elke lijstreactie en bevat paginering-informatie.

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