OData API

Gebruik de OData API voor het opvragen van data met een zelfopgestelde zoekvraag in de vorm van een URL (query). De OData API levert de data in het machineleesbare bestandsformaat JSON.

Locatie en versie

Locatie OData  API-data
gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/ v4 2.0
Image

Datamodel, entiteiten en attributen

Het datamodel dat gebruikt wordt in de OData API is gelijk aan het informatiemodel van het Gegevensmagazijn. Het informatiemodel geeft een overzicht van alle entiteitsoorten die opgevraagd kunnen worden middels de OData API en hun onderlinge relaties. Op de detailpagina's van de entiteitsoorten is te zien welke attributen een entiteit van een bepaalde entiteitsoort heeft en worden voorbeelden gegeven.

Ga naar de documentatiepagina over het informatiemodel

Image

 

Opstellen van een query

Het opstellen van een query bestaat uit het kiezen van een entiteitsoort als beginpunt en het toevoegen van functies met argumenten om zo tot de gewenste resultaten te komen. Wanneer er geen functies toegevoegd worden aan een query zullen alle entiteiten van een entiteitsoort getoond worden.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Document
Alle entiteiten van de entiteitsoort Document

Om de data van een specifieke entiteit te tonen kan de waarde van het attribuut id gebruikt worden. 

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Document(7a9b77f1-
d230-4a00-9856-2f0f8e967e62
)
Specifieke entiteit van de entiteitsoort Document

Wanneer een specifieke entiteit een achterliggend bestand heeft, kan deze worden opgehaald door /resource aan de query toe te voegen.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Document(7a9b77f1-
d230-4a00-9856-2f0f8e967e62)
/resource
Bestand behorende bij een specifieke entiteit van de entiteitsoort Document

Bekijk ook de documentatie op de website van OData voor meer informatie over het opstellen van queries.

Ga naar de officiële documentatie van OData

Image

Toevoegen van functies

Om functies toe te voegen aan een query dient een ? toegevoegd te worden achter de entiteitsoort of de specifieke entiteit die als beginpunt is gekozen. Ieder daaropvolgende functie dient te beginnen met &, en de argumenten van een functie komen achter een =. 

Filteren op attributen met $filter

De functie $filter maakt het mogelijk om de resultaten van een query te filteren op basis van de waardes van attributen. In de argumenten van $filter kunnen vergelijkingsoperatoren (eq, ne, gt, lt, ge, le) en Booleaanse operatoren (and, or, not) gebruikt worden om de resultaten te vernauwen of verruimen. Het is aan te raden om altijd te filteren op entiteiten die niet zijn verwijderd daar verwijderde entiteiten als placeholder in het Gegevensmagazijn blijven bestaan om wijzigingen te kunnen herleiden.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Persoon?$filter=
Verwijderd eq false and (Functie eq
'Eerste Kamerlid' or Functie eq
'Tweede Kamerlid')
Alle entiteiten van de entiteitsoort Persoon waarvan de waarde van het attribuut Functie gelijk is aan Eerste Kamerlid of Tweede Kamerlid 

Met de operatoren startswith(), endswith() en contains() als argument van de functie $filter kan op gedeeltes van de waarde van een bepaald attribuut gefilterd worden.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Persoon?$filter=
Verwijderd eq false and(startswith(
Roepnaam, 'd') or endswith(
Roepnaam, 'd'))
Alle entiteiten van de entiteitsoort Persoon waarvan de waarde van het attribuut Roepnaam begint of eindigt met een 'd'

Voor het filteren met datums in argumenten van de functie $filter zijn er de operatoren second(), minute(), day(), hour(), month() en year()

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Persoon?$filter=
Verwijderd eq false and year(
Geboortedatum) le 1850
Alle entiteiten van de entiteitsoort Persoon waarvan de waarde van het attribuut Geboortedatum kleiner dan of gelijk is aan het jaartal 1850

Als een entiteit een relatie heeft met entiteiten van een andere entiteitsoort, kan de oorspronkelijke entiteit gefilterd worden op basis van de waardes van attributen van de gerelateerde entiteitsoort. Bij op-één-relaties kan er gefilterd worden door in de functie $filter met een / te verwijzen naar de gerelateerde entiteitsoort en het attribuut. 

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/FractieZetelVacature
?$filter=Verwijderd eq false and
TotEnMet eq null and Fractiezetel/
Fractie/DatumInactief eq null

Alle entiteiten van de entiteitsoort FractieZetelVacature waarvan de waarde van het attribuut TotEnMet gelijk is aan null en de waarde van het attribuut DatumInactief van de via entiteiten van de entiteitsoort FractieZetel gerelateerde entiteiten van de entiteitsoort Fractie gelijk is aan null (i.e. alle actieve vacatures voor vacante zetels in de Tweede Kamer)

