U bent hier

SyncFeed API 2.0

De SyncFeed welke is gebaseerd op de Atom 1.0 (XML) standaard heeft als doel om zo eenvoudig mogelijk (een subset van) alle data van het Open Data Portaal te synchroniseren met een eigen database. Dit stelt afnemers in staat om met behulp van eigen indexering en query strategieën de grote hoeveelheid informatie op een intuïtieve en efficiënte manier te raadplegen en te gebruiken. Doordat de SyncFeed iedere mutatie voorziet van een oplopend nummer is het mogelijk om alleen informatie op te vragen die recent is gewijzigd en zo een eigen database te synchroniseren. Via de SyncFeed kan informatie opgevraagd worden in XML formaat welke is voorzien van een XML Schema (XSD) .

SyncFeed endpoints

De basis URL van de SyncFeed is https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0/. De SyncFeed heeft de volgende 3 endpoints:

# URL API-data versie Opmerkingen

1

/SyncFeed/2.0/Feed

2.0

Feed. Optionele querystring parameters:

  • ?category=[categorie]
    Met deze parameter kunt u alleen entiteiten van een bepaalde categorie opvragen. Bijv. “?category=persoon”. Zie voor alle opties het Datamodel.
     
  • ?skiptoken=[nummer]
    Met deze parameter kunt u een bepaald aantal mutaties overslaan. Het skiptoken is een oplopend nummer, welke steeds wordt opgehoogd bij iedere doorgevoerde mutatie in de Open Data Portaal API.
     
  • ?content=[internal]/[external]
    Met deze parameter kan worden ingesteld of de XML inhoud van entiteiten inline moet worden meegestuurd of niet. Standaard waarde is [internal]. Voor een correcte werking van oudere Atom 1.0 feed readers kan het vereist zijn om dit op [external] te zetten.

2

/SyncFeed/2.0/Entiteiten/<guid>

2.0

Via deze endpoint is het mogelijk om de inhoud (XML) van een enkele entiteit los op te halen via de entiteit GUID identifier.

3

/SyncFeed/2.0/Resources/<guid>

2.0

Via deze endpoint is het mogelijk om een bestand te downloaden welke toebehoort aan een entiteit via de entiteit GUID identifier (bijv. een Persoon, Fractie, Document of Verslag).

SyncFeed structuur

U kunt entiteiten eenvoudig ophalen via de feed. Een voorbeeld verzoek “/SyncFeed/2.0/Feed” ziet er als volgt uit

<feed xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/2005/Atom">
<title>Gegevensmagazijn SyncFeed</title>
<link rel="self" href="https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0/Feed" />
<link rel="next" href="https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0/Feed?skiptoken=2050" />
<updated>2019-02-11T15:29:46.7299828+01:00</updated>
<author>
<name>Tweede Kamer der Staten-Generaal</name>
<uri>https://opendata.tweedekamer.nl</uri>
<email></email>
</author>
<rights>Het is gebruikers toegestaan de informatie en gegevens van deze internetsite met bronvermelding over te nemen voor eigen gebruik door deze te kopiëren, uit te printen of op te slaan. Het is niet toegestaan de verstrekte informatie en gegevens evenals de ontwerpen en symbolen van de Tweede Kamer der Staten-Generaal te gebruiken voor doeleinden waarvoor het ongepast is, of in gevallen waarin de kans bestaat dat er misverstanden over de oorsprong kunnen ontstaan, dan wel in gevallen waarin men doet voorkomen dat het door de Tweede Kamer der Staten-Generaal is geautoriseerd.
</rights>
<id>https://gegevensmagazijn.tweedekamer.nl//SyncFeed/2.0/Feed</id>
<entry>
<title>3c155434-c804-4329-b346-c784342f5518</title>
<id>https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0/Entiteiten/3c155434-c804-4329-b346-c784342f5518</id>
<author>
<name>Tweede Kamer der Staten-Generaal</name>
</author>
<updated>2019-02-07T14:37:57Z</updated>
<category term="agendapunt" />
<link rel="next" href="https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0/Feed?skiptoken=1801" />
<content type="application/xml">
<agendapunt xmlns:tk="http://www.tweedekamer.nl/xsd/tkData/v1-0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.tweedekamer.nl/xsd/tkData/v1-0" id="3c155434-c804-4329-b346-c784342f5518" tk:bijgewerkt="2008-08-26T16:45:04.483" tk:verwijderd="false">
</content>
</entry>
</feed>

