Hente data via OAI-PMH

Om OAI-PMH

OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting) er en internasjonal standard for å hente ut beskrivelser av ressurser fra en katalog. Den brukes mye til høsting mellom kataloger og dataportaler. Standarden er beskrevet i OAI-PMH versjon 2.0.

Hva du får ut

Hver post i uttrekket er beskrevet i RDF og leveres i formatet RDF/XML (valgt med metadataPrefix=rdfxml i steg 2). Beskrivelsene følger en standard for hver ressurstype, for eksempel DCAT-AP-NO for datasett og SKOS-AP-NO-Begrep for begreper.

Slik fungerer det

OAI-PMH-endepunktet leverer uttrekket som en liste med poster. Hver post beskriver én ressurs, for eksempel ett datasett eller ett begrep, avhengig av hvilket uttrekk du henter. Store lister deles opp i flere sider. Hver gang du åpner en adresse får du én side med inntil 50 poster. Neste side henter du ved å endre adressen. Hver side, bortsett fra den siste, slutter med en fortsettelsesnøkkel (resumptionToken) som du bruker for å hente neste side.

Steg 1: Velg uttrekk

Finn ID-en for uttrekket du vil hente. Disse uttrekkene er tilgjengelige i dag:

En oppdatert oversikt med antall poster i hvert uttrekk finner du i API-dokumentasjonen.

Steg 2: Hent første side

Lim inn denne adressen i adressefeltet. Bytt ut <ID> med ID-en for uttrekket du valgte i steg 1:

Kopier
https://resource.api.fellesdatakatalog.digdir.no/v1/union-graphs/<ID>/oai-pmh?verb=ListRecords&metadataPrefix=rdfxml

Du får opp XML med de første 50 postene. Lagre siden med Ctrl+S (Mac: Cmd+S) hvis du vil ta vare på den.

Steg 3: Finn fortsettelsesnøkkelen

Trykk Ctrl+F (Mac: Cmd+F) og søk etter resumptionToken. Nederst på siden finner du en linje som ligner på denne. Eksempel for et uttrekk med 81 poster:

Kopier
<resumptionToken completeListSize="81" cursor="0"><ID>:rdfxml:50</resumptionToken>

completeListSize viser hvor mange poster uttrekket inneholder totalt. cursor viser hvor mange poster som kom før denne siden. På første side er den 0. Står det cursor="50", starter siden på post nummer 51. Teksten mellom taggene er nøkkelen til neste side.

Finner du ikke resumptionToken, fikk hele uttrekket plass på én side, og du er ferdig. Antall poster finner du da ved å søke etter <record> med Ctrl+F (Mac: Cmd+F). Antall treff er antall poster på siden.

Steg 4: Hent neste side

Bytt ut alt etter ? i adressen med verb=ListRecords&resumptionToken= etterfulgt av nøkkelen du fant:

Kopier
https://resource.api.fellesdatakatalog.digdir.no/v1/union-graphs/<ID>/oai-pmh?verb=ListRecords&resumptionToken=<ID>:rdfxml:50

Merk: metadataPrefix=rdfxml skal ikke være med på denne og de neste sidene. Tar du den med, får du feilmeldingen badArgument. Nøkkelen husker hvilket format du valgte i steg 2.

Steg 5: Gjenta til du er ferdig

Gjenta steg 3 og 4 for hver ny side. Nøkkelen endrer seg bare i tallet på slutten, som øker med 50 for hver side (:50, :100, :150 osv.). Du kan derfor også hente neste side ved å øke tallet selv.

Når resumptionToken er tomt, har du hentet alle postene. Eksempel for et uttrekk med 81 poster:

Kopier
<resumptionToken completeListSize="81" cursor="50"/>

I eksempelet er 50 poster levert tidligere, så siste side viser post 51 til 81 av 81.

Øker du tallet forbi slutten av lista, får du feilmeldingen badResumptionToken. Da har du også hentet alt.

Tips

• Firefox og Chrome viser XML som et lesbart tre. Hvis siden ser tom ut eller bare viser tekst, prøv Ctrl+U (Mac: Cmd+Option+U) for å se kildekoden.
• Kolonene i nøkkelen fungerer vanligvis uten endring. Får du feil, prøv å bytte : med %3A.
• Vil du bare se hvilke poster som finnes, kan du bruke verb=ListIdentifiers i stedet for verb=ListRecords i steg 2. Da blir sidene mye mindre, og framgangsmåten er den samme.