Feed API
From NUBWiki
| Warning:This version of the API is deprecated and no longer supported, for a newer API see Feed_API_4.0! |
Contents |
Inleiding
De publishing server van het Nederlands Uitburo is opgebouwd volgens het REST architectuur principe. In dit pincipe is vastgelegd hoe de opmaak van de URI's is. Door dit principe te hanteren worden URI's technisch 'leesbaar' en is het dus gemakkelijke te interpreteren.
Bestanden
We hebben een set XML Schema en voorbeeldbestanden beschikbaar die je kunnen helpen bij het interfacen met de Publishing Server.
Algemeen
Pagineren
Met de parameters rows en start is het mogelijk om door de resultaten te bladeren. In onderstaande tabel zijn de parameters weergegeven die je kunt gebruiken bij het pagineren van de feeds:
| rows | optioneel | het maximaal aantal te retourneren hits |
| start | optioneel | de startpositie waarvan het volgende x aantal resultaten wordt getoond |
Voorbeeld:
http://feeds.uitburo.nl/1.0/activiteiten?key=ed79e27aedbe4a5824f70aaf5b2e9836&rows=5&start=200
Sorteren
Op dit moment ondersteund de API maar één sorteer parameter. Gegevens kunnen oplopend (asc) of aflopend (desc) worden gesorteerd. Onderstaand een voorbeeld van het gebruik van de sort parameter.
Parameters:
| sort | optioneel | het sorteren van lijsten op specifieke kenmerken |
Voorbeeld:
http://feeds.uitburo.nl/1.0/locaties/1998-L-001-0000300/activiteiten?key=ed79e27aedbe4a5824f70aaf5b2e9836&sort=activiteittype+asc
Het format voor het opgeven van een sort parameter is als volgt: sort={sorteerveld}+{richting} oftwel: sort=activiteittype+asc.
Series
lijst met series
| Beschrijving: | Aanroep voor het weergeven van series, eventueel gefilterd op een aantal optionele parameters |
| URL: | http://feeds.uitburo.nl/1.0/series |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
| datum-wijziging-vanaf | xs:dateTime | optioneel | Alle activiteiten die gewijzigd zijn vanaf datum-wijziging-vanaf. Samen met de datum-wijziging-tot kan een periode worden geselecteerd. |
| datum-wijziging-tot | xs:dateTime | optioneel | Alle activiteiten die gewijzigd zijn tot datum-wijziging-tot. Samen met de datum-wijziging-vanaf kan een periode worden geselecteerd. |
| text | xs:string | optioneel | Zoeken in de text velden van een serie (inhoud, inhoud-kort, opmerkingen etc) |
| serietype | xs:int | optioneel | Zoeken op serietype (zie waardelijst) |
| sort | xs:string | optioneel | Sorteren op datum-wijziging, serietype |
Voorbeeld:
http://feeds.uitburo.nl/1.0/series?key=ed79e27aedbe4a5824f70aaf5b2e9836&datum-wijziging-vanaf=2009-07-21T00:00:00.0Z
specifieke serie
| Beschrijving: | Opvragen van een specifieke serie |
| URL: | http://feeds.uitburo.nl/1.0/series/{cidn} |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/series/2009-S-01-0928?key=ed79e27aedbe4a5824f70aaf5b2e9836
Activiteiten
lijst met activiteiten
| Beschrijving: | Geeft een lijst activiteiten, default worden alle activiteiten, met 10 resultaten per resultaat pagina, gesorteerd op einddatum |
| URL: | http://feeds.uitburo.nl/1.0/activiteiten |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
| datum-vanaf | xs:dateTime | optioneel | Alle activiteiten met begindatum groter of gelijk aan datum-vanaf. Samen met de einddatum kan een periode worden geselecteerd. |
| datum-tot | xs:dateTime | optioneel | Alle activiteiten met einddatum kleiner of gelijk aan datum-vanaf. Samen met de begindatum kan een periode worden geselecteerd. |
| datum-wijziging-vanaf | xs:dateTime | optioneel | Alle activiteiten die gewijzigd zijn vanaf datum-wijziging-vanaf. Samen met de datum-wijziging-tot kan een periode worden geselecteerd. |
| datum-wijziging-tot | xs:dateTime | optioneel | Alle activiteiten die gewijzigd zijn tot datum-wijziging-tot. Samen met de datum-wijziging-vanaf kan een periode worden geselecteerd. |
| activiteittype | xs:int | optioneel | Selectiecriterium voor type activiteit (zie waardelijst) |
| gratis | xs:int | optioneel | Selectiecriterium welke aangeeft of een activiteit gratis is (zie waardelijst) |
| regio | xs:int | optioneel | Selectiecriterium voor regio. Er kunnen meerdere regio's worden opgegeven door middel van een spatie (+) (zie waardelijst) |
| zaal | xs:string | optioneel | Zoeken van locaties op basis van zalen. |
| sort | xs:string | optioneel | Sorteren op datum-wijziging, datum-start, datum-tot, activiteittype, gratis, regio en zaal |
Voorbeeld:
http://feeds.uitburo.nl/1.0/activiteiten?key=ed79e27aedbe4a5824f70aaf5b2e9836&datum-vanaf=2009-08-01T00:00:00.0Z&datum-tot=2009-08-08T00:00:00.0Z&gratis=1
specifieke activiteit
| Beschrijving: | Geeft een specifieke activiteit voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/activiteiten/{cidn} |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/activiteiten/2009-A-047-0152107?key=ed79e27aedbe4a5824f70aaf5b2e9836
Locaties
lijst met locaties
| Beschrijving: | Geeft een lijst locaties, default worden alle locaties, met 10 resultaten per resultaat pagina, gesorteerd op einddatum |
| URL: | http://feeds.uitburo.nl/1.0/locaties |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
| datum-wijziging-vanaf | xs:dateTime | optioneel | Alle locaties die gewijzigd zijn vanaf datum-wijziging-vanaf. Samen met de datum-wijziging-tot kan een periode worden geselecteerd |
| datum-wijziging-tot | xs:dateTime | optioneel | Alle locaties die gewijzigd zijn tot datum-wijziging-tot. Samen met de datum-wijziging-vanaf kan een periode worden geselecteerd |
| text | xs:string | optioneel | Fulltext zoeken op beschrijvingen van locatie |
| locatienaam | xs:string | optioneel | Retourneert locaties die voldoen aan locatienaam. |
| plaats | xs:string | optioneel | Zoeken op plaatsnaam. |
| locatietype | xs:int | optioneel | Welk type locatie? |
| mediatype | xs:string | optioneel | Selecteren van gegevens op basis van mediatype afbeelding, audio of video? |
| sort | xs:string | optioneel | Sorteren op datum-wijziging, locatietype, locatienaam, mediatype |
Voorbeeld:
http://feeds.uitburo.nl/1.0/locaties?key=ed79e27aedbe4a5824f70aaf5b2e9836&wijzigingdatum-vanaf=2009-07-21T00:00:00.0Z&plaats=amsterdam
specifieke locatie
| Beschrijving: | Geeft een specifieke locatie voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/locaties/{cidn} |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/locaties/1998-L-001-0000254?key=ed79e27aedbe4a5824f70aaf5b2e9836
Producties
lijst met producties
| Beschrijving: | Geeft een lijst producties, default worden alle locaties, met 10 resultaten per resultaat pagina, gesorteerd op einddatum |
| URL: | http://feeds.uitburo.nl/1.0/producties |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens |
| datum-wijziging-vanaf | xs:dateTime | optioneel | Alle producties die gewijzigd zijn vanaf datum-wijziging-vanaf. Samen met de datum-wijziging-tot kan een periode worden geselecteerd |
| datum-wijziging-tot | xs:dateTime | optioneel | Alle producties die gewijzigd zijn tot datum-wijziging-tot. Samen met de datum-wijziging-vanaf kan een periode worden geselecteerd |
| text | xs:string | optioneel | Fulltext zoeken in alle tekst velden van een productie |
| productienaam | xs:string | optioneel | Zoeken op de naam van een productie |
| taal | xs:int | optioneel | Zoeken op producties met een bepaalde taal (zie waardelijst) |
| mediatype | xs:string | optioneel | Selecteren van gegevens op basis van mediatype afbeelding, audio of video |
| hoofdgenre | xs:string | optioneel | Zoeken op het hoofdgenre van een productie (zie waardelijst) |
| subgenre | xs:string | optioneel | Zoeken op het subgenre van een productie (zie waardelijst) |
Voorbeeld:
http://feeds.uitburo.nl/1.0/producties?key=ed79e27aedbe4a5824f70aaf5b2e9836&datum-wijziging-vanaf=2009-01-01T00:00:00.0Z&hoofdgenre=jeugd
specifieke productie
| Beschrijving: | Geeft een specifieke productie voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/producties/{cidn} |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/producties/2009-P-068-0006041?key=ed79e27aedbe4a5824f70aaf5b2e9836
Overige
activiteiten op specifieke locatie
| Beschrijving: | Geeft een specifieke locatie voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/locaties/{cidn}/activiteiten |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens |
Voorbeeld:
http://feeds.uitburo.nl/1.0/locaties/1998-L-001-0000258/activiteiten?key=ed79e27aedbe4a5824f70aaf5b2e9836
activiteiten voor specifieke productie
| Beschrijving: | Geeft alle activiteiten voor een specifieke productie voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/producties/{cidn}/activiteiten |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/producties/2009-P-068-0006061/activiteiten?key=ed79e27aedbe4a5824f70aaf5b2e9836
locaties voor specifieke productie
| Beschrijving: | Geeft alle locaties voor een specifieke productie voor het opgegeven {cidn} |
| URL: | http://feeds.uitburo.nl/1.0/producties/{cidn}/locaties |
| Formaat: | application/xml |
| Method(s): | GET |
Parameters:
| key | xs:string | verplicht | Authenticatie sleutel voor het ophalen van gegevens. |
Voorbeeld:
http://feeds.uitburo.nl/1.0/producties/2008-P-001-0312793/locaties?key=ed79e27aedbe4a5824f70aaf5b2e9836
Waardelijsten
serietype
| waarde | omschrijving |
| 1 | festival (alle uitgaven) |
| 2 | serie (alle uitgaven) |
| 3 | serie (uitsluitend portal) |
| 4 | actie serie (abonnementen) |
| 5 | uitgids aub vaste serie |
| 6 | uitgids aub keuzeserie |
activiteittype
| waarde | omschrijving |
| 0 | tentoonstelling |
| 1 | voorstelling |
gratis
| waarde | omschrijving |
| 0 | onbekend of niet-gratis |
| 1 | gratis |
regio
| waarde | omschrijving |
| 0 | alles (heel Nederland) |
| 1 | Amsterdam |
| 2 | Rotterdam |
| 3 | Den Haag (regio) |
| 4 | Groningen (provincie) |
| 5 | Enshede & Twente |
| 6 | Leiden |
| 7 | Maastricht |
| 8 | Limburg |
| 9 | Utrecht (provincie) |
| 10 | Nijmegen |
| 11 | Noord-Holland |
| 12 | Apeldoorn |
| 13 | Friesland |
| 14 | Arnhem |
| 15 | Drenthe |
| 16 | Flevoland |
| 17 | Gelderland |
| 18 | Noord-Brabant |
| 19 | Overijssel |
| 20 | Zeeland |
| 21 | Zuid-Holland |
Taal
| waarde | omschrijving |
| 0 | Nederlands |
| 1 | Engels |
| 2 | Duits |
| 3 | Frans |
| 4 | Spaans |
| 5 | Fries |
Genre
Http Status codes
Bij het aanroepen van de verschillende resources kunnen onderstaande HTTP status code met bijbehorende fouten optreden.
HTTP Status Code - 200 OK
Het request is goed gegaan, er wordt een response geretouneerd.
HTTP Status Code - 403 Forbidden
Er wordt een request uitgevoerd zonder een key parameter op te geven.
HTTP Status Code - 404 Not Found
Er wordt een request uitgevoerd naar een URI die niet aanwezig is.
HTTP Status Code - 500 Internal Server Error
Er is een fout opgetreden op de server, neem contact op met secretariaat@nederlandsuitburo.nl wanneer de fout blijft optreden.
Externe links
http://en.wikipedia.org/wiki/Representational_State_Transfer