Hieronder staat per element de betekenis uitgelegd.

Element Opmerkingen

<feed>

Feed open element.

- <title>

Titel van de feed. Dit is een statisch veld.

- <link rel=”self”>

Hyperlink van huidig verzoek.

- <link rel=”next”>

(Optioneel)
Wanneer de feed meer dan het maximaal aantal items (250) teruggeeft, dan bevat dit element de link om de volgende pagina met resultaten binnen te halen.

- <link rel=”resume”>

(Optioneel)
Wanneer de feed geen items bevat (bijv. vanwege het gebruik van een ?skiptoken querystring parameter en er nog geen nieuwe mutaties beschikbaar zijn) dan bevat dit element de huidige URL.

- <updated>

Datum (servertijd) waarop de response is gegenereerd.

- <author></author>

Contactgegevens van de auteur van deze feed (Tweede Kamer der Staten-Generaal). Dit is een statisch veld.

- <rights>

Disclaimer van de API. Dit is een statisch veld.

- <id>

Identifier (url) van het huidige verzoek. De waarde van dit veld is gelijk aan de waarde van het <link rel=”self”> element hierboven).

- <entry>

Entry open element. Dit element bevat informatie over een losse entiteit.

-- <title>

Titel van de entiteit. In de SyncFeed is dit de GUID identifier van de entiteit.

-- <id>

De directe hyperlink naar deze entiteit. Deze maakt gebruik van de “/Entiteiten” endpoint i.p.v. de “/Feed”.

-- <author></author>

Naam van de auteur van deze entiteit. Dit is een statisch veld.

-- <updated>

Datum wanneer deze entiteit (mutatie) zichtbaar is geworden in de SyncFeed API.

-- <category>

Het type entiteit. Deze waarde kan gebruikt worden voor de “?category” querystring parameter.

-- <link rel=”alternate”>

(Optioneel)
Wanneer de feed is opgevraagd m.b.v. de “?content=external” querystring parameter dan bevat dit element de link naar de entiteit inhoud (XML).

-- <link rel=”next”>

De hyperlink naar de feed met als startpunt de hiernavolgende <entry>. Dit veld kan door afnemers gebruikt worden om per binnengehaalde en verwerkte entiteit bij te houden via welke URL de volgende entries binnengehaald kunnen worden.

 -- <content type=”application/xml”>

(Optioneel)
Wanneer de feed is opgevraagd m.b.v. de “?content=internal” querystring parameter (standaard) dan bevat dit element de XML representatie van deze entiteit.

- </entry>

Entry sluit element.

</feed>

Feed sluit element.

Datamodel SyncFeed

De data in de SyncFeed komt overeen met het Informatiemodel. De SyncFeed is gebaseerd op XML opslag, OData slaat de data relationeel op. In plaats van expands zoals bij OData staan er links naar andere entiteiten.

SyncFeed category 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.

persoonAdres

persoonContactinformatie

persoonGeschenk

persoonLoopbaan

persoonNevenfunctie

persoonNevenfunctieInkomsten

persoonOnderwijs

persoonReis

reservering

stemming

vergadering

verslag

Inclusief download link naar volledige XML.

zaak

zaakActor

zaal

