API documentatie – ScienceOut

ScienceOut API versie 1

Technische documentatie

De ScienceOut API is een alleen-lezen REST API waarmee agenda items van ScienceOut opgehaald kunnen worden. De API geeft de items terug in JSON formaat. Er zijn drie API's:

Zoek – zoeken naar specifieke items
Uitgelicht – uitgelichte items van de homepage
Tips – tips van de homepage

API toegangssleutel

Om toegang te krijgen tot de API heb je eerst een toegangssleutel nodig.
Maak een toegangssleutel aan.

Logo en link verplicht

Als je gebruik maakt van de ScienceOut API ben je verplicht om het logo en een link naar ScienceOut op te nemen. Voorbeeld:

agenda via

agenda via
<a href="http://www.scienceout.nl/">
  <img src="http://www.scienceout.nl/static/widget/scienceout.png" alt="ScienceOut.nl">
</a>

Zoek API

Het ophalen van agenda items doe je met een HTTP GET request aan de Zoek API.

URL

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL

Parameters

Alle parameters zijn optioneel.

query

Zoek query. Moet URL-encoded zijn.

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&query=mist%20u%20de%20dodo

per_pagina

Het aantal activiteiten dat de API teruggeeft. Maximaal: 20. Standaard: 20.

De API geeft informatie over het aantal resultaten:

{"totaal": 135, "pagina": 1, "per_pagina": 20, "items": […]}

Hiermee kun je het aantal pagina’s in het resultaat uitrekenen. Om een andere pagina op te vragen geef je de pagina parameter mee:

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&per_pagina=10&pagina=6

organisatie

ID van een organisatie. Je kunt maar één organisatie opgeven.

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&organisatie=1

Overzicht van organisaties op ScienceOut – het ID vind je in de URL van een organisatie: http://www.scienceout.nl/organisaties/339

thema

ID van een thema. Je kunt maar één thema opgeven.

Onderwijs	3
Gelegerd in Gelderland	8

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&thema=1

periode

Zoek naar activiteiten in een bepaalde periode. Je kunt maar één periode opgeven. Mogelijke periodes:

vandaag, morgen, weekend, week, maand.

Bij week en maand kijkt de API of het zinvol is om items van deze week/maand of van volgende week/maand terug te geven.

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&periode=morgen

start, eind

Voor het opvragen van items in een specifieke periode. Formaat: dd-mm-yyyy

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&start=26-10-2010&eind=05-11-2010

doelgroep

ID van een doelgroep. Standaard zoekt de API door alle doelgroepen. Doelgroepen op ScienceOut:

kinderen	1
volwassenen	2
jongeren	4

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&doelgroep=1

doelgroep[]

Gebruik deze construct om meerdere doelgroepen op te geven. Parameter moet URL-encoded zijn: http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&doelgroep%5B%5D=1&doelgroep%5B%5D=2

soort

ID van een soort. Standaard zoekt de API door alle soorten. Soorten op ScienceOut:

tentoonstelling	1
festival	2
lezing / debat	3
excursie / rondleiding	4
workshop	5
voorstelling / demonstratie	6
experiment / proefjes	8
wedstrijd / prijsvraag	10
congres / symposium	11
online	12
interview	13
overig	14
cursus	16
oratie / promotie / afscheidscollege	18
open dag	19
sterren kijken	20
vakantieprogramma	21

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&soort=1

soort[]

Gebruik deze construct om meerdere soorten op te geven. Parameter moet URL-encoded zijn: http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&soort%5B%5D=1&soort%5B%5D=2

provincie

ID van een provincie. Standaard zoekt de API door alle provincies. Provincies op ScienceOut:

Noord-Holland	1
Friesland	2
Groningen	3
Drenthe	4
Flevoland	5
Overijssel	6
Gelderland	7
Utrecht	8
Zuid-Holland	9
Zeeland	10
Noord-Brabant	11
Limburg	12

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&provincie=1

provincie[]

Gebruik deze construct om meerdere provincies op te geven. Parameter moet URL-encoded zijn: http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&provincie%5B%5D=1&provincie%5B%5D=2

onderwerp

ID van een onderwerp. Standaard zoekt de API door alle onderwerpen. Onderwerpen op ScienceOut:

aardwetenschappen	1
archeologie	2
astronomie	3
biologie	4
communicatiewetenschappen & media	5
culturele antropologie	6
cultuurwetenschappen	7
economie & bedrijfskunde	8
filosofie	9
gedragswetenschappen	10
geneeskunde	11
geschiedenis	12
industrie en industrieel erfgoed	13
informatica ICT	14
kunstgeschiedenis CKV	15
literatuurwetenschappen	16
meteorologie	17
natuurkunde	18
onderwijskunde	19
paleontologie	20
pedagogiek	21
politicologie	22
psychologie	23
rechtswetenschappen	24
ruimtevaart	25
scheikunde	26
sociale geografie	27
sociologie	28
taalwetenschap	29
techniek	30
telecommunicatie	31
transport & logistiek	32
wiskunde	33
biotechnologie	34
nanotechnologie	35
architectuur	37
neurowetenschappen	38
duurzaamheid en klimaat	39
zoölogie	40
aardrijkskunde	41
antropologie	42
criminologie	43
film- en televisiewetenschap	44
polemologie	45
planologie	46
theologie	47
voeding & diëtetiek	48

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&onderwep=1

onderwerp[]

Gebruik deze construct om meerdere onderwerpen op te geven. Parameter moet URL-encoded zijn: http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&onderwerp%5B%5D=1&onderwerp%5B%5D=2

callback

Als er een callback aanwezig is, zal de response in JSONP zijn met de opgegeven callback.

http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&callback=fooShow

fooShow({
  "totaal": 135,
  "pagina": 1,
  "per_pagina": 20,
  "items": […]
})

Uitgelicht API

Het ophalen van uitgelichte activiteiten doe je met een HTTP GET request aan de Uitgelicht API.

URL

http://www.scienceout.nl/api/v1/uitgelicht.json?sleutel=SLEUTEL

Parameters

Alle parameters zijn optioneel.

aantal

1, 2 of 3. Er zijn altijd 3 uitgelichte activiteiten op ScienceOut.

http://www.scienceout.nl/api/v1/uitgelicht.json?sleutel=SLEUTEL&aantal=2

callback

Als er een callback aanwezig is, zal de response in JSONP zijn met de opgegeven callback.

http://www.scienceout.nl/api/v1/uitgelicht.json?sleutel=SLEUTEL&callback=fooShow

Tips API

Het ophalen van tips doe je met een HTTP GET request aan de Tips API.

URL

http://www.scienceout.nl/api/v1/tips.json?sleutel=SLEUTEL

Parameters

Alle parameters zijn optioneel.

aantal

1–10. Het aantal tips op ScienceOut is variabel.

http://www.scienceout.nl/api/v1/tips.json?sleutel=SLEUTEL&aantal=5

callback

Als er een callback aanwezig is, zal de response in JSONP zijn met de opgegeven callback.

http://www.scienceout.nl/api/v1/tips.json?sleutel=SLEUTEL&callback=fooShow

Voorbeeld JSON response

De API geeft de gevonden items terug als JSON.

