Bygg med Handlingar

Från första anrop till
en egen databas.

API:et ger tillgång till dokument, extraherad fulltext, metadata och källor för de kommuner som ingår i din åtkomst.

OpenAPI-specifikation (JSON) · Synkroniseringsexempel (Python)

1. Logga in och skapa en nyckel

När vi har öppnat din pilot loggar du in med din e-postadress och en engångskod. I kundportalen skapar och återkallar du dina egna API-nycklar. Där ser du också kommunurval, anropsgräns och åtkomstens slutdatum.

Skicka nyckeln i Authorization: Bearer …. Förvara den på din server och lägg den aldrig i en URL eller i kod som skickas till webbläsaren.

2. Hämta dokument och fulltext

curl --fail --get \
  'https://handlingar.kungjort.se/api/v1/documents' \
  -H "Authorization: Bearer $KUNGJORT_API_KEY" \
  --data-urlencode 'kommun=skelleftea' \
  --data-urlencode 'q=skogsbruk' \
  --data-urlencode 'limit=10'

Listan returnerar metadata och en document_url för varje dokument. Hämta den för att läsa raw_text, raw_md och fullständiga paragrafblock. Använd source_url för kommunens källadress och original_url för en arkivkopia när den ingår i din åtkomst.

Resurs under /api/v1	Innehåll
`/documents`	Dokumentlista, sökning och historisk export.
`/documents/{id}`	Fulltext, metadata, paragrafer och ärendereferenser.
`/documents/{id}/files`	Arkiverade filversioner med SHA-256.
`/documents/{id}/original`	Originalfil, med valfri `sha256` för en bestämd version.
`/cases`	Dokument med ett extraherat diarienummer.
`/coverage`	Aktuellt bestånd per kommun, organ, år och dokumenttyp.
`/changes`	Nya, ändrade och borttagna poster efter en sparad cursor.

Listan kan filtreras med kommun, organ, doc_type, since, until, q och dnr. Datumfiltren gäller dokumentets mötesdatum. Följ next_cursor med samma filter. Högst 100 dokument returneras per sida.

3. Bygg och uppdatera din databas

Börja med /documents utan ämnes- eller datumfilter. Spara första svarets changes_cursor.
Följ next_cursor till slutet. Hämta fulltexten och spara varje dokument med dess ID som nyckel.
Hämta /changes?cursor=… från den sparade startpunkten. Det fångar även rättelser som kom medan exporten pågick.
Vid upsert, hämta dokumentet på nytt och ersätt den lokala posten inklusive paragrafer. Vid delete, ta bort den lokala posten. Ett 404 efter en upsert behandlas också som borttagning.
Spara checkpoint efter att hela batchen har skrivits. Kör sedan samma flöde exempelvis dagligen. Behåll senaste revision även för borttagna poster.

Det körbara Python-exemplet använder SQLite och standardbiblioteket. Det sparar data och checkpoint tillsammans och kan återupptas efter avbrott.

export KUNGJORT_API_KEY='din-nyckel'
python3 sync.py --database handlingar.sqlite

Ändringsflödet omfattar hela ditt kommunurval. Gör ämnesurval i din egen databas. Starta en ny export om åtkomstens kommunurval ändras.

Täckning, identiteter och källor

Dokument-ID är beständigt för en arkivpost och ändras inte när texten parsas om. Titlar och nämndnamn är metadata, inte dokumentnycklar. Två separat publicerade kopior kan ha olika ID:n.

Paragrafer behåller sitt section_id när de säkert kan matchas efter en rättelse. Vid en tvetydig delning eller sammanslagning kan nya ID:n uppstå. Ersätt därför dokumentets hela paragrafuppsättning vid uppdatering.

Ärenden kopplas via kommun och normaliserat diarienummer. Det är en extraherad referens, inte en garanti för att alla dokument i ärendet har hittats eller att numret aldrig återanvänds i olika diarier.

Publiceringssammanhang finns i publication_organ och publication_meeting_date när källan anger det. De kan skilja sig från organ och meeting_date i en bilagas eget innehåll. Organfiltret och täckningslistan använder publiceringsorganet när det finns.

Originalversioner identifieras med SHA-256. parsed_original_url pekar på filen som texten säkert kan knytas till, annars är fältet tomt. Kommunens källadress kan försvinna även om arkivkopian finns kvar.

Täckningslistan visar vad vi har, inte att alla möten finns med. Äldre material kan saknas på kommunens webbplats. OCR, datum, dokumenttyp och diarienummer kan bli fel. Kontrollera viktiga uppgifter mot originalet; kvalitetsfält som parse_status och parse_flags följer med.

Anropsgränser och felsökning

Alla dina nycklar delar kundens minutkvot. Vid 429, vänta enligt Retry-After. Vid tillfälliga serverfel, försök igen med ökande väntetid. Varje svar innehåller X-Request-ID; skicka det till oss vid ett fel.

Administratörer kan se anropens tid, nyckel, metod, sökväg, tillåtna sökparametrar, svarskod och svarstid för att felsöka och utveckla tjänsten. Loggen sparas i 30 dagar. Nyckelvärden, cookies, IP-adresser och innehåll i förfrågningar eller svar sparas inte.

Åtkomst och pilot

Omfattning, användning och eventuell fortsättning bestämmer vi tillsammans inför din pilot. Inloggning skapar inte ett abonnemang. Kontakta oss för att komma igång eller utöka din åtkomst.

Logga in med e-postkod →