Structuur XML inhoud per entiteit (XSD's)

De SyncFeed geeft de entiteiten weer in XML formaat. Hieronder vindt u een voorbeeld van een "activiteit" entiteit.

<activiteit xmlns:tk="http://www.tweedekamer.nl/xsd/tkData/v1-0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.tweedekamer.nl/xsd/tkData/v1-0" id="b6429a19-9a65-455c-89b5-70caf9dfaba4" tk:bijgewerkt="2008-09-10T16:36:46.037" tk:verwijderd="false">
<soort>Hoorzitting / rondetafelgesprek</soort>
<nummer>2008A00062</nummer>
<onderwerp>ICT in de zorg</onderwerp>
<datumSoort>Dag</datumSoort>
<datum>2008-09-10T14:00:00</datum>
<aanvangstijd>2008-09-10T14:00:00</aanvangstijd>
<eindtijd>2008-09-10T16:00:00</eindtijd>
<locatie xsi:nil="true" />
<besloten>false</besloten>
<status>Uitgevoerd</status>
<vergaderjaar>2007-2008</vergaderjaar>
<kamer>Tweede Kamer</kamer>
<noot xsi:nil="true" />
<vrsNummer>15296860</vrsNummer>
<sidVoortouw>S-1-365867521-2120874753-2028197338-1299813002-3981344915-3888665279</sidVoortouw>
<voortouwnaam>vaste commissie voor Volksgezondheid, Welzijn en Sport</voortouwnaam>
<voortouwafkorting>VWS</voortouwafkorting>
<voortouwkortenaam>VWS</voortouwkortenaam>
<voortouwcommissie ref="663a410e-bb4b-4507-a6c8-6009e85ae039" />
</activiteit>

Alle entiteiten in de SyncFeed bevatten de volgende verplichte attributen op root niveau:

Attribuut Opmerkingen

id

GUID van de entiteit.

bijgewerkt

Datum wanneer het bronsysteem deze entiteit heeft aangemaakt/aangepast.

verwijderd

Er is bewust voor gekozen alle verwijderde entiteiten als “placeholder” zichtbaar te houden in de API zodat afnemers kunnen detecteren wanneer iets verwijderd is. 

De inhoud van iedere entiteit met de mogelijke velden/volgorde, datatypes, relaties etc. zijn vastgelegd in de XML schema definition standaard (XSD). De XSD is beschikbaar via de volgende URL:
https://gegevensmagazijn.tweedekamer.nl/Contract/tkdata-v1-0.xsd

Werking SyncFeed (full-load en synchronisatie)

De SyncFeed is speciaal beschikbaar gesteld voor afnemers om zo eenvoudig mogelijk (een subset van) alle data van het Open Data Portaal te synchroniseren met een eigen database

Full-load
In eerste instantie zult u alle gegevens uit de SyncFeed uit moeten lezen en deze vervolgens (eventueel geconverteerd) opslaan in uw eigen database. Dit doet u als volgt. 

Maak een query naar de /Feed endpoint. 

  1. Voor iedere <entry> die u tegenkomt: sla de Guid en de XML inhoud van deze entry, samen met de <link rel=”next”> waarde op in de database. Dit "<link>" element bevat de link om de volgende request te maken. Zo weet u precies waar u gebleven bent.
    1. Indien de <entry> een <link rel="enclosure"> element bevat dan betekent dit dat er een achterliggend bestand beschikbaar is. Dit bestand kunt u downloaden door deze enclosure link te volgen.
  2. Nadat u alle beschikbare <entry> elementen van het verzoek heeft verwerkt, maakt u een volgende request op basis van de <link rel=”next”> waarde van het laatst verwerkte <entry>.
  3. Herhaal stap 1 en 2 totdat u geen <entry> resultaten meer terugkrijgt. Dit betekent dat u alle entiteiten heeft binnengehaald. Indicatie: op het moment van schrijven bevat de SyncFeed ongeveer 3,5 miljoen entiteiten.

Synchronisatie
Om uw eigen database te synchroniseren met de SyncFeed API kunt u periodiek de API bevragen met behulp van de <link rel=”next”> waarde van het door u laatst verwerkte <entry> hierboven. Let hierbij op dat een entiteit die u eerder heeft opgehaald opnieuw in de feed kan voorkomen (in het geval van een update). Dit controleert u op basis van de meegestuurde GUID identifier.

Query voorbeelden

Hieronder vindt u enkele voorbeeld queries.

Omschrijving Query
Haal alle inhoud op /Feed

Haal alle activiteiten op

/Feed?category=activiteit
Geef alleen een link naar de inhoud van de entiteit weer /Feed?category=activiteit&content=external
Haal de inhoud van een specifieke entiteit op /Entiteiten/<guid>
Haal het bestand (resource) van een specifieke entiteit op /Resources/<guid>

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