Teknisk beskrivning

Detta är en tjänst för att integrera åtkomst till vissa av Lantmäteriets arkiv i egna system.

Arkiven som normalt används är de statliga och många kommunala lantmäteriarkiv som finns tillgängliga hos Lantmäteriet.

Bildformat

Akterna tillhandahålls i bildformatet DjVu och PDF. Den DjVu som tillhandahålls är en DjVu-fil som innehåller många sidor, på samma sätt som PDF.  Storleken på PDF-filen är oftast något större än för motsvarande DjVu-fil för att få likvärdig bildkvalitet.

DjVu

För att kunna titta på en DjVu så krävs en DjVu-visare, det finns idag tre huvudval:

1. Valfri webbläsare tillsammans med en fristående DjVu-visare.
2. Det finns en HTML5-baserad DjVu-visare, djvu-html5, som inte kräver att någon DjVu-visare/plugin finns installerad på användarens dator, den har dock idag mycket mindre funktionalitet än de övriga alternativen.
3. DjVu-plugin till webbläsare. Detta har tidigare varit huvudalternativet men majoriteten av dagens webbläsare stödjer inte längre denna typ av plugins.

PDF

För att kunna titta på en PDF så krävs en PDF-visare. De flesta webbläsare har inbyggt stöd för PDF men det går även att installera en PDF-läsare som exempelvis Adobe Acrobat Reader i datorn.

Om det uppstår prestandaproblem med stora akter i webbläsarens inbyggda PDF-visare prova med en fristående.

Autentisering

Webbläsarna/visarna kan inte direkt använda detta API utan det krävs att ni har en mellanliggande tjänst som hanterar OAuth-autentiseringen.

Felhantering

Det finns två olika varianter av felhantering som kan väljas.

1. En som vid fel skickar http-status 200 samt en bild som visar vad som gått fel, denna variant måste användas om man använder DjVuplugin:en.
2. En som på normalt sätt skickar respektive http-status som beskriver felet samt en JSON med ytterligare detaljer där ni sedan själva får hantera presentationen av felet till användaren.

Se API-specifikationen för mer information om hur felen rapporteras. Bryter man mot API:et så får man ut en http-status och en JSON oavsett vilken variant av felhantering man valt.

Gränssnittsdefinition

Detta dokument är en förenklad dokumentation av tjänsten och ska vara tillräcklig för normal användning men tar inte upp alla detaljer. För mer detaljer se OpenAPI-filen. Den kan fås under API-Console i API-Store.

Åtkomstpunkt

Verifiering: https://api-ver.lantmateriet.se/distribution/produkter/aktdirekt/v5.0

Produktion: https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0

Format

Data hämtas i DjVu-format eller PDF-format med GET-anrop. Det går även att göra HEAD-anrop för att enbart få ut information om akten finns och exempelvis dess storlek.

Sammanfattning

Operationer

GET .../document.pdf?archive={arkiv}&id={aktbeteckning}&document_on_error={boolean}&free_data_only={boolean}

Beskrivning

Hämta en akt i form av en PDF från ett visst arkiv eller i ett visst län.

Om free_data_only=true ges endast åtkomst till akter som är gratis, vanligtvis är det akter som är skapade före 1929.

Felmeddelande

Vid fel så svarar tjänsten normalt med lämplig HTTP-felkod samt en JSON-sträng som innehåller felmeddelandet.

Om document_on_error=true svarar i stället tjänsten med HTTP-status 200 och ett pdf-dokument som innehåller felmeddelandet.

I båda fallen sätts även HTTP-headrarna Error-Code samt Error-Message.

Exempel, felmeddelande

{
  "code": 404,
  "reason": "Not Found",
  "detailedError": [
    {
      "code": "no_such_document",
      "message": "The requested document is not available in the specified archive or the archive does not exist: 'lm99' '99-alf-avs102 vol2'",
      "userMessage": "Akten finns inte i det angivna arkivet.",
    }
  ],
}

Vid fel i autentiseringen eller vid fel i middleware skickas ingen JSON.

Exempel

https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=k21g&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=21&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=21&id=2180-1416&document_on_error=true
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=21&id=2180-1416&free_data_only=true

Requestparametrar

archive sätts i normalfallet till länsnummer (01 eller 1 för Stockholm osv.). Värt att veta är att för län som blivit sammanslagna så ger sökning i det nuvarande länet träff i båda delarnas arkiv. Skåne län(12) är en sammanslagning av Kristianstad län(11) och Malmöhus län(12). Västra Götalands län(14) är sammanslagning av Göteborgs och Bohus län(14) och Älvsborgs län(15) och Skaraborgs län(16).

I verifieringsmiljön finns endast testakterna i län 99 tillgängliga.

Svar

En PDF-fil som innehåller den kompletta akten. Det skickas även HTTP-headrar med information enligt exemplet nedan:

"archive": lm99
"content-length": "789560"
"content-type": "application/pdf"
"date": "Fri,08 Jul 2022 05:20:41 GMT"
"document-id": "99-alf-avs102 vol2"
"free-data": True

GET .../document.djvu?archive={arkiv}&id={aktbeteckning}&document_on_error={boolean}&free_data_only={boolean}

