Back to top

Een groot deel van de via Oorlogsbronnen gepubliceerde beschrijvingen (metadata)  is toegankelijk via een Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) API. Hierdoor worden derden in staat gesteld om de binnen Oorlogsbronnen opgeslagen metadata op een gestructureerde manier op te vragen. OAI-PMH is een krachtige tool om data en metadata te delen tussen instellingen en platformen. Hiermee kan bijvoorbeeld alle beschikbare metadata en specifieke updatesvan de server opgehaald worden. 

Klik hier voor de specificatie van OAI-PMH. Daar worden alle mogelijkheden van dit type API uitgelegd. Oorlogsbronnen implementeert dit protocol met twee specifieke metadataformaten. De specifieke details van de Oorlogsbronnen OAI worden hieronder besproken voor ontwikkelaars/curatoren die al bekend zijn met dit type API. Beginners kunnen hier kijken voor een goede introductie in OAI-PMH.

Beschikbare elementen

De Oorlogsbronnen 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. 'Ese' (Europeana Semantic Elements) is een implementatie bestaande uit een mix van DC Terms en enkele elementen van Europeana.

Voor optimaal gebruik van de API raden wij het gebruik van de ese variant aan. Deze bevat meer gedetailleerde informatie over de objecten op Oorlogsbronnen. De simpelere oai_dc maakt deze bestanden sneller uitwisselbaar en combineerbaar met andere OAI implementaties die gebaseerd zijn 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 Oorlogsbronnen op een rijtje

Zie ook http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListMetadataFormats voor de OAI implementatie van deze informatie.

Een Dublin Core elementinterpretatie kan per instelling verschillen. Zie hier de juiste elementinterpretatie van Europeana Semantic Elements.

Aanroepvoorbeelden

Resumption tokens

De Oorlogsbronnen 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 50 resultaten per keer getoond worden. Wanneer er meer dan 50 resultaten getoond worden zal het veld ‘resumptionToken’ verschijnen onderaan de resultaten:

Met behulp van de waarde van dit veld zijn de volgende 50 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 beschrijvingen in de set DIMCON opvraagt met: 
http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListRecords&metadataPrefix=ese&set=DIMCON

Dan zie je meer dan 50 records. Door de resumption tokens te gebruiken kun je deze resultaten per 50 ophalen:

http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListRecords&resumptionToken={"set":"DIMCON","from":"0001-01-01T00:00:00Z","until":"9999-12-31T23:59:59Z","startIndex":50,"metadataPrefix":"ese"}

Elke pagina heeft zijn eigen resumption token voor de volgende pagina.

Metadataformaten

Zoals eerder beschreven zijn er meerdere metadataformaten beschikbaar. De metadataPrefix heeft voor Oorlogsbronnen verschillende mogelijkheden. oai_dc en ese zijn hiervoor beschikbaar.

Identificeren

Voor vele automatische harvesters van een OAI implementatie is het identificeren van een implementatie van belang:

http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?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 ese. Deze aanvraag kan gebruikt worden voor een initiële copy van alle gegevens uit Oorlogsbronnen. We raden niet aan deze vaak te gebruiken, het is een zware aanvraag op onze database.

http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListSets

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. Media waarvan metadata veranderd wordt na haar initiële upload heeft de datum van de laatste wijziging. 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://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListRecords&metadataPrefix=ese&from=2013-01-01&until=2013-08-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://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?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 "DIMCON" van de eerste 7 maanden van 2013 ophalen door de volgende URL te gebruiken:

http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=ListRecords&metadataPrefix=ese&from=2013-01-01&until=2013-08-01&set=DIMCON

Specifiek record ophalen

Wanneer je informatie wilt ophalen van één specifieke record dan kan je dat doen via de volgende URL:

http://oaicat.oorlogsbronnen.knaw.nl/OAIHandler?verb=GetRecord&metadataPrefix=ese&identifier=niod:2824881

Ieder record heeft een eigen identifier die uniek is voor Oorlogsbronnen. Je kunt deze identifier ophalen via bijvoorbeeld het OAI-PMH met ListRecords (zie vorige alinea).

Overzicht collecties

  • ARCHIEVEN    Archiefbeschrijvingen van het NIOD
  • ARCHIEVEN-INDIEINOORLOG  Selectie archiefbeschrijvingen uit ARCHIEVEN
  • ARCHIEVENWO2   Beschrijvingen uit de aggregator Wegwijzer Archieven WO2
  • BBHCO     Beeldbeschrijvingen van het Historisch Centrum Overijssel
  • BBWO2    Beeldbeschrijvingen uit de Beeldbank WO2
  • DANS     Beschrijvingen uit de aggregator van onderzoeksdata DANS
  • DIMCON    Beschrijvingen uit de museum aggregator DiMCoN
  • GETUIGENVERHALEN   Beschrijvingen van het interviewproject Getuigen Verhalen
  • GVNEVDO01    Oorlogsdagboeken uit Geheugen van Nederland
  • GVNEVDO02    Propagandadrukwerk WO2 uit Geheugen van Nederland
  • GVNEVDO03    Verzetsliteratuur uit Geheugen van Nederland
  • GVNMUSE01    Kamptekeningen Nederlands-Indië uit Geheugen van Nederland
  • GVNNIOD02    Illegale pamfletten en brochures uit Geheugen van Nederland
  • IPNV     Interviewproject Nederlandse Veteranen
  • KITLV     Beeldbank Koninklijk Instituut voor Taal-, Land- en Volkenkunde
  • MFORCE-MEDIA   Beschrijvingen uit WOII in muziek
  • OCLC     Bibliotheekcatalogus NIOD
  • OIB     Beschrijvingen uit Oorlog in Blik
  • OORLOGSGRAVEN Beschrijvingen uit het Slachtofferregister van de Oorlogsgravenstichting
  • OORLOGSMONUMENTEN  Beschrijvingen van Oorlogsmonumenten
  • RAL     Beschrijvingen uit beeldbank van Regionaal Archief Leiden