Introduktion

Vi tillhandahåller ett API för maskinella uppdateringar av servicedata. 
Detta API lämpar sig för organisationer som har IT-avdelningar/utvecklare, då det krävs att dataleverantörer utvecklar egna klienter för att jobba mot vårt API. 

Med ServiceApi får du programmatiskt tillgång till Tillväxtverkets tjänster för att uppdatera servicedata.

ServiceApi är ett REST-baserat API där data överförs som JSON.
För att använda ServiceApi krävs ett giltigt användarnamn och lösenord.

Tillväxtverket tillhandahåller en testinstans av ServiceApi som med fördel används vid utveckling och test.
Innehållet i testinstansens databas återställs varje natt.

Uppdateringsstrategier

Det finns flera strategier för att uppdatera data via vårt API, bland annat inkrementell och full uppdatering.
Båda strategierna kräver att leverantörens data matchas mot Tillväxtverkets servicedata.
ServiceApi tillhandahåller inga mekanismer för att matcha data, det ansvarar respektive leverantör för.
En matchning kan göras genom att hämta ut alla serviceplatser och sedan jämföra exempelvis dess adresser och koordinater med leverantörens interna register. 

I Tillväxtverkets databas finns idag ca 17 000 serviceplatser och många av utförarna är samma år från år för de olika servicetyperna. Sannolikheten att det redan finns en befintlig serviceplats i databasen att koppla på en service till är därför stor. Trots detta kan en matchning mellan exempelvis besöksadress och postort ge relativt få träffar eftersom adresserna kan vara skrivna på olika sätt i de olika matchningsregistren.

Försök i möjligaste mån matcha mot en befintlig serviceplats innan ni ger er på att skapa helt nya serviceplatser. Tänk på att det kan finnas andra attribut i utförarinformationen som också går att matcha på än besöksadress och koordinat. Exempelvis kan även serviceplatsens namn vara vägledande för matchningsmetoden.     

Inkrementell

Hämta via API en kollektion med all service och dess serviceplatser som leverantören ansvarar för.
Uppdatera de som har ändrats.
Radera de som har försvunnit.
Skapa de som har tillkommit.
När en ny service skapas, kontrollera ifall det finns en serviceplats på aktuell adress och använd den, annars skapa en ny serviceplats.
Endast serviceplatser som saknar relationer till service får raderas.
Upptäcks fel på befintliga serviceplatser, rapporteras dessa med ett ändringsförslag.

Full uppdatering

Vid en full uppdatering, då raderas först all service som leverantören ansvarar för, sedan skapas all service igen och binds till befintliga serviceplatser.
Fördelen med en full uppdatering är att borttag, nya och uppdateringar inte behöver hanteras separat, däremot måste all service som skapas matchas mot befintliga serviceplatser (där det är möjligt).

Autentisering

För att använda API'et krävs en användare som administreras av er i administrationsportalen.

Autentiseringen baseras på OAuth 2.0 Authentication.

Ett giltigt token erhålls efter en accepterad inloggning, därefter används denna token (bakas in i HTTP headern Authorization) i alla anrop mot API'et. 

Om ni är intresserade av att uppdatera data via det maskinella APIét och har frågor kontakta anders.dahlgren@tillvaxtverket.se .