Beskrivning

Hämta en akt i form av en DjVu från ett visst arkiv eller i ett visst län.

Om free_data_only=true ges endast åtkomst till akter som är gratis, vanligtvis är det akter som är skapade före 1929.

Felmeddelande

Vid fel så svarar tjänsten normalt med lämplig HTTP-felkod samt en JSON-sträng som innehåller felmeddelandet.

Om document_on_error=true svarar i stället tjänsten med HTTP-status 200 och ett DjVu-dokument som innehåller felmeddelandet.

I båda fallen sätts även HTTP-headrarna Error-Code samt Error-Message.

Exempel, felmeddelande

{
  "code": 404,
  "reason": "Not Found",
  "detailedError": [
    {
      "code": "no_such_document",
      "message": "The requested document is not available in the specified archive or the archive does not exist: 'lm99' '99-alf-avs102 vol2'",
      "userMessage": "Akten finns inte i det angivna arkivet.",
    }
  ],
}

Vid fel i autentiseringen eller vid fel i middleware skickas ingen JSON.

Exempel

https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=k21g&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=21&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=21&id=2180-1416&document_on_error=true
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=21&id=2180-1416&free_data_only=true

Requestparametrar

archive sätts i normalfallet till länsnummer (01 eller 1 för Stockholm osv.). Värt att veta är att för län som blivit sammanslagna så ger sökning i det nuvarande länet träff i båda delarnas arkiv. Skåne län(12) är en sammanslagning av Kristianstad län(11) och Malmöhus län(12). Västra Götalands län(14) är sammanslagning av Göteborgs och Bohus län(14) och Älvsborgs län(15) och Skaraborgs län(16).

I verifieringsmiljön finns endast testakterna i län 99 tillgängliga.

Svar

En DjVu-fil som innehåller den kompletta akten. Det skickas även HTTP-headrar med information enligt exemplet nedan:

"archive": lm99
"content-length": "789560"
"content-type": "image/vnd.djvu"
"date": "Fri,08 Jul 2022 05:20:41 GMT"
"document-id": "99-alf-avs102 vol2"
"free-data": True

HEAD .../document.pdf?archive={arkiv}&id={aktbeteckning}

Beskrivning

Som motsvarande GET-anrop 4.4.1 men svarar enbart med HTTP-headrar, inget PDF-dokument.

Felmeddelande

Vid fel så svarar tjänsten med lämplig HTTP-felkod och information om felet i HTTP-headrarna Error-Code och Error-Message.

Exempel

https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=k21g&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.pdf?archive=21&id=2180-1416

Requestparametrar

archive sätts i normalfallet till länsnummer (01 eller 1 för Stockholm osv.). Värt att veta är att för län som blivit sammanslagna så ger sökning i det nuvarande länet träff i båda delarnas arkiv. Skåne län(12) är en sammanslagning av Kristianstad län(11) och Malmöhus län(12). Västra Götalands län(14) är sammanslagning av Göteborgs och Bohus län(14) och Älvsborgs län(15) och Skaraborgs län(16).

I verifieringsmiljön finns endast testakterna i län 99 tillgängliga.

Svar

HTTP-headrar som innehåller information om akten.

Exempel, header

"archive": lm99
"content-length": "789560"
"content-type": "application/pdf"
"date": "Fri,08 Jul 2022 05:20:41 GMT"
"document-id": "99-alf-avs102 vol2"
"free-data": True

HEAD .../document.djvu?archive={arkiv}&id={aktbeteckning}

Beskrivning

Som motsvarande GET-anrop 4.4.2 men svarar enbart med HTTP-headrar, inget DjVu-dokument.

Felmeddelande

Vid fel så svarar tjänsten med lämplig HTTP-felkod och information om felet i HTTP-headrarna Error-Code och Error-Message.

Exempel

https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=k21g&id=2180-1416
https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/document.djvu?archive=21&id=2180-1416

Requestparametrar

archive sätts i normalfallet till länsnummer (01 eller 1 för Stockholm osv.). Värt att veta är att för län som blivit sammanslagna så ger sökning i det nuvarande länet träff i båda delarnas arkiv. Skåne län(12) är en sammanslagning av Kristianstad län(11) och Malmöhus län(12). Västra Götalands län(14) är sammanslagning av Göteborgs och Bohus län(14) och Älvsborgs län(15) och Skaraborgs län(16).

I verifieringsmiljön finns endast testakterna i län 99 tillgängliga.

Svar

HTTP-headrar som innehåller information om akten. 

Exempel, header

"archive": lm99
"content-length": "789560"
"content-type": "image/vnd.djvu"
"date": "Fri,08 Jul 2022 05:20:41 GMT"
"document-id": "99-alf-avs102 vol2"
"free-data": True

GET .../ping

Använd denna för att verifiera att din kommunikation med tjänsten samt autentiseringen fungerar.

Exempel

https://api.lantmateriet.se/distribution/produkter/aktdirekt/v5.0/ping

 Svar

Om kommunikationen med tjänsten fungerar så blir alltid svaret enligt nedan:

{
	"response":"pong"
}