Hjälp VGR testa vårt API med öppna vaccintider

Är du utvecklare, teknikentusiast eller bara lite nyfiken? Nu kan du hjälpa oss i Västra Götalandsregionens digitala covidteam med att utvärdera testversionen av vårt API.

Den här bloggposten kommer uppdateras löpande med mer pedagogiska detaljer, kodexempel och tillämpningar. Så känns det övermäktigt i nuvarande skick får du gärna titta in igen senare så kanske vi hunnit dokumentera ikapp.

Genvägar:


Bakgrund

VGR:s team har byggt både en översikt för PCR-testning som lanserades i januari och en samlingssida för bokningsbara vaccintider som lanserades i maj. Redan i vintras väcktes tanken om att släppa de data vi själva använder öppet på något sätt. Kanske via ett API eller som öppna data. Frågan prioriterades egentligen först när Pierre Mesure förvarnade oss om hans helgprojekt i mitten på maj, vilket inom några dagar blev tjänsten jagvillhavaccin.nu

När vi nu hade en potentiell konsument av den data vi själva använde var beslutet enkelt. Vi ville släppa dessa data öppet. Och här är vi nu några dagar efter det beslutet med en första testversion av detta API.

Du kan hjälpa oss på traven. Vi är nyfikna på vad du gillar, vad du saknar, funkar det pålitligt, etc. Helt enkelt om du tycker att det är ett bra API och rimligt att komma igång.

Legalese

Vi hävdar ingen upphovsrätt på de data du får ut från tjänsten. Vi betraktar dem som Public Domain, CC0 eller den mest tillåtande licensen vi kan komma på. Vår tolkning, utan att ha hunnit fråga någon av våra jurister, är att det faller under PSI-lagen. Det vill säga invånarnas rätt att återanvända information som samlats in av offentlig sektor.

Pröva helt utan tekniska förkunskaper

Gå till Google Colab och klicka på play-knappen för att provköra.

Den enklaste varianten vi kan komma på för att provköra vår tjänst är om du har ett Google-konto. Då kan du logga in på Google Colab och bara klicka på en play-knapp. Det som händer är att det under rutan med kod kommer dyka upp några mottagningar som har tider och den bokningslänk som föreslås av API:t.

Provkör på Google Colab >

Använd vårt API / statiska JSON-svar

Skaffa dig dina egna API-nycklar

Vi har en instruktion för hur du skaffar dig ditt eget konto på Mulesoft och egna API-nycklar. Notera att detta innebär att ditt namn och kontaktuppgifter lagras hos Mulesoft och Amazon. Läs deras ToS och integritetspolicy, men VGR har inga problem med att du anger information av tillfällig karaktär eller mejladresser av temporär karaktär likt Protonmail. Vi kan vilja kontakta dig angående ditt konto eller förändringar i tjänsten, men det här är inte tvingande.

Steg för att få dina API-nycklar:

  1. Skaffa konto på Mulesoft. Det gör du genom ”Request access” på följande sida hos Mulesoft.
  2. När du är klar med ditt konto klickar du på nytt på knappen ”Request access” och fyller i vad som behövs enligt vår guide till Mulesoft.
  3. Inom en stund kommer ett mejl med en länk till dina uppgifter.

Gör HTTP-anrop till testtjänsten

Ställ frågan till:
https://api.vgregion.se/e-crm-scheduling-public/api/v1/testCenter

Du behöver följande HTTP-headers:
client_id: ditt-client-id
client_secret: din-hemlighet

Exempel på hur ett anrop ser ut i verktyget Postman (se nedan för att ladda ner).
Exempel på hur ett anrop ser ut i verktyget Postman (se nedan för att ladda ner).

Vi har ett repo på Github med exempelkod som en Jupyter Notebook och en ren Python-fil. Dessutom exempeldata vid de tillfällen API:t är nere eller du vill utveckla mot din lokala maskin.
api-vaccin-exempelkod (Github)

Förklaring av API:t

  • title: Namn på vaccinatören / vårdmottagningen
  • hsaid: vaccinatörens unika ID (register över HSAID)
  • municipality: heltal/siffra för i vilken kommun vaccinatören verkar (register över kommunkoder)
  • urlBooking: URL för invånaren att boka vaccinationstid dos 1 hos vaccinatören
  • urlContactCard: URL till vaccinatörens kontaktsida på 1177.se
  • urlContactCardText: används internt av VGR, troligen meningslöst för alla andra
  • testtype: används internt av VGR, troligen meningslöst för alla andra
  • timeslots: heltal, ibland null för 0/unknown, anger antal lediga tider inom angivet tidsintervall
  • updated: yyyy-mm-dd hh:mm:ss, tidstämpel för när den interna tjänsten senast hämtade information från VGR:s integrationsplattform

