API
Atom feeds
Op Open Beelden gepubliceerde media items worden aangeboden via een aantal Atom feeds . Deze Atom feeds kunnen gebruikt worden om de content van Open Beelden op basis van een aantal zoekcriteria (recente toevoegingen aan het platform, recente toevoegingen van een specifieke gebruiker, aan een media item gerelateerd materiaal, recente resultaten voor een bepaalde zoekterm, etc.) via externe applicaties (zoals bijvoorbeeld Miro) of websites weer te geven.
OAI-PMH
Alle via Open Beelden gepubliceerde media items en de bijbehorende beschrijvingen (metadata) zijn toegankelijk via een Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) API. Hierdoor worden derden in staat gesteld om de binnen Open Beelden opgeslagen metadata en mediabestanden op een gestructureerde manier op te vragen. OAI-PMH is een krachtige tool om data en metadata te delen tussen instellingen en platformen. Met OAI-PMH kan bijvoorbeeld alle data van de server opgehaald worden, maar er kunnen ook specifieke updates uit het opgevraagd worden.
Klik hier voor de specificatie van OAI-PMH. Daar worden alle mogelijkheden van dit type API uitgelegd. Open Beelden implementeert dit protocol met twee specifieke metadataformaten. De specifieke details van de Open Beelden OAI worden hieronder besproken voor ontwikkelaars/curatoren die al bekend zijn met dit type API. Kijk ook hier voor een goede introductie in OAI-PMH.
Beschikbare elementen
De Open Beelden OAI implementatie maakt twee verschillende dataformaten beschikbaar. Waaronder een minimale vereiste dataset van OAI-PMH genaamd 'oai_dc' (OAI Dublin Core). Dublin Core is een set elementen waarmee fysieke objecten beschreven kunnen worden. oai_dc bevat 15 elementen gespecificeerd door Dublin Core.
De tweede, uitgebreidere, set metadata is een verfijning van deze kernelementen. 'oai_oi' (OAI Open Images) is een Open Beelden specifieke implementatie bestaande uit een mix van DC Terms en een XML interpretatie van ccREL.
Voor optimaal gebruik van de API raden wij het gebruik van de oai_oi variant aan. Deze bevat meer gedetailleerde informatie over de bestanden op Open Beelden. De simpelere oai_dc maakt deze bestanden sneller uitwisselbaar en combineerbaar met andere OAI implementaties die rusten op Dublin Core.
OAI-PMH is XML gebaseerd. Alle requests naar deze API kunnen dan ook gevalideerd worden door bijbehorende XSDs. Een XML Schema Document of XSD beschrijft hoe een XML bestand eruit ziet, welke elementen wel en niet zijn toegestaan, wat voor type ze zijn en hoe vaak ze voorkomen. De belangrijkste XSDs van Open Beelden op een rijtje:
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd
Deze XSD beschrijft hoe een resultaat van een aanvraag eruit zal zien. Hiermee kan je controleren of de aanvraag goed beantwoord is.
http://www.openbeelden.nl/feeds/oai/oai_oi.xsd
Wanneer je gebruik maakt van het Open Beelden specifieke metadataformaat dan kan je elk individueel record met deze XSD controleren op haar validiteit.
http://www.openarchives.org/OAI/2.0/oai_dc.xsd
Wanneer je gebruik maakt van het Dublin Core minimale metadataformaat dan kan je elk individueel record met deze XSD controleren op haar validiteit.
Zie ook http://www.openbeelden.nl/feeds/oai/?verb=ListMetadataFormats voor de OAI implementatie van deze informatie.
Een Dublin Core elementinterpretatie kan per instelling verschillen, daarom is hieronder een beschrijving geplaatst van alle elementen per type element:
oai_dc
|
element |
uitleg |
opmerkingen |
| dc:title | Titel van het item. | - |
| dc:creator | De maker/producent van het item (in de auteursrechtelijke zin). | In het geval van een persoonsnaam is het formaat “achternaam, voornaam”, met daar optioneel tussen haakjes nog een rol achter. Bijvoorbeeld: “Janssen, Jan (producent)” |
| dc:subject | Trefwoorden die het item beschrijven, meestal afkomstig uit een vaste woordenlijst (thesaurus). | Namen van personen die in het media-item voorkomen vallen hier ook onder. Deze volgen hetzelfde formaat als hierboven. Er kunnen meerdere trefwoorden aanwezig zijn. |
| dc:description | Een tekstuele beschrijving van het item. | - |
| dc:publisher | De uploader van het item naar Open Beelden. | Voor dit veld zijn altijd twee waarden aanwezig, de uitgeschreven gebruikersnaam plus een URL naar het profiel van de gebruiker op Open Beelden. |
| dc:contributor | Personen/instanties die aan de totstandkoming van het item hebben bijgedragen (in de auteursrechtelijke zin). | In het geval van persoonsnamen wordt hetzelfde formaat als hierboven gebruikt. Er kunnen meerdere waarden aanwezig zijn. |
| dc:date | De oorspronkelijke publicatiedatum van het item. | Standaard is dit het moment van uploaden naar Open Beelden, gebruikers kunnen dit handmatig aanpassen (indien nodig). |
| dc:type | Het mediatype van het item. | Items op Open Beelden zijn van het type video, audio of stilstaand beeld en worden aangegeven volgens: http://dublincore.org/documents/dcmi-type-vocabulary/ |
| dc:format | De verschillende bestandsformaten waarin het item op Open Beelden beschikbaar is. | Er zijn altijd meerdere bestandsformaten van een item aanwezig. |
| dc:identifier | Het catalogusnummer van het item (indien afkomstig uit een bestaande collectie). | - |
| dc:source | Een verwijzing naar de oorspronkelijke drager/bron van het items (indien aanwezig). | - |
| dc:language | De taal van het items zelf (dus niet de beschrijving ervan). | Deze waarde wordt aangegeven volgens de ISO 639-1 standaard. |
| dc:relation | Een vermelding van de bronnen waaruit het item tot stand is gekomen. | - |
| dc:coverage | De geografische locatie(s) van het item. | Doorgaans zijn dit uitgeschreven plaatsnamen. Er kunnen meerdere waarden aanwezig zijn. |
| dc:rights | De licentievoorwaarden waaronder het item beschikbaar is. | Alle items op Open Beelden zijn beschikbaar onder een Creative Commons licentie of bevinden zich in het publiek domein. De waarde van dit veld wordt uitgedrukt in de vorm van een URL. Bijvoorbeeld: “http://creativecommons.org/licenses/by-sa/3.0/nl/” |
oai_oi
|
element |
uitleg |
opmerkingen |
| oi:title | Titel van het item. | - |
| oi:alternative | Ondertitel van het item (optioneel). | - |
| oi:creator | De maker/producent van het item (in de auteursrechtelijke zin). | In het geval van een persoonsnaam is het formaat “achternaam, voornaam”, met daar optioneel tussen haakjes nog een rol achter. Bijvoorbeeld: “Janssen, Jan (producent)” |
| oi:subject | Trefwoorden die het item beschrijven, meestal afkomstig uit een vaste woordenlijst (thesaurus). | Namen van personen die in het media-item voorkomen vallen hier ook onder. Deze volgen hetzelfde formaat als hierboven. Er kunnen meerdere trefwoorden aanwezig zijn. |
| oi:description | Een introducerende beschrijving van het item. | - |
| oi:abstract | Een uitgebreide beschrijving van het item. | - |
| oi:publisher | De uploader van het item naar Open Beelden. | Voor dit veld zijn altijd twee waarden aanwezig, de uitgeschreven gebruikersnaam plus een URL naar het profiel van de gebruiker op Open Beelden. |
| oi:contributor | Personen/instanties die aan de totstandkoming van het item hebben bijgedragen (in de auteursrechtelijke zin). | In het geval van persoonsnamen wordt hetzelfde formaat als hierboven gebruikt. Er kunnen meerdere waarden aanwezig zijn. |
| oi:date | De oorspronkelijke publicatiedatum van het item. | Standaard is dit het moment van uploaden naar Open Beelden, gebruikers kunnen dit handmatig aanpassen (indien nodig). |
| oi:type | Het mediatype van het item. | Items op Open Beelden zijn van het type video, audio of stilstaand beeld en worden aangegeven volgens: http://dublincore.org/documents/dcmi-type-vocabulary/ |
| oi:extent | De lengte van het item. | Deze tijdsduur wordt aangegeven volgens volgens: http://en.wikipedia.org/wiki/ISO_8601#Durations |
| oi:medium | De verschillende bestandsformaten waarin het item op Open Beelden beschikbaar is. | Er zijn altijd meerdere bestandsformaten van een item aanwezig. |
| oi:identifier | Het catalogusnummer van het item (indien afkomstig uit een bestaande collectie). | - |
| oi:source | Een verwijzing naar de oorspronkelijke drager/bron van het items (indien aanwezig). | - |
| oi:language | De taal van het items zelf (dus niet de beschrijving ervan). | Deze waarde wordt aangegeven volgens de ISO 639-1 standaard. |
| oi:references | Een vermelding van de bronnen waaruit het item tot stand is gekomen. | - |
| oi:spatial | De geografische locatie(s) van het item. | Doorgaans zijn dit uitgeschreven plaatsnamen. Er kunnen meerdere waarden aanwezig zijn. |
| oi:attributionName | De naam van één of meerdere makers die, in het geval van hergebruik van het item, vermeld dienen te worden. | In het geval van persoonsnamen wordt hetzelfde formaat als hierboven gebruikt. |
| oi:attributionURL | De locatie van het oorspronkelijke item waar, in het geval van hergebruik van het item, naar verwezen dient te worden. | De waarde van dit veld wordt uitgedrukt in de vorm van een URL die verwijst naar het item op Open Beelden. Bijvoorbeeld: “http://www.openbeelden.nl/media/23173” |
| oi:license | De licentievoorwaarden waaronder het item beschikbaar is. | Alle items op Open Beelden zijn beschikbaar onder een Creative Commons licentie of bevinden zich in het publiek domein. De waarde van dit veld wordt uitgedrukt in de vorm van een URL. Bijvoorbeeld: “http://creativecommons.org/licenses/by-sa/3.0/nl/” |
Aanroepvoorbeelden
Resumption tokens
De Open Beelden OAI-PMH API zal niet alle gegevens tegelijkertijd weergeven. De API maakt gebruik van ‘resumption tokens’ om het dataverkeer en wachttijd te beperken. Daardoor zullen bij grote aanvragen maar 100 resultaten per keer getoond worden. Wanneer er meer dan 100 resultaten getoond worden zal het veld ‘resumptionToken’ verschijnen onderaan de resultaten:
<resumptionToken cursor="100" completeListSize="12000">!f!u!oai_dc!100</resumptionToken>
Met behulp van de waarde van dit veld zijn de volgende 100 records op te halen. Elke nieuwe set records heeft zijn eigen resumption token, dit gaat door totdat de inhoud van de het resumption token veld leeg is.
Als je bijvoorbeeld alle media die in 2009 of later zijn bewerkt of geupload opvraagd met:
http://www.openbeelden.nl/feeds/oai/?verb=ListRecords&metadataPrefix=oai_dc&from=2009-01-01
Dan zal je meer dan 100 elementen records kunnen zien. Door de resumption tokens te gebruiken kan je deze resultaten per 100 ophalen:
http://www.openbeelden.nl/feeds/oai/?verb=ListRecords&resumptionToken=!f2009-01-01!u!oai_dc!100
Elke pagina zal zijn eigen resumption token hebben voor de volgende pagina.
Metadataformaten
Zoals eerder beschreven zijn er meerdere metadataformaten beschikbaar. De metadataPrefix heeft voor Open Beelden verschillende mogelijkheden. oai_dc en oai_oi zijn hiervoor beschikbaar.
Identificeren
Voor vele automatische harvesters van een OAI implementatie is het identificeren van een implementatie van belang:
http://www.openbeelden.nl/feeds/oai/?verb=Identify
Ook staat in de identify request enkele andere belangrijke informatie over deze implementatie.
Alle informatie ophalen
Onderstaande aanvraag haalt alle records op uit de database met het metadataformaat oai_dc. Deze aanvraag kan gebruikt worden voor een initiële copy van alle gegevens die Open Beelden heeft. We raden niet aan deze vaak te gebruiken, het is een zware aanvraag op onze database.
http://www.openbeelden.nl/feeds/oai/?verb=ListRecords&metadataPrefix=oai_dc
Periodieke updates
Door onderstaande aanvraag is het mogelijk periodiek de nieuwste bestanden van Open Beelden af te halen. Zo kan er bijvoorbeeld elke dag gekeken worden of er nieuw materiaal op Open Beelden staat zodat deze bekeken kunnen worden. Media waarvan metadata veranderd wordt na haar initiële upload zal de datum van de laatste wijziging hebben. Door de ‘from’ en ‘until’ variabele (in het YYYY-MM-DD formaat) te veranderen kunnen specifieke periodes opgehaald worden. Wanneer één van deze variabelen ontbreekt zal het systeem uitgaan van het eerst of laatst mogelijke record.
http://www.openbeelden.nl/feeds/oai/?verb=ListRecords&metadataPrefix=oai_dc&from=2010-11-01&until=2010-12-01
Specifieke collectie ophalen
Binnen OAI-PHM bestaan de mogelijkheid om specifieke sets aan objecten te definiëren. Gebruik de volgende URL om een lijst met de collectie aan te vragen:
http://www.openbeelden.nl/feeds/oai/?verb=ListSets
Gebruik de informatie in het element ‘setspec’ om dieper te graven in een specifieke collectie. Alle bovenstaande voorbeelden zijn ook te gebruiken met ‘set’ variabelen. Zo kan je bijvoorbeeld alle records uit de collectie "beeldengeluid" van november 2010 ophalen door de volgende URL te gebruiken:
http://www.openbeelden.nl/feeds/oai/?verb=ListRecords&metadataPrefix=oai_dc&from=2010-11-01&until=2010-12-01&set=beeldengeluid
Specifiek record ophalen
Wanneer je informatie wilt ophalen van één specifieke record dan kan je dat doen via de volgende URL:
http://www.openbeelden.nl/feeds/oai/?verb=GetRecord&identifier=oai:openimages.eu:47540&metadataPrefix=oai_dc
Ieder record heeft een eigen identifier die uniek is voor Open Beelden. Je kunt deze identifier ophalen via bijvoorbeeld het OAI-PMH met ListRecords (zie vorige alinea), of deze kopiëren uit de URL van een item op Open Beelden (dit is de reeks cijfers die in de URL volgt na /media/).
Software
Enkele goede tools zijn beschikbaar om gebruik te maken van OAI-PMH API calls. Zo is er bijvoorbeeld een goede Python implementatie die OAI requests makkelijk maakt. Zie hiervoor:
http://www.infrae.com/download/OAI/pyoai
Deze tool wordt o.a. door Wikimedia gebruikt om Open Beelden maandelijks te harvesten, waardoor materiaal met de juiste licentie automatisch wordt geupload naar Wikimedia Commons, bijvoorbeeld voor hergebruik binnen Wikipedia. Zie :
https://fisheye.toolserver.org/browse/multichill/bot/openbeelden/openbeelden_uploader.py?r=HEAD
