UIT-API Noord-Holland

Zoeken in alle evenementen en activiteiten in Noord-Holland? De Cultuurcompagnie maakt het mogelijk met de UIT-API. Met deze API kan je gemakkelijk filteren op activiteiten in Noord-Holland. Zo zijn er filters op plaats, leeftijd en zelfs op activiteitssoort. Met de UIT-API kun je dus gemakkelijk zoeken in meer dan 1000 activiteiten van meer dan 700 organisaties.

Documentatie

In de API zit informatie over activiteiten en organisaties in Noord-Holland. De API geeft standaard data in JSON, maar kan desgevraagd ook in XML-formaat serveren. Documentatie van de API is hier te vinden. De data mag worden hergebruikt onder een CC BY 4.0 licentie. Dit betekent dat je de data mag delen en aanpassen. Je moet het wel aangegeven als de data is aangepast. Ook moet je altijd de auteur vermelden. In dit geval is dat de Cultuurcompagnie.

Data ophalen

In de API zijn activiteiten op basis van diverse filters op te halen. Je kan zoeken op organisatie, regio, plaats, soort activiteit of leeftijdscategorie. Eerst moet je in de betreffende ‘endpoint’ de ID ophalen van de filter die je wil gebruiken. Met een ID kan je vervolgens binnen de activiteiten zoeken.

Stel dat je alleen activiteiten voor 18 jaar of ouder wil zoeken dan moet je in de endpoint “leeftijdcategorieen” zoeken welke ID deze categorie heeft. Dat is in dit geval ID: 10.

{

ID: 10,

NAAM: “18+”

},

Deze ID kan je gebruiken in een API-call op de ‘endpoint activiteiten’ met de parameter leeftijdscategorien. De query is dan: http://www.uitinnoordholland.nl/api/agenda/activiteiten?leeftijdcategorien=10.

Het resultaat is dat je alle activiteiten terugkrijgt die gemerkt zijn voor 18+. Je kan ook op meerde leeftijdscategorieën zoeken door gebruik te maken van een komma in de parameter.

De query http://www.uitinnoordholland.nl/api/agenda/activiteiten?leeftijdcategorien=10,16 haalt dus zowel de activiteiten voor 18+ (ID: 10) als 50+ (ID: 16) op. Deze methode geldt voor alle parameters.

Aan de slag

Er zijn vijf verschillende endpoints. Je kan zoeken op plaatsen, regio’s, activiteitensoorten, organisaties en leeftijdscategorieën. Elke plaats heeft bijvoorbeeld een eigen ID.

Zoals gedemonstreerd kan je de ID’s gebruiken om een query te doen op de activiteiten. De ‘endpoints’ gelden dus ook als parameter voor de ‘activiteiten-endpoint’.

Naast deze parameters kan je met de format=xml parameter de output in XML geven. Je kan ook enkel zoeken op gratis activiteiten met de gratis=True parameter. Deze parameters kan je – in tegenstelling tot de andere parameters – combineren met andere.

In een vorig voorbeeld zochten we op alle activiteiten voor 18 jaar en ouder.  Deze query geeft meerdere activiteiten terug. Iedere activiteit heeft een eigen tag “SPEELDATA”. Dit geeft deze output:

SPEELDATA:
[
{
PRIJSTOELICHING: “”,
PRIJS_OUDEREN: “”,
PRIJS_CJP: “”,
GRATIS: false,
PRIJS_DEUR: “”,
PRIJS: “”,
REEKSDATA:
[
{
UITVERKOCHT: false,
EIND_DATUM: “”,
TIJDTOELICHTING: “”,
ID: 22723022,
GEANNULEERD: false,
START_DATUM: “2015-02-17T21:00:00+01:00”
},
],
LOCATIETOELICHTING: “”,
TICKETINFO: “”,
IDORGANISATIES: 10592,
TICKETURL: “reservationAndSelling”,
PRIJS_KIND: “”,
ID: 25765
},
],

In de data kan je de prijs (PRIJS_OUDEREN, PRIJS_CJP, PRIJS en PRIJS_DEUR en GRATIS) en locatie (LOCATIETOELICHTING) vinden van de activiteit. In de activiteit is ook de IDORGANISATIES opgenomen waardoor je gemakkelijk andere activiteiten van dezelfde organisatie kan zoeken.

Een activiteit kan meerdere keren plaatsvinden. Elke ‘happening’ is onder de tag REEKSDATA opgenomen. In deze reeks zijn de datum en tijd (START_DATUM en EIND_DATUM) opgenomen en of deze geannuleerd zijn.

Ook zijn LEEFTIJDCLASSIFICATIE en de ACTIVITEITENSOORT geven in de data. Je kan hier dus alsnog op filteren. Hier is niet de ID opgenomen, maar de volledige naam (dus niet ‘ID: 10′ maar ’18 +’).

In de activiteit is ook een TITEL en een LEAD opgenomen met informatie over wat voor activiteit het is. In dit geval gaat het om een Apres Ski Party. Deze informatie is ‘user friendly’ en dus bruikbaar binnen je eigen app.

Organisaties

Naast activiteiten is er ook veel data opgenomen over organisaties die activiteiten aanbieden. Je kan deze bereiken door http://www.uitinnoordholland.nl/api/agenda/organisaties aan te roepen. Ook hier kan je format=XML gebruiken. Een voorbeeld van de respons is:

{
LNG: 4.63517189999993,
POSTCODE: “”,
NAAM: “#FF Verderop”,
GEMEENTE: “Haarlemmermeer”,
TOEVOEGDATUM: “2014-10-15T15:56:58+01:00”,
LAT: 52.2635733,
BEZOEKADRES: “St. Anthoniusstraat 5”,
TELEFOON: “”,
OPENINGSTIJDEN: “”,
OMSCHRIJVING: “”,
TOEGANKELIJKHEID: “”,
WWW: “”,
PLAATS: “Nieuw-Vennep”,
ID: 19501,
WIJZIGDATUM: “2014-10-15T16:01:55+01:00”,
EMAIL: “”,
URL: “http://www.uitinnoordholland.nl/agenda/agenda/organisatie/q/idorganisatie/19501/titel/ff-verderop”
}

Voor de organisatie zijn de adresgegevens opgenomen (POSTCODE, PLAATS, BEZOEKADRES). Daarnaast is in de data LNG en LAT opgenomen. Dit zijn longitude respectievelijk latitude: geo-locaties. De organisatie kan je dus eenvoudig tonen op een kaart. Maar je kan ook de locatiegegevens van een mobiele telefoon gebruiken om aan te geven dat er een evenement in de buurt is.

Interessant is dat je op basis van een activiteit ook een organisatie kan ophalen. Bij een activiteit is een organisatie-ID (IDORGANISATIE) opgenomen. Deze kan je gebruiken om de gegevens van een specifieke organisatie op te halen door bijv. de query http://www.uitinnoordholland.nl/api/agenda/organisaties?id=13196 te doen. Zo kan je bijvoorbeeld nu achterhalen dat de Aprés Ski Party van zojuist georganiseerd is door Café De Zaak is in Hoofddorp. Vaak is de organisator ook de locatie van het evenement.

Dagje of avondje uit?

Met deze API heb je toegang tot alle activiteiten in Noord-Holland. Met diverse filters kan je gemakkelijk zoeken op activiteiten voor jouw publiek. Daarmee is de UIT-API een mooie toevoeging voor culturele of toeristische apps.