Bra resurser

  • HSAID och mottagningsnamn – HSAID är de unika identiteter som en vårdgivare har. På denna länk finns en förteckning över dem.
  • Förteckning över kommunkoder – vårt API returnerar kommunkoder istället för namnet på respektive kommun.
  • npm-bibliotek som förenklar användningen av API:t, skapat av en invånare som hjälpte oss testa API:t

Tips på verktyg

8 svar på ”Hjälp VGR testa vårt API med öppna vaccintider”

  1. Trevligt!

    Kommentarer:

    1) Går det att prenumerera på uppdateringar, istället för att behöva polla efter datan? (Tänker Kafka-ström, pubsub eller liknande.)
    Om inte, lämna gärna en rekommendation på hur ofta datan uppdateras, och därmed bör hämtas. (Kan ju lösas med HTTP enligt 2 nedan.)

    2) Om det nu inte går att komma från pollandet, generell kommentar är att det är oklart varför datan, som verkar helt oberoende av input utifrån, inte är förberäknad och distribuerad med t ex AWS S3. Här kan datans freshness iaf avgöras med vanlig HTTP-logik (Etag, Last-Modified, Cache-Control och relaterade headers).

    3) Att avkräva nycklar för access är givetvis sunt för att kunna få spårbarhet (noggrannare monitorerbarhet) i ev störande beteenden, samt spåra hur många & hur ofta som API:et nyttjas, och ev kunna bestrida den/de som missköter sig. Finns en portal för att registrera sig som användare av plattformen och dess data/API?

    1. Tack!

      1. Ja det har också slagit oss som jobbat med API:t, men att pubsub existerar hade jag hunnit glömma bort. Ska undersöka detta. Var mer inne på RSS/Atom eller kanske activitystream för när något upptäcktes för första gången i vår ände.
      2. Jag tolkar det som att vi via HTTP borde ange hur fräscht innehållet är. Visst. Men dels är det olika för respektive mottagning i listan (cirka 4 minuter gammal som mest), dels att sammanställningen nästan aldrig är mer än en handfull sekunder inaktuell. Jag tror vår policy är att du kan hämta varje sekund. Men det kanske uppstår problem i din ände?
      3. Denna portal finns nu när API:t är i produktion – se https://eu1.anypoint.mulesoft.com/exchange/portals/vastra-gotalandsregionen/7022b556-013d-4fc9-966c-298db3fc6a46/e-crm-scheduling-public/

      Ja, vi kommer flytta in API-driften till egna servrar. Exakt när är lite oklart just nu.

  2. Bra initiativ!
    Skulle gärna även vilja se vilken åldersgrupp som gäller för respektive bokningsställe.

    1. Tack för din återkoppling. Ja det hade varit bra men är dessvärre ingen information vi automatiskt kan få med oss i respektive källsystem för bokningsbara tider.
      Dock kommer jag ta med ditt förslag till vår lista i alla fall. Det kan inspirera någon att börja registrera sådan metadata.

  3. test.api.vgregion.se verkar inte svara längre!
    Har även provat med api.vgregion.se som svarar men accepterar inte nycklarna.

    1. Hej Göran

      Jag ligger lite efter med att uppdatera denna skrivelse. Ursäkta!
      Du behöver hämta dina egna nycklar på nedan URL:
      https://www.dataportal.se/en/datasets/197_2465/covid-19-vaccine-appointments-in-vastra-gotaland#ref=?p=1&q=v%C3%A4stra%20g%C3%B6taland&s=2&t=20&f=&rt=dataset$esterms_IndependentDataService$esterms_ServedByDataService

      Men du anropar på samma sätt som beskrivits här. Skriv gärna en ny kommentar om du kör fast så ska jag eller någon kollega försöka bistå!

  4. Hej!
    Har suttit och försökt hämta vårdcentraler som har lediga tider genom API:n men när jag jämför får jag det inte att stämma överens med hemsidan https://www.vgregion.se/ov/vaccinationstider/bokningsbara-tider/
    Jag ser exempelvis att Lindholmen erbjuder inom de närmsta två veckorna men det är inget jag får reda på när jag kör exempelkoderna. Varför kan det vara så? Nämner API:n enbart om det finns tider just idag?

    1. Hej Philip

      Den data vi släpper via API:t är den som ”tillhör” oss i VGR. Det är därför du endast får ut tider som gäller Närhälsans olika mottagningar. Den du refererar till på Lindholmen är sannolikt den som Kry driver på uppdrag av Västra Götalandsregionen.
      Vi har ställt frågan till några av de större leverantörerna av bokningssystem ifall de vill skicka med sina data men förstått att det inte är en fullt så enkel fråga att besvara.

      Tills vidare är det så klart ok om du väljer att jobba med webscraping av vår webbplats. Webbplatsen har en cache-timeout på en minut, så oftare än så är det det inte lönt att fråga respektive URL om den har nytt innehåll.

Lämna ett svar

Din e-postadress kommer inte publiceras. Obligatoriska fält är märkta *