API för (admin.)dataportal.se¶
All information om datamängder som syns på dataportal.se finns tillgängliga via API:et på admin.dataportal.se. Det innebär att om man har andra behov som inte täcks av vad som finns på dataportal.se eller api.dataportal.se så kan man ladda ner informationen och vidareutnyttja utifrån eget tycke.
Admin.dataportal.se använder sig av EntryScape Registry och lagringslösningen EntryStore för att hantera metadata. Generell dokumentation om det underliggande API:et finner du här:
- Swagger för hela API:et https://entrystore.org/api/
- Samt mer detaljerad information om hur sökning fungerar https://entrystore.org/kb/search/
Utöver denna generella dokumentation följer nedan mer specifik och förenklad dokumentation om hur API:et används på admin.dataportal.se.
Uppdateringsfrekvens¶
Varje natt försöker registrera uppdatera infomrationen om datamängderna genom att skörda om från alla registrerade organisationer. Det innebär att informationen kan som mest vara 24 timmar gammal förutsatt att skördningen från källan fungerar som den ska.
Nattlig dump¶
Varje natt efter att informationen om datamängder uppdaterats skapas en dump där all information samlats i formatet RDF/XML enligt den svenska profilen DCAT-AP-SE2.0.0:
Datamängdssök¶
Datamängderna beskrivs med hjälp av DCAT-AP-SE2.0.0 och formatet som används är RDF där datamängdernas identifierare är URI:er som sätts av utgivande organisationer. Det är viktigt att bevara dessa URI:er. Detta skapar viss komplexitet i API:et då man behöver slå upp baserat på identiferare som motsvarar andra domäner.
API:et innefattar ett sökorienterat API där man kan filtrera fram vilka datamängder man vill ha i en lista. API:et tillåter också anrop för att få ut metadata om enskilda datamängder såväl som andra entiteter.
Söka efter datamängder¶
Följande sökfråga ger en paginerad lista med alla datamängder:
Här används offset för paginering, parametern limit kan ökas till max 100 för att få fler svar i ett anrop. Parametern rdfType indikerar vilken typ av entiteter vi söker efter, i detta fall är det datamängder då typen är http://www.w3.org/ns/dcat#Dataset, observera att först har tecknet : escapats då det har en särskild betydelse i frågespråket som används (Solr) och därefter har uttrycket urlenkodats.
Svaren man får tillbaka är en JSON struktur som ser ut som:
{
"offset": 0,
"limit": 10,
"results": 7038,
"resource" {
"children": [
{
"contextId": "574",
"entryId": "2700",
"metadata": {
// Dataset metadata
},
...
},
...
]
}
}
Datamängdernas metadata uttrycks i formatet rdf/json.
Det finns en mängd olika sökkriterier man kan lägga till, t.ex. för att söka efter datamängder där svenska titlar matchar ett visst kriterium kan använda parametern title.sv i sökfrågan, t.ex:
Slå upp en enskild datamängd¶
Om man har koll på vilken identitet en datamängd har enligt organisationen som publicerar den, dvs dess URI, kan man söka efter den för att nå dess metadata via resource fältet i sökindexet:
https://admin.dataportal.se/store/search?type=solr&query=public:true+AND+(resource:URI)
Där du ersätter URI med datamängdens adress (eller någon annan entitet som en utgivare, kontakt, distribution osv.), glöm inte att först escapa : och sen urlenkoda. Här är ett exempel på hur man gör det i JavaScript.
const dataset = encodeURIComponent('http://example.com/dataset1'.replace(':', '\\:'));
// dataset now has the value "http%5C%3A%2F%2Fexample.com%2Fdataset1"
const queryURL = `https://admin.dataportal.se/store/search?type=solr&query=public:true+AND+(resource:${dataset})`;
Det går också att be om att få ut all metadata för en viss datamängd om man känner till API:ets egna sätt att identifiera datamängden (observera att API:et gör sitt bästa att behålla identifierarna över tid, men om datamängden tas bort och sen läggs till igen kan identifieraren ha ändrats). I resultatlistan anges varje träffs identitet via en kombinationen avcontextId och entryId. I detta fall kan vi be att också få med relaterade entiteter (t.ex. distributioner och utgivare) genom att lägga till parametern recursive=dcat:
https://admin.dataportal.se/store/{contextId}/entry/{entryId}?recursive=dcat
Du kan välja mellan lite olika format, antingen via content negotiation eller genom att sätta den explicita format parametern &format=text/turtle. Om man inte anger ett format får man application/rdf+xml.
Slå upp andra förvaltade entiteter¶
Låt oss ta ett exempel där vi har hittat en datamängd och i dess metadata står det att dess utgivare (dcterms:publisher) är http://id.kb.se/organisations/SE2021000837. För att hitta metadata för utgivares URI behöver vi söka efter den på liknande sätt som för en datamängd när man har dess URI, här är ett exempel på hur man gör det i JavaScript:
const publisher = encodeURIComponent('http://id.kb.se/organisations/SE2021000837'.replace(':', '\\:'));
// publisher now has the value "http%5C%3A%2F%2Fid.kb.se%2Forganisations%2FSE2021000837"
const queryURL = `https://admin.dataportal.se/store/search?type=solr&query=public:true+AND+(resource:${publisher})`;
Observera att exemplet ovan motsvarar en mer generell princip. Dvs i sökresultat får man bara med metadata för precis det man söker efter t.ex. datamängdens egen metadata. Man får inte med refererade entiteter, t.ex. distributioner, utgivare, kontakter osv. Dessa är enbart angivna via deras identifierare (URI:er) och nås via separata uppslag (*). Detta skiljer sig från dumpen ovan där alla relaterade entiteter finns med.
(*) Detta gäller för förvaltade entiteter som datamängder, distributioner, kataloger, osv. De förvaltade entiteterna är de som listas i specifikationen under primära klasser. De övriga klasserna som benämns stödjande klasser levereras som en del av metadatat för respektive primär klass och behöver därmed ingen separat uppslagning. Slutligen finns det referenser till begrepp, dvs allt som listas under vokabulärer. Metadata om dessa begrepp (URI:er) är information som förvaltas som en del av DCAT-AP-SE, inte något som API:et förvaltar. Implementatörer förväntas ha information om dessa URI:er, t.ex. för att kunna presentera lablar istället för URI:er. Relevant informationen om begreppen ska gå att slå upp genom att dereferera dem, men ytterligare information, t.ex. lämpliga översättningar i maskinläsbara format, finns också som en del av den svenska specifikationen på github.
Skördningsstatus¶
Den som är nyfiken över hur många datamängder det finns per organisation kan göra följande anrop:
För att få information om exakt vilken organisation som skördades senaste dygnet och hur många av dessa datamängder som kommer från offentlig sektor kan man göra följande anrop:
I det sistnämnda anropet kan man ändra limit och se historiska data flera år tillbaka. Formatet i det svaret kräver dock lite mer bearbetning då organisationsnamn inte står i klartext utan istället anges indirekt via ett contextId som motsvarar en skördad datakatalog. Man kan se contextId insprängt i en speciell property, som i följande exempel där contextId är 170, värdet som pekas ut är antalet datamängder som skördats för den organisationen:
http://entrystore.org/terms/statistics#datasets_in_context_170: 2
För att förstå resultatet bättre är det rekommenderat att man kombinerar med följande anrop som ger alla senaste skördningsrapporter per organisation. Utöver detaljerad skördningsstatus ser man nämligen också kopplingen mellan contextId och namn på organisationen (via propertyn dcterms:title):
Om man bara vill få ut skördninstrapporter för offentliga organisationer kan man lägga till filtret psi: