OAI-PMH

Überblick

Der /oai Endpunkt stellt einen OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting) Server zur Verfügung, der einen Großteil der Digitalisate aus dem Kulturpool bereitstellt.

OAI-PMH ist ein Standard-Protokoll für das Harvesting von Metadaten aus digitalen Archiven und Repositorien, das eine standardisierte Schnittstelle für die Übertragung von Metadaten zwischen verschiedenen Systemen bietet.

Basis-URL

https://api.kulturpool.at/oai

Technischer Hinweis

Der OAI-PMH-Endpunkt wird über die Reverse-Proxy-Konfiguration eingebunden und ist nicht Teil der FastAPI-Anwendung. Er teilt sich lediglich die Domain mit den übrigen APIs.

OAI-PMH Verben

Das OAI-PMH Protokoll unterstützt sechs Standard-Verben (Befehle):

Identify

Gibt grundlegende Informationen über das Repository zurück.

Parameter:

verb (string): Identify (Pflicht)

Beispiel:

GET /oai?verb=Identify

ListMetadataFormats

Listet alle verfügbaren Metadatenformate auf.

Parameter:

verb (string): ListMetadataFormats (Pflicht)
identifier (string): Spezifischer Datensatz (optional)

Beispiel:

GET /oai?verb=ListMetadataFormats

ListSets

Listet alle verfügbaren Sets (Sammlungen) auf.

Parameter:

verb (string): ListSets (Pflicht)
resumptionToken (string): Token für paginierte Ergebnisse (optional)

Beispiel:

GET /oai?verb=ListSets

ListIdentifiers

Listet die Identifikatoren aller verfügbaren Datensätze auf.

Parameter:

verb (string): ListIdentifiers (Pflicht)
metadataPrefix (string): Format der Metadaten (Pflicht)
from (string): Datum ab wann (optional, Format: YYYY-MM-DD)
until (string): Datum bis wann (optional, Format: YYYY-MM-DD)
set (string): Spezifisches Set/Sammlung (optional)
resumptionToken (string): Token für paginierte Ergebnisse (optional)

Beispiel:

GET /oai?verb=ListIdentifiers&metadataPrefix=edm&set=kulturpool-europeana:wien-bibliothek

ListRecords

Ruft die Metadaten aller verfügbaren Datensätze ab.

Parameter:

verb (string): ListRecords (Pflicht)
metadataPrefix (string): Format der Metadaten (Pflicht)
from (string): Datum ab wann (optional, Format: YYYY-MM-DD)
until (string): Datum bis wann (optional, Format: YYYY-MM-DD)
set (string): Spezifisches Set/Sammlung (optional)
resumptionToken (string): Token für paginierte Ergebnisse (optional)

Beispiel:

GET /oai?verb=ListRecords&metadataPrefix=edm&set=kulturpool-europeana:wien-bibliothek

GetRecord

Ruft einen einzelnen Datensatz ab.

Parameter:

verb (string): GetRecord (Pflicht)
identifier (string): Eindeutige Kennung des gewünschten Datensatzes (Pflicht)
metadataPrefix (string): Format der Metadaten (Pflicht)

Beispiel:

GET /oai?verb=GetRecord&metadataPrefix=edm&identifier=https://id.kulturpool.at/b1eaac0f-69a1-4174-8ac6-90a61615d0ae

Verfügbare Metadatenformate

EDM (Europeana Data Model)

metadataPrefix: edm
Schema: Europeana Data Model
Namespace: http://www.europeana.eu/schemas/edm/

Rufen Sie verb=ListMetadataFormats auf, um die zum jeweiligen Zeitpunkt tatsächlich unterstützten Formate zu ermitteln.

Beispielanfragen

Repository-Informationen abrufen

curl "https://api.kulturpool.at/oai?verb=Identify"

Alle verfügbaren Sets anzeigen

curl "https://api.kulturpool.at/oai?verb=ListSets"

Identifikatoren aus der Wienbibliothek

curl "https://api.kulturpool.at/oai?verb=ListIdentifiers&metadataPrefix=edm&set=kulturpool-europeana:wien-bibliothek"

Vollständige Datensätze aus der Wienbibliothek

curl "https://api.kulturpool.at/oai?verb=ListRecords&metadataPrefix=edm&set=kulturpool-europeana:wien-bibliothek"

Spezifischen Datensatz abrufen

curl "https://api.kulturpool.at/oai?verb=GetRecord&metadataPrefix=edm&identifier=https://id.kulturpool.at/b1eaac0f-69a1-4174-8ac6-90a61615d0ae"

Datensätze aus einem bestimmten Zeitraum

curl "https://api.kulturpool.at/oai?verb=ListRecords&metadataPrefix=edm&from=2024-01-01&until=2024-12-31"

Antwortformat

Alle OAI-PMH Antworten sind im XML-Format strukturiert und UTF-8-kodiert.

Erfolgreiche Antwort (GetRecord Beispiel)

<?xml version="1.0" encoding="UTF-8"?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
         http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
  <responseDate>2025-08-05T10:30:00Z</responseDate>
  <request verb="GetRecord" metadataPrefix="edm"
           identifier="https://id.kulturpool.at/b1eaac0f-69a1-4174-8ac6-90a61615d0ae">
    https://api.kulturpool.at/oai
  </request>
  <GetRecord>
    <record>
      <header>
        <identifier>https://id.kulturpool.at/b1eaac0f-69a1-4174-8ac6-90a61615d0ae</identifier>
        <datestamp>2024-12-15T09:22:13Z</datestamp>
        <setSpec>kulturpool-europeana:wien-bibliothek</setSpec>
      </header>
      <metadata>
        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:edm="http://www.europeana.eu/schemas/edm/"
                 xmlns:dc="http://purl.org/dc/elements/1.1/"
                 xmlns:dcterms="http://purl.org/dc/terms/"
                 xmlns:ore="http://www.openarchives.org/ore/terms/">
          <!-- EDM/RDF Metadaten hier -->
          <edm:ProvidedCHO rdf:about="https://id.kulturpool.at/b1eaac0f-69a1-4174-8ac6-90a61615d0ae">
            <dc:title>Beispiel Titel</dc:title>
            <dc:creator>Beispiel Künstler</dc:creator>
            <dc:description>Beispiel Beschreibung</dc:description>
            <!-- weitere Metadatenfelder -->
          </edm:ProvidedCHO>
        </rdf:RDF>
      </metadata>
    </record>
  </GetRecord>
</OAI-PMH>

Fehlerantwort

<?xml version="1.0" encoding="UTF-8"?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/">
  <responseDate>2025-08-05T10:30:00Z</responseDate>
  <request>https://api.kulturpool.at/oai</request>
  <error code="badVerb">Illegal OAI verb</error>
</OAI-PMH>

Fehlerbehandlung

Das OAI-PMH Protokoll definiert standardisierte Fehlercodes:

Code	Bedeutung
`badArgument`	Ungültiges Argument
`badResumptionToken`	Ungültiger oder abgelaufener Resumption Token
`badVerb`	Ungültiges Verb
`cannotDisseminateFormat`	Nicht unterstütztes Metadatenformat
`idDoesNotExist`	Datensatz existiert nicht
`noMetadataFormats`	Keine Metadatenformate verfügbar
`noRecordsMatch`	Keine Datensätze entsprechen den Kriterien
`noSetHierarchy`	Repository unterstützt keine Sets

Paginierung

Bei großen Datenmengen verwendet OAI-PMH Resumption Tokens für die Paginierung:

<resumptionToken completeListSize="5000" cursor="100">
  token123456789
</resumptionToken>

Um die nächste Seite abzurufen:

GET /oai?verb=ListRecords&resumptionToken=token123456789

Resumption Token

Wird ein resumptionToken übergeben, dürfen keine weiteren Parameter außer verb mitgeschickt werden — insbesondere kein metadataPrefix, set, from oder until. Andernfalls antwortet der Server mit badArgument.

Vollständiges Harvesting (Python)

import requests
from xml.etree import ElementTree

OAI_URL = "https://api.kulturpool.at/oai"
NS = {"oai": "http://www.openarchives.org/OAI/2.0/"}


def harvest(metadata_prefix="edm", oai_set=None):
    params = {"verb": "ListRecords", "metadataPrefix": metadata_prefix}
    if oai_set:
        params["set"] = oai_set

    while True:
        response = requests.get(OAI_URL, params=params, timeout=60)
        response.raise_for_status()
        tree = ElementTree.fromstring(response.content)

        for record in tree.findall(".//oai:record", NS):
            yield record

        token = tree.find(".//oai:resumptionToken", NS)
        if token is None or not (token.text or "").strip():
            break

        # Mit resumptionToken nur noch verb + Token senden
        params = {"verb": "ListRecords", "resumptionToken": token.text.strip()}


for count, record in enumerate(harvest(oai_set="kulturpool-europeana:wien-bibliothek"), 1):
    identifier = record.find(".//oai:identifier", NS)
    print(count, identifier.text if identifier is not None else "?")

Anwendungsfälle

Für Aggregatoren

Europeana: Harvesting von Kulturpool-Daten für die europäische digitale Bibliothek
Weitere nationale und internationale Aggregatoren, die österreichische Kulturinhalte übernehmen

Für Forschung

Bulk-Download von Metadaten für Forschungszwecke
Systematische Analyse von Sammlungsbeständen
Aufbau lokaler Forschungsdatenbanken

Für Entwicklung

Integration in eigene Anwendungen
Aufbau von Mashups und Visualisierungen
Entwicklung spezialisierter Suchinterfaces

Alternative zum Harvesting

Wenn Sie ohnehin den gesamten Datenbestand benötigen, sind die Datensets zum Herunterladen meist der schnellere Weg — ein einzelner Download statt vieler paginierter Anfragen.

Basis-URL​

OAI-PMH Verben​

Identify​

ListMetadataFormats​

ListSets​

ListIdentifiers​

ListRecords​

GetRecord​

Verfügbare Metadatenformate​

EDM (Europeana Data Model)​

Beispielanfragen​

Repository-Informationen abrufen​

Alle verfügbaren Sets anzeigen​

Identifikatoren aus der Wienbibliothek​

Vollständige Datensätze aus der Wienbibliothek​

Spezifischen Datensatz abrufen​

Datensätze aus einem bestimmten Zeitraum​

Antwortformat​

Erfolgreiche Antwort (GetRecord Beispiel)​

Fehlerantwort​

Fehlerbehandlung​

Paginierung​

Vollständiges Harvesting (Python)​

Anwendungsfälle​

Für Aggregatoren​

Für Forschung​

Für Entwicklung​

Basis-URL

OAI-PMH Verben

Identify

ListMetadataFormats

ListSets

ListIdentifiers

ListRecords

GetRecord

Verfügbare Metadatenformate

EDM (Europeana Data Model)

Beispielanfragen

Repository-Informationen abrufen

Alle verfügbaren Sets anzeigen

Identifikatoren aus der Wienbibliothek

Vollständige Datensätze aus der Wienbibliothek

Spezifischen Datensatz abrufen

Datensätze aus einem bestimmten Zeitraum

Antwortformat

Erfolgreiche Antwort (GetRecord Beispiel)

Fehlerantwort

Fehlerbehandlung

Paginierung

Vollständiges Harvesting (Python)

Anwendungsfälle

Für Aggregatoren

Für Forschung

Für Entwicklung