Application Programming Interface (API)
De API (Application Programming Interface) is bedoeld voor hergebruik van onze data en metadata. Deze API is de ‘poort’ tot alle collectiedata in ons collectiebeheersysteem. Het zoeksysteem van het Stadsarchief wordt gevoed via de API, maar hij staat open voor iedereen. Alle openbare collectiedata kunnen dus worden hergebruikt door derden.
Hergebruik
Via de API (https://id.archief.amsterdam/docs/openapi) kunnen alle collectiedata worden bevraagd. We nodigen iedereen uit om verrassende, mooie, handige applicaties te maken of onderzoeken uit te voeren door middel van deze API. Wel gelden bij hergebruik, net als voor gebruik via het reguliere zoeksysteem onze gebruiksvoorwaarden.
Gegevens (data en metadata) over mogelijk nog levende personen mogen alleen worden gebruikt en hergebruikt voor historisch (waaronder genealogisch), wetenschappelijk of statistisch onderzoek.
De gegevens mogen hergebruikt worden onder de volgende voorwaarden.
Gegevens over mogelijk nog levende personen: gegevens mogen niet gekoppeld worden, scans mogen niet doorzoekbaar gemaakt worden en gegevens mogen niet met kunstmatige intelligentie worden verwerkt. Lees meer in het Beleid Persoonsgegevens
Auteursrecht: hergebruik is alleen mogelijk als er geen auteursrecht op een afbeelding rust. Lees meer in het Beleid Auteursrecht.
Bronvermelding: bij alle vormen van hergebruik stellen we een bronvermelding op prijs
Mogelijkheden van de API
Via https://id.archief.amsterdam/ is de collectiedata te bevragen. Je kunt bijvoorbeeld alle metadata van één specifiek record ophalen, of alle records van één type, bijvoorbeeld alle Afbeeldingen. Je kunt met een zoekopdracht werken om alle items die aan die zoekopdracht voldoen op te halen. Je kunt hier ook parameters voor gebruiken als dit veld ‘bevat waarde’ (notEmpty), een datum van laatste wijziging (modified date) etc.
Als je in de API veel records op wilt halen, is hiervoor een zogenoemd resumption token beschikbaar. Hiermee kun je steeds de volgende X records die voldoen aan je criteria ophalen, net zo lang totdat je ze allemaal hebt. Met de API kun je ook een OAI-PMH request doen om hele sets te harvesten.
Wil je plaatjes hergebruiken, dan moet je daarvoor nu zowel het record (de betreffende beschrijving / metadata) ophalen als het asset (het bestand). In de toekomst willen we het ook mogelijk maken losse assets op te halen. Dat kan uiteraard alleen als ze publiek beschikbaar zijn.
Voorbeelden
Om een wat concreter beeld te geven over wat je met zo’n API zou kunnen, geven we hier drie voorbeelden. Uiteraard zijn de mogelijkheden zo goed als eindeloos en zijn deze voorbeelden geenszins representatief.
Voorbeeld 1: afbeeldingen
Stel, je maakt een website over je straat, de Postjesweg, en wilt op die website afbeeldingen van het Stadsarchief gebruiken.
1. Zoeken naar Afbeelding-records
Gebruik een POST-request om records op te halen die betrekking hebben op de Postjesweg en het type Image hebben:
curl -X POST "https://id.archief.amsterdam/search/records?lang=nl" \
-H "Content-Type: application/json" \
--data-binary @- <<DATA
{
"query": {
"type": "AndQuery",
"queries": [
{
"type": "FullTextQuery",
"query": "postjesweg"
},
{
"type": "FieldQuery",
"operator": "equals",
"field": "data.recordType.id",
"value": "Image"
}
]
},
"pagination": {
"page": 1,
"perPage": 50
}
}
DATA
Zie: https://reqbin.com/opfgkvuh
2. IIIF-URL's ophalen
De resultaten bevatten IIIF-URL's voor de afbeeldingen. Deze kun je eenvoudig parsen met jq:
jq '.rows[].media.rows[].iiif'
Met deze URL's kun je de afbeeldingen direct in bijvoorbeeld een website integreren.
3. Alle assets van een record ophalen
Sommige records hebben meerdere assets. Om alle assets van een specifiek record op te halen, gebruik je de volgende request: https://reqbin.com/3ws8jcsj
curl -X GET "https://id.archief.amsterdam/resources/records/44721875-d206-cf18-07d4-1915ba410422/assets?page=1&perPage=10" \
-H "Accept: text/turtle"
Het totaal aantal assets vind je in de response, bijvoorbeeld:
[ a <http://memorix.io/ontology#Pagination>; <http://memorix.io/ontology#total> "73"^^<http://www.w3.org/2001/XMLSchema#long> ]
Met behulp van de page/perPage query-parameter kan er over de assets heen worden genavigeerd.
Voorbeeld 2: akten en persoonsvermeldingen
Stel, je wilt voor een onderzoek alle gegevens van tewerkstellingen in de Tweede Wereldoorlog ophalen om daar een analyse op los te laten.
Dit kan met een zoekquery op het categorie-veld (Deed.rico:hasOrHadCategory) binnen het Akte recordtype.
1. Zoeken op veldwaarde
Gebruik een POST-request om alle records op te halen die behoren tot de categorie Tewerkgestelden '40-'45:
curl -X POST "https://id.archief.amsterdam/search/records?lang=nl" \
-H "Content-Type: application/json" \
--data-binary @- <<DATA
{
"query": {
"field": "field.Deed.rico:hasOrHadCategory",
"operator": "equals",
"subField": "title",
"type": "FieldQuery",
"value": "Tewerkgestelden '40-'45"
},
"pagination": {
"page": 1,
"perPage": 50
}
}
Probeer het hier uit: https://reqbin.com/asxtg3ct
2. Persoonsvermeldingen
In de response vind je records met UUIDs (“id”). Die kan je vervolgens gebruiken om metadata van de betreffende records op te halen met een GET request naar id.archief.amsterdam/resources/records/{id}:
curl --request GET \ --url https://id.archief.amsterdam/resources/records/114cd8d4-f447-4745-8dac-8c363c23e706 \ --header 'Accept: text/turtle, application/ld+json'
Uit de metadata van een akte kan je vervolgens ook de persoonsvermeldingen halen:
rico:hasOrHadSubject [ rdf:type saa:LinkedPersonObservation; memorix:order 1; saa:relatedPersonObservation <https://id.archief.amsterdam/961f6b1c-2444-53f7-e053-b784100aa83b>; saa:relatedPersonObservationRole <https://id.archief.amsterdam/resources/vocabularies/concepts/e8a92b13-efff-4b2e-e053-b784100a3466> ];
Voorbeeld 3: alle records van een archief
Stel, je doet onderzoek in het archief van de Wisselbank, en je wilt in een andere omgeving alle stukken uit dat archief op een andere manier presenteren.
Zoeken naar alle records gekoppeld aan een archief:
Om alle records die gekoppeld zijn aan een specifiek archief, zoek je eerst de IRI van het archiefblok op. In dit geval is dat https://id.archief.amsterdam/80ae8641-ab87-40ae-e053-b784100ad8d3
Met een POST-request kan je vervolgens alle records op halen die gekoppeld zijn aan dat archief:
curl -X POST "https://id.archief.amsterdam/search/records?lang=nl" \
-H "Content-Type: application/json" \
--data-binary @- <<DATA
{
"query": {
"field": "_link",
"operator": "equals",
"type": "FieldQuery",
"value": "https://id.archief.amsterdam/80ae8641-ab87-40ae-e053-b784100ad8d3"
},
"pagination": {
"page": 1,
"perPage": 50
}
}
Probeer het hier uit: https://reqbin.com/vxgyzen7
De response bevat alle records die een link bevatten naar https://id.archief.amsterdam/80ae8641-ab87-40ae-e053-b784100ad8d3 (Archiefblok “5077, Archief van de Wisselbank”)
URI’s
Via de API wordt een domein-onafhankelijke permalink (een zgn. persistent HTTP URI) aangeboden volgens het format: https://id.archief.amsterdam/uuid. Hierbij worden de richtlijnen van Netwerk Digitaal Erfgoed gevolgd.
Bij gebruik van zo’n link wordt de RDF metadata teruggegeven. Je kunt deze link echter ook gebruiken in een websiteomgeving (zoals het zoeksysteem van het Stadsarchief) en zorgen dat deze data aan de websitekant wordt weergegeven als een detailpagina. Bijvoorbeeld: een link als https://id.archief.amsterdam/f9bbf8f8-75bf-2232-1a3e-ad7cde4a9f9b wordt als het ware ‘vertaald’ naar https://beta.archief.amsterdam/detail/f9bbf8f8-75bf-2232-1a3e-ad7cde4a9f9b In de API zie je dit terug bij het label isShownAt; de data wordt op dit moment getoond op deze webpagina van het Stadsarchief.
Het Stadsarchief heeft hiervoor gekozen om het leggen van links zowel gebruiksvriendelijk als duurzaam te maken. De links uit de API zijn écht duurzaam, mochten we als archief ooit nog van naam of website veranderen.
Tot slot
Deze API is een eerste stap waarmee we verschillende vormen van hergebruik mogelijk maken. Op termijn komt er ook een SPARQL-endpoint waarmee andere, getrapte queries gedaan kunnen worden.
De API bevat alleen de data die in het collectiebeheersysteem zitten. Dit wordt steeds meer. Wat er bijvoorbeeld op dit moment nog niet inzit, zijn de transcripties. Die zijn te doorzoeken op de pagina van Transkribus. Ook willen we in de toekomst de mogelijkheden van het IIIF manifest nog verder benutten.
Bekijk de Github repository van het Stadsarchief als je meer wilt weten over het datamodel (de blauwdruk) of enkele voorbeelden van Records in Contexts wilt zien.