Documentatie van de API

Deze pagina beschrijft op hoofdlijnen hoe de API werkt.
Direct geïnteresseerd in de details? Naar de technische beschrijving van alle API-functies.

Soorten gegevens

Het Participatieprikbord bevat gegevens over accommodaties, activiteiten en initiatieven. Vanuit een technisch perspectief zijn activiteiten en initiatieven hetzelfde: in de API komen daarom geen initiatieven voor, maar uitsluitend accommodaties en activiteiten.

Functies

De API maakt accommodaties en activiteiten doorzoekbaar, levert details van accommodaties en activiteiten en routeert reacties van website-bezoekers naar de juiste contactpersoon. De volgende tabel beschrijft welke functies er zijn. Daarbij is ook aangegeven welke extra mogelijkheden er zijn voor geregistreerde API-gebruikers.

Wat Anonieme API-gebruiker Geregistreerde API-gebruiker
Gebruikslimiet Maximaal 1.000 requests per IP-adres per dag Maximaal 50.000 requests per geregistreerde gebruiker per dag
Zoeken naar accommodaties Ja, maar zonder facetten (facetten = aantal zoekresultaten op bepaalde kenmerken) Ja, met facetten
Zoeken naar activiteiten Ja, maar zonder facetten Ja, met facetten
Eén accommodatie opvragen Ja Ja
Eén activiteit opvragen Ja Ja
Reactie op een accommodatie doorsturen naar de beheerder Nee Ja (zie toelichting hieronder)
Reactie op een activiteit doorsturen naar de organisator Nee Ja: reacties van accommodatiebeheerders, vrijwilligers en deelnemers (zie toelichting hieronder)

Reacties doorsturen

Geregistreerde API-gebruikers kunnen op hun website reactieformulieren aanbieden. Deze formulieren moeten zelf worden gebouwd en bepaalde velden bevatten (zie technische beschrijving van de API). Ingevulde formulieren worden via de API doorgestuurd naar de accommodatiebeheerder of organisator gestuurd in de vorm van een e-mail.

Technologie

De API gebruikt JSON (JavaScript Object Notation).

Ook JSON-P wordt ondersteund, bijvoorbeeld:https://api.participatieprikbord.denhaag.nl/api/v1/activities.jsonp?callback=myCallBackName&limit=1

Naar de technische beschrijving van alle API-functies

In de technische beschrijving is een testomgeving ingebouwd. Klik op Sandbox om een bepaalde functie direct te kunnen testen.

Voorbeelden

Enkele voorbeelden van het gebruik van de API.

Voorbeeld 1: ophalen activiteiten

<?php
$baseUrl = 'https://api.participatieprikbord.denhaag.nl/api/v1/';
$action = 'activities.json?';
$today = date_create();
$query = http_build_query(
			array(
				//API key as provided at registration
				'apikey' => '<your-api-key-here>',

				//Needs => 1 will filter activities on the need for volunteers
				'needs' => '1',

				//Date from: only activities that take place today or in the future
				'date_from' => $today->format('Y-m-d'),

				'date_to' => $today->add(new DateInterval('P3M'))->format('Y-m-d'),

				  )
		  );
print_r('Request parameters are: '.$query);
$apiUrl = $baseUrl.$action.$query;
$json = file_get_contents($apiUrl);
$obj = json_decode($json);
foreach ($obj->result as $act):?>
    <p><a href="<?php echo $act->url[0] ?>"><?php echo $act->title ?></a><br/>
    <?php echo $act->description ?></p>
    <p>Vrijwilligers:<br/><?php echo $act->volunteer_tasks ?></p>
    <p>Te vinden op:<br/>
        <?php foreach ($act->url as $url): ?>
        <a href="<?php echo $url ?>"><?php echo $url ?></a><br/>
        <?php endforeach ?>
    </p>
<?php endforeach; ?>