Bij op-veel-relaties kan er gefilterd worden door in de functie $filter gebruik te maken van de operatoren any() en all(). De operator any() dient gebruikt te worden wanneer één van de gerelateerde entiteiten door de filter heen moet komen om een entiteit in de resultaten te laten zien.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Persoon?$filter=
Verwijderd eq false and FractieZetelPersoon/any(a:a/
TotEnMet eq null)
Alle entiteiten van de entiteitsoort Persoon die niet zijn verwijderd waarvan de waarde van het attribuut TotEnMet van één van de gerelateerde entiteiten van de entiteitsoort FractieZetel Persoon gelijk is aan null (i.e. alle active Tweede Kamerleden)

De operator all() dient gebruikt te worden wanneer alle gerelateerde entiteiten door de filter heen moeten komen om een entiteit in de resultaten te laten zien.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Persoon?$filter=
Verwijderd eq false and
PersoonNevenfunctie/any(a:a/
Verwijderd eq false) and
PersoonnevenFunctie/all(b:b/
VergoedingSoort ne 'Onbezoldigd')
Alle entiteiten van de entiteitsoort Persoon die gerelateerde entiteiten van de entiteitsoort PersoonNevenfunctie hebben waarvan de waarde van het attribuut VergoedingSoort niet altijd gelijk is aan Onbezoldigd 

Attributen van resultaten beperken met $select

De functie $select maakt het mogelijk om te kiezen welke attributen van een entiteit in de resultaten getoond worden. Deze functie kan onder andere ingezet worden om de grootte van de resultaten te beperken daar standaard alle attributen getoond worden.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/|Commissie?$filter=
Verwijderd eq false&$select=
NaamNL,Afkorting
Alle entiteiten van de entiteitsoort Commissie met alleen de attributen NaamNL en Afkorting zichtbaar

Gerelateerde entiteiten ophalen met $expand

De functie $expand maakt het mogelijk om bij een entiteit alle gerelateerde entiteiten van een andere entiteitsoort te tonen in de resultaten. Het is mogelijk om binnen een $expand door middel van ( ) functies toe te passen op de resultaten van de $expand. Om meerdere functies toe te passen op de resultaten van een $expand dient een ; gebruikt te worden in plaats van een &.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Zaak?$filter=
verwijderd eq false and Soort eq
'Motie'&$expand=ZaakActor($filter
=relatie eq 'Indiener')
Alle entiteiten van de entiteitsoort Zaak waarvan de waarde van het attribuut Soort gelijk is aan Motie met de bijbehorende entiteiten van de entiteitsoort ZaakActor waarvan de waarde van het attribuut Relatie gelijk is aan Indiener

Resultaten overslaan met $skip

De functie $skip maakt het mogelijk om een bepaald aantal resultaten over te slaan. Om de belasting van individuele queries op het Gegevensmagazijn te minimaliseren worden standaard maximaal 250 resultaten tegelijkertijd weergegeven. Dit geldt ook voor het aantal entiteiten dat met de functie $expand opgehaald kan worden. Wanneer een query meer dan 250 resultaten geeft staat er onderaan de pagina een query die leidt naar de volgende pagina.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/DocumentVersie?
$
filter=Verwijderd eq false&
$skip=
250
Alle entiteiten van de entiteitsoort Documentversie op de eerste 250 na (i.e. pagina 2 van de resultaten) 

Resultaten beperken met $top

De functie $top maakt het mogelijk om het aantal resultaten te beperken.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Reservering?$top
=25
De eerste 25 entiteiten van de entiteitsoort Reservering

Resultaten sorteren met $orderby

De functie $orderby maakt het mogelijk om de resultaten te sorteren op basis van de waarde van een attribuut. De argumenten asc (oplopend) en desc (aflopend) kunnen gebruikt worden om de volgorde te bepalen. 

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Activiteit?
$filter=
Verwijderd eq false&
$expand=
Agendapunt($orderby=Volgorde
asc)
Alle entiteiten van de entiteitsoort Activiteit met de bijbehorende entiteiten van de entiteitsoort Agendapunt oplopend gesorteerd op de waarde van het attribuut Volgorde 

Resultaten tellen met $count

De functie $count maakt het mogelijk om het totaal aantal resultaten te weergeven. De argumenten van de functies $skip en $top worden hierbij genegeerd.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/PersoonNevenfunctie
?$filter=Verwijderd eq false&$count
=true
Alle entiteiten van de entiteitsoort PersoonNevenfunctie die niet verwijderd zijn met het totaal aantal resultaten

Het metadataniveau bepalen met $format

De functie $format maakt het mogelijk om in te stellen hoeveel metadata van entiteiten getoond wordt. Er zijn drie metadataniveaus beschikbaar: none, minimal en full. De extra metadata helpen bij het beter begrijpen van een entiteitsoort (beschikbare argumenten voor de functie $expand, achterliggende bestanden, etc.). In productie is het aan te raden om gebruik te maken van het metadataniveau none om de grootte van de resultaten te beperken.

Voorbeeld Resultaat
gegevensmagazijn.tweedekamer.nl/
OData/v4/2.0/Fractie?
$filter=
Verwijderd eq false&
$format=
application/json;odata.metadata=full
Alle entiteiten van de entiteitsoort Fractie die niet verwijderd zijn met de volledige metadata
Image

Nog vragen? Kijk bij de veelgestelde vragen of het antwoord erop er al bijstaat.