{
  "totaal":141,
  "pagina":1,
  "per_pagina":2,
  "items": [
    {
      "titel":"De Grote Kanarietentoonstelling",
      "ondertitel":"Natuur en cultuur van een volksvogel",
      "beschrijving":"De kanarie is de populairste vogel ooit. Maar hoe werden zijn veren
                      ‘kanariegeel’ en waarin schuilt het geheim van zijn zangkwaliteiten?",
      "url":"http://www.scienceout.nl/agenda/a1e34n0fth",
      "locatie":"Natuurhistorisch Museum Rotterdam, Rotterdam",
      "adres":"Natuurhistorisch Museum Rotterdam, Westzeedijk 345, 3015 AA Rotterdam, Nederland",
      "telefoon":"+31 (0)10 436 42 22",
      "e-mailadres":"…",
      "lees_meer":"http://www.nmr.nl",
      "lat":51.9107,
      "lng":4.47374,
      "soort":"tentoonstelling",
      "datum_indicatie":"sinds 1 mei",
      "provincie":"Zuid-Holland",
      "doelgroep":"jongeren, kinderen, volwassenen",
      "onderwerp":"biologie",
      "tags":"vogels, vogelzang, fokken",
      "img":"http://www.scienceout.nl/system/files/000/000/624/original/retrieveFile.jpg",
      "img_medium":"http://www.scienceout.nl/system/files/000/000/624/detail/retrieveFile.jpg",
      "img_small":"http://www.scienceout.nl/system/files/000/000/624/live/retrieveFile.jpg",
      "datum_type":2,
      "data":
        {"start_datum":"2010-05-01",
         "eind_datum":"2010-09-26",
         "start_tijd":"10:00",
         "eind_tijd":"17:00"}
    },
    {
      "titel":"Leve(n in) het heelal",
      "ondertitel":null,
      "beschrijving":"Tijdens Oktober Kennismaand worden speciale presentaties (films,
                      video's, lezingen) rond het thema 'Leven in het heelal' gehouden.",
      "url":"http://www.scienceout.nl/agenda/o55cq3ps29",
      "locatie":"Streekmuseum Volkssterrenwacht Burgum, Burgum"
      "adres":"Streekmuseum Volkssterrenwacht Burgum, Menno van Coehoornweg 9, 9251 LV Burgum, Nederland",
      "telefoon":"+31 (0)511 465 544",
      "e-mailadres":"…",
      "lees_meer":"http://www.streekmuseum-volkssterrenwachtburgum.nl/",
      "lat":53.2037,
      "lng":6.0005,
      "soort":"festival",
      "datum_indicatie":"vanaf 1 oktober",
      "provincie":"Limburg",
      "doelgroep":"jongeren, kinderen, volwassenen",
      "onderwerp":"astronomie, ruimtevaart",
      "tags":"",
      "img":"http://www.scienceout.nl/system/files/000/000/839/original/ISS.png",
      "img_medium":"http://www.scienceout.nl/system/files/000/000/839/detail/ISS.png",
      "img_small":"http://www.scienceout.nl/system/files/000/000/839/live/ISS.png",
      "datum_type":1,
      "data":[
        {"dag":"2010-10-01",
         "start_tijd":"19:00",
         "eind_tijd":"22:30"},
        {"dag":"2010-10-02",
         "start_tijd":"14:00",
         "eind_tijd":"16:30"},
        {"dag":"2010-10-08",
         "start_tijd":"19:00",
         "eind_tijd":"22:30"},
        {"dag":"2010-10-09",
         "start_tijd":"14:00",
         "eind_tijd":"16:30"},
        {"dag":"2010-10-15",
         "start_tijd":"19:00",
         "eind_tijd":"22:30"},
        {"dag":"2010-10-16",
         "start_tijd":"14:00",
         "eind_tijd":"16:30"},
        {"dag":"2010-10-22",
         "start_tijd":"19:00",
         "eind_tijd":"22:30"},
        {"dag":"2010-10-23",
         "start_tijd":"14:00",
         "eind_tijd":"16:30"},
        {"dag":"2010-10-29",
         "start_tijd":"19:00",
         "eind_tijd":"22:30"},
        {"dag":"2010-10-30",
         "start_tijd":"14:00",
         "eind_tijd":"16:30"}]
    }
  ]
}

Uitleg van een paar begrippen

totaal, pagina, per_pagina: Informatie over het totaal aantal gevonden resultaten, de huidige pagina binnen de set van resultaten, het aantal resultaten per pagina.
url: De URL van de activiteit op ScienceOut.
lees_meer: Theoretisch een URL waar meer te lezen is over de activiteit, maar meestal is dit een link naar de homepage van de organisatie.
datum_type: ScienceOut kent twee manieren om de data van een activiteit op te geven: als aaneengesloten periode (datum_type = 1), of als losse dagen (datum_type = 2).
datum_indicatie: De datum indicatie van een activiteit zoals gebruikt op ScienceOut, voorbeelden: op 1 mei, sinds 1 mei, vanaf 1 mei

Foutafhandeling

De API geeft een foutmelding als de toegangssleutel onjuist is, dit is een JSON response:

{
  "items":[],
  "error":"Ongeldige API sleutel."
}

Als de API geen resultaten kon vinden, geeft de API een ‘lege’ JSON response terug:

{
  "totaal":0,
  "pagina":1,
  "per_pagina":20,
  "items":[ ]
}

jQuery voorbeeld

jQuery(function($) {
  // ScienceOut Agenda
  var agenda = $("#agenda");
  agenda.hide();
  $.getJSON (
    "http://www.scienceout.nl/api/v1/zoek.json?sleutel=SLEUTEL&organisatie=1&per_pagina=10&callback=?",
    function (data) {
      $.each (data.items, function (i, item) {
        agenda.append ($('<li/>').
               append ('<p><img src='+item.img_small+'></p>').
               append ('<div><h4><a href="'+item.lees_meer+'">'+item.titel+'</a></h4>').
               append ('<p>'+item.beschrijving+' <a href="'+item.lees_meer+'\">Meer</a></p></div>').
               append ('<p>'+item.datum_indicatie+'</p'))
      });
      if (data.items) {
        agenda.show('fast');
      }
    }
  );
});

ScienceOut

ScienceOut API versie 1

API toegangssleutel

Logo en link verplicht

Zoek API

URL

Parameters

Uitgelicht API

URL

Parameters

Tips API

URL

Parameters

Voorbeeld JSON response

Uitleg van een paar begrippen

Foutafhandeling

jQuery voorbeeld

Inhoud

Feedback

Widget