U bent hier

OData API 2.0

Open Data Protocol (OData) versie 4 is een open protocol voor het ontwikkelen van REST API’s. OData wordt in veelgebruikte applicaties zoals bijv. Excel en Microsoft Power BI standaard ondersteund als bron. Er is op het internet veel informatie beschikbaar voor ontwikkelaars hoe OData API’s bevraagd kunnen worden. Het OData protocol leent zich goed om een snapshot van verschillende entiteiten in samenhang op te kunnen halen met behulp van een enkele zoekvraag. Via de OData v4 API kan informatie opgevraagd worden in JSON formaat.

Er is op internet veel informatie beschikbaar voor ontwikkelaars hoe OData API's bevraagd kunnen worden. Hieronder vindt u enkele handige (Engelstalige) links over OData:

# URL OData versie API-data versie Opmerkingen

1

/OData/v4/2.0/

4 (json)

2.0

Maakt gebruik van OData v4 protocol, deze ondersteunt JSON.

De volledige URL van de OData v4 API is:
https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/

Datamodel OData

De data in OData komt overeen met het informatiemodel. Gegevens in OData zijn anders gemodelleerd dan in de SyncFeed. De SyncFeed is gebaseerd op XML opslag, OData slaat de data relationeel op. Per entiteit krijgt u steeds uitbreidingsmogelijkheden (expands) om gerelateerde data uit andere entiteiten erbij te zoeken.

OData entiteiten Opmerkingen

Activiteit

ActiviteitActor

Agendapunt

Besluit

Commissie

CommissieContactinformatie

CommissieZetelVastPersoon

CommissieZetelVastVacature

CommissieZetelVervangerPersoon

CommissieZetelVervangerVacature

CommissieZetel

Document

 Inclusief download link naar bestand: doc(x)/pdf.

DocumentActor

DocumentVersie

Fractie

(Optioneel)
Inclusief download link naar fractie logo afbeelding.

FractieAanvullendGegeven

FractieZetel

FractieZetelPersoon

FractieZetelVacature

Kamerstuk

Kamerstukdossier

Persoon

(Optioneel)
Inclusief download link naar persoon foto afbeelding.

PersoonContactinformatie

PersoonGeschenk

PersoonLoopbaan

PersoonNevenfunctie

PersoonNevenfunctieInkomsten

PersoonOnderwijs

PersoonReis

Reservering

Stemming

Vergadering

Verslag

Inclusief download link naar volledige XML.

Zaak

ZaakActor

Zaal

Algemene kolommen

De entiteiten hebben allen de volgende kolommen:

Kolomnaam Opmerkingen

Id

GUID (Globally Unique Identifier) van de entiteit.

GewijzigdOp

Datum wanneer het bronsysteem deze entiteit heeft aangemaakt/aangepast.

ApiGewijzigdOp

Datum wanneer deze entiteit (mutatie) zichtbaar is geworden in de OData API. Filteren op dit veld maakt het mogelijk om alleen verschillen op te halen van een bepaalde periode.

Verwijderd

Komt overeen met verwijderd=true/false op entiteit niveau uit de SyncFeed. Er is bewust voor gekozen alle verwijderde entiteiten als “placeholder” zichtbaar te houden in de API zodat afnemers kunnen detecteren wanneer iets verwijderd is. Wanneer u enkel bestaande entiteiten wilt opvragen dient u zelf te filteren op “Verwijderd eq false”.

Query voorbeelden

OData heeft een eigen querytaal voor het opvragen van data. Hieronder staan een aantal queries om mee te beginnen:

Omschrijving Query
Algemeen: opvragen beschikbare entiteiten en functies /$metadata
Opvragen commissieleden (Afkorting nu op FIN) /Persoon?$expand=CommissieZetelVastPersoon, CommissieZetelVastPersoon($expand=CommissieZetel($expand=Commissie))&$orderby=Achternaam&$filter=CommissieZetelVastPersoon/any(aa: aa/CommissieZetel/Commissie/Afkorting eq 'FIN' and aa/TotEnMet eq null)
Opvragen actieve Kamerleden van een fractie Persoon?$filter=FractieZetelPersoon/any(a:a/FractieZetel/Fractie/Afkorting eq '<<afkorting hier invullen>>') and FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))&$format=application/json;odata.metadata=full
Kamerleden: alle actieve /Persoon?$orderby=Achternaam&$filter=FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))&$count=true
Activiteiten: per vergaderjaar /Activiteit?$filter=Vergaderjaar eq '2015-2016'&$orderby=Aanvangstijd desc
Parlementaire documenten: moties, zoek in onderwerp (voorbeeld ‘beveiliging’) /Document?$filter=Soort eq 'Motie' and contains(Onderwerp,'beveiliging')
Activiteiten opvragen van een bepaalde maand (voorbeeld mei 2019) /Activiteit?$filter=year(Aanvangstijd) eq 2019 and month(Aanvangstijd) eq 5&$orderby=Aanvangstijd desc
Geef de vergaderingen met links naar de verslagen uit 2017-2008 in JSON formaat en oplopend gesorteerd op Begin.

/Vergadering?$expand=Verslag&$filter=Vergaderjaar eq '2018-2019'&$orderby=Datum desc&$format=application/json;odata.metadata=full
(In de expand /Verslag staat de download naar de XML in: Resource/target)

Document download

/Document?$format=application/json;odata.metadata=full&$filter=DocumentNummer eq '2009D35955'
Via /Resource is het document te downloaden.
/Document(<<guid invoeren>>)/TK.DA.GGM.OData.Resource()" of in het kort: /Document(<<guid invoeren>>)/Resource

Persoon afbeelding download (optioneel)

/Persoon?$orderby=Achternaam&$filter=Achternaam eq 'Pechtold'&$format=application/json;odata.metadata=full
Via /Resource is de afbeelding te downloaden.
/Persoon(<<guid invoeren>>)/TK.DA.GGM.OData.Resource()" of in het kort: /Persoon(<<guid invoeren>>)/Resource

Per kamerstukdossier de activiteiten opvragen waar deze in behandeld is. /Zaak?$filter=Agendapunt/any(a:a ne null) and Kamerstukdossier/any(d: d/Nummer eq 34986) and Verwijderd eq false&$format=application/json;odata.metadata=full&$expand=Agendapunt($expand=Activiteit)

(Let op: u moet het adres van het end-point voor de query plaatsen. Bijvoorbeeld: https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/)

De volgende functies zijn universeel te gebruiken in de queries:

Functie v4
expand $expand=Besluit($expand=Agendapunt($expand=Activiteit))
entiteiten tellen $count=true
pagineren $skip=250
filteren op datum $filter=Datum gt 2017-01-01T00:00:00Z
filteren op datum/tijd/tijdzone $filter=Datum gt 2019-03-07T00:00:00%2B01:00 (waarbij de plus (+) van de tijdzone wordt encoded met %2B).
filteren binnen expand /Persoon?$filter=FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))
sorteren binnen entiteit /Activiteit?$orderby=Nummer desc
sorteren binnen expand met filter /Activiteit?$expand=Agendapunt($orderby=Nummer desc)&$filter=Nummer eq '2015A04079'
eerste x (10) resultaten tonen $top=10
meerdere waarden tegelijk filteren /Activiteit?&$filter=Nummer in ('2009A00380','2015A04079')

Dit zijn slechts enkele voorbeelden, OData v4 heeft nog een hoop andere functies. Raadpleeg de officiële OData documentatie voor alle mogelijkheden: http://www.odata.org/

Om de server niet te veel te belasten worden standaard maximaal 250 resultaten tegelijk weergegeven. Ook voor expands geldt een maximum van 250 resultaten. Bij meer dan 250 resultaten staat er aan het einde van de resultatenlijst een verwijzing naar de volgende pagina.
Een voorbeeld:
@odata.nextLink:
"https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/Persoon?$skip=250"

Metadata niveaus

Binnen OData v4 zijn er verschillende "metadata niveaus", deze helpen bij het begrijpen van de verschillende functies (expands, download links) per entiteit. Het is aan te raden om tijdens het ontwikkelen van een koppeling gebruik te maken van de "full" metadata optie. Hieronder de mogelijkheden met daarbij voorbeelden en een omschrijving:

Metadata niveau Voorbeeld Omschrijving
none /Activiteit?$format=application/json;odata.metadata=none Geeft geen metadata, dit is sneller en kan schelen in laadtijden.
minimal /Activiteit?$format=application/json;odata.metadata=minimal Heeft een minimale set aan metadata.
full /Activiteit?$format=application/json;odata.metadata=full Geeft alle expand mogelijkheden.