Så här hämtar du EMIL-information från Susa-navet
Du kan hämta ut EMIL-information från Susa-navet. Informationen du får ut kan du filtrera och forma på ett antal olika sätt. Här kan du läsa om hur du gör.
För att kunna hämta ut och bearbeta informationen i EMIL behöver du ha ha kunskap om Svensk Standard SS10700 (EMIL) med avseende på typer, dokument, struktur och värdeförråd.
Standarden beskrivs på https://sis.se/emil
Länk till annan webbplats.
Det finns två API:er som kan användas för att hämta uppgifter ur SUSA-navet. REST-API:et är det mer moderna, resultaten är här på JSON-format. Det äldre så kallade EMIL-API:et returnerar de XML-dokument som SUSA-navets leverantörer har skapat.
Bägge API:erna hittar du här: https://susanavet2.skolverket.se/#/api/ Länk till annan webbplats.
REST-API:et
Detta API har ett så kallat Swagger-gränssnitt som utgör både dokumentation och utforskande funktioner. Alla olika anrop finns beskrivna och vilka argument de tar: https://susanavet2.skolverket.se/swagger-ui/ Länk till annan webbplats.
Det finns en volymbegränsning på detta API, varje anropande IP-adress får maximalt göra 5000 hämtningar per timme. Med hjälp av filter eller begäranden om många objekt i samma anrop kan mängden anrop begränsas.
Exempel på anrop
Alla anordnare i Hedemora kommun (kommunkod 2083):
https://susanavet2.skolverket.se/api/1.1/providers?municipality=2083 Länk till annan webbplats.
Alla anordnare för grundskola i Hedemora:
https://susanavet2.skolverket.se/api/1.1/providers?municipality=2083&organisationForm=grundskola Länk till annan webbplats.
En specifik anordnare, utifrån dess ID:
https://susanavet2.skolverket.se/api/1.1/providers/p.sv.35494110 Länk till annan webbplats.
Alla utbildningar som ges på finska:
https://susanavet2.skolverket.se/api/1.1/infos?language=fin Länk till annan webbplats.
Alla yrkesutbildningar:
https://susanavet2.skolverket.se/api/1.1/infos?vocational=true Länk till annan webbplats.
Tre specifika utbildningar:
https://susanavet2.skolverket.se/api/1.1/infos?id=i.fbr.288992.378977&i.fbr.289042.377588&i.fbr.53584.368612 Länk till annan webbplats.
Utbildningstillfällen som erbjuds på distans:
https://susanavet2.skolverket.se/api/1.1/events?distance=true Länk till annan webbplats.
Utbildningstillfällen vars titel innehåller ordet ”betong”:
https://susanavet2.skolverket.se/api/1.1/events?title=betong Länk till annan webbplats.
Utbildningstillfällen för alla utbildningar som är märkta som ”program”:
https://susanavet2.skolverket.se/api/1.1/events?configuration=program Länk till annan webbplats.
Vissa egenskapers tillåtna värden styrs av en värdemängd. Värdena i en värdemängd kan frågas med ett anrop till /reference följt av värdemängdens namn. I beskrivningen av ett attribut står då t.ex. ”Valid values obtained with /reference/educationLevel”. Exempel för configuration:
https://susanavet2.skolverket.se/api/1.1/reference/configuration Länk till annan webbplats.
EMIL-API:et
Ett anrop till någon av API-funktionerna skapar ett XHTML-dokument som innehåller länkar till de EMIL-dokument som finns lagrade i SUSA-navet. Om inga argument anges tas alla tillgängliga EMIL-dokument med. Normalt anger man ett eller flera filter för att få en mindre mängd dokument.
Anropa Susa-navets export
Exportfunktionen nås via HTTPS, filter och val anges som parametrar i URL:en. https://susanavet2.skolverket.se/SusaNavExport/EmilExporter?filter Länk till annan webbplats.
Använda filter
Det finns två typer av argument: filter som begränsar urvalet och val av vilken typ av dokument man vill få ut (anordnare, utbildning, utbildningstillfälle).
De flesta filter påverkar endast en typ av dokument. Vilken typ som påverkas framgår av filtrets prefix. Filter med prefixet “EI” filtrerar utbildningar (educationInfo-dokument), filter med prefixet “EE” filtrerar utbildningstillfällen (educationEvent-dokument). Det finns inga filter för utbildningsanordnare.
Filter som saknar prefix filtrerar alla typer av dokument. Filter anges som ett eller flera URL-argument.
Göra urval
Varje angivet filter kontrollerar vilka EMIL-dokument som uppfyller filtret. Om flera filter används är det snittet av dessa dokumentmängder som ges som resultat.
Om ett filter för utbildningstillfällen finns angivet kommer exporten alltid att leverera utbildningstillfällen, oavsett om det finns infofilter angivna. Det beror på att det bildas två mängder för olika typer av dokument (utbildningar och utbildningstillfällen). Då snittet av dessa mängder alltid skulle vara tomt, konverteras automatiskt utbildningarna till tillhörande utbildningstillfällen.
Som exempel kommer följande filterkombination att ge utbildningstillfällen då det är ett eventfilter (EE) angett. ?EELanguage=swe&EIAcademicType=högskoleutbildning
Om enbart filter som agerar på alla typer av dokument anges returneras alla typer.
Välja typ av dokument
Man kan välja vilken typ av dokument man vill få ut. Det finns tre val, ett för varje dokumenttyp: SelectEP (utbildningsanordnare), SelectEI (utbildning), SelectEE (utbildningstillfälle). Det går bara att välja typ av dokument om man har angett minst ett filter.
Som exempel kan man ange följande för att i nyss nämnda exempel få ut utbildningarna i stället för utbildningstillfällena. ?EELanguage=swe&EIAcademicType=högskoleutbildning&SelectEI
Man kan även välja att få med refererande dokument av andra typer genom att ange detta som värden på Select-parametern. Detta anges med koderna EP, EI, EE.
Om man som exempel vill få ut utbildningarna i exemplet ovan och respektive utbildningsanordnare för de utbildningarna anger man:
?EELanguage=swe&EIAcademicType=högskoleutbildning&SelectEI=EP
Det går att kombinera flera referenskoder. Följande hämtar alla utbildningstillfällen som är på svenska samt respektive utbildningsinformation och utbildningsanordnare:
?EELanguage=swe&SelectEE=EI,EP
Tillgängliga filter
Ej utgångna dokument
NotExpired används för att välja ut EMIL-dokument som inte har passerat utgångsdatum. Om det här filtret inte används så finns dokument som är upp till 30 dagar efter utgångsdatum med i resultatet.
Exempel (varning, ger många svar):
https://susanavet2.skolverket.se/SusaNavExport/EmilExporter?NotExpired Länk till annan webbplats.
Uppdaterade sedan datum
UpdatedSince filtrerar fram dokument som uppdaterats sedan ett visst datum. Argumentet på formatet yyyy-mm-dd (år-månad-dag).
Distansutbildning
EEFormOfStudy väljer ut utbildningstillfällen som ges på distans eller inte. Filtret tar argument distance eller normal.
Undervisningsspråk
EELanguage filtrerar utbildningstillfällen som ges på ett specifikt undervisningsspråk. Språkkoder skall specificeras enligt ISO 639-3 (treställiga språkkoder).
Kommun
EEMunicipality är ett filter som visar utbildningstillfällen i en eller flera kommuner. Om man vill ange flera koder separeras de med kommatecken. Områden anges med fyrsiffrig kod för kommun eller sexsiffrig kod för kommun och stadsdel/kommundel enligt SCB.
Akademisk typ
EIAcademicType filtrerar på typ av skolform. Giltiga värden finns specificerade i EMIL:s värdeförråd OrganisationForm. Aktuella möjliga värden ges av https://susanavet2.skolverket.se/api/1.1/reference/organisationForm Länk till annan webbplats.
Alla utbildningstillfällen
GetEvent listar alla utbildningstillfällen.
Exempel:
https://susanavet2.skolverket.se/SusaNavExport/EmilExporter?GetEvent Länk till annan webbplats.
Alla utbildningar
GetInfo listar alla utbildningar.
Exempel:
https://susanavet2.skolverket.se/SusaNavExport/EmilExporter?GetInfo Länk till annan webbplats.
Alla utbildningsanordnare
GetProvider listar alla utbildningsanordnare.
Exempel:
https://susanavet2.skolverket.se/SusaNavExport/EmilExporter?GetProvider Länk till annan webbplats.
Alla dokument
Filtret GetAll är ett filter som enbart är till för att kombinera med urvalsargument (SelectNN). Det hämtar alla dokument oavsett typ.
Ämnessök mot Susa-navet
I Susa-navet finns ett ämnesträd som kan användas för att söka utbildningar utifrån en ämneshierarki. På översta nivån finns cirka 20 ämnesområden. Varje område innehåller cirka 5-20 olika inriktningar, totalt ca 200 stycken.
En inriktning är egentligen bara en samling av utbildningskoder eller ämnen (studievägskoder, programkoder, kurskoder). Inriktningen ”Arkeologi” hör till ämnesområdet ”Kultur och humanistiska ämnen” och innehåller fem olika utbildningskoder/ämnen. Ett ämne är i praktiken en utbildningskod enligt någon ämnesförteckning, som SUN eller en leverantörsspecifik lista. Varje ämne i Susa-navet anger därför dels själva utbildningskoden, dels enligt vilken ämnesförteckning.
Matchning sker mot egenskapen utbildningskod (code) i EMIL:s huvudklass educationInfo.
I exemplet nedan använder folkhögskolorna kod 285 på sina utbildningar inom arkeologi, medan universiteten använder koden 587. Den som söker utbildningar inom Arkeologi kommer att få som svar alla som är märkta med någon av de fem koderna.
Ämnessök via API
För att hämta listan över alla ämnesområden, anropa detta API: https://susanavet2.skolverket.se/api/1.1/areas Länk till annan webbplats.
Av svaret framgår bl.a. ID, namn och en länk till ämnesområdets ingående inriktningar, t.ex.: http://susanavet2.skolverket.se/api/1.1/areas/9 Länk till annan webbplats.
Av svaret för ett områdes inriktningar framgår bl.a. ID, namn och en länk till inriktningens ingående ämnen, t.ex.: http://susanavet2.skolverket.se/api/1.1/directions/78 Länk till annan webbplats.
Av svaret framgår bl.a. ID, namn, typ (ägare av kodlistan), själva ämneskoden och en länk till definitionen av ämnet. Denna är inte så intressant.
I ett gränssnitt är ämnesområdena och inriktningarna intressanta att visa och låta användarna välja.
Om användarna tillåts välja ett helt ämnesområde för sökning blir anropet för att få utbildningar https://susanavet2.skolverket.se/api/1.1/infos?areaIds=9 Länk till annan webbplats.
för att få områdets utbildningstillfällen blir anropet istället https://susanavet2.skolverket.se/api/1.1/events?areaIds=9 Länk till annan webbplats.
Om användarna (bara) kan välja inriktningar blir anropet för att få utbildningar https://susanavet2.skolverket.se/api/1.1/infos?directionIds=78 Länk till annan webbplats.
för att få inriktningens utbildningstillfällen blir anropet https://susanavet2.skolverket.se/api/1.1/events?directionIds=78 Länk till annan webbplats.
Har användaren valt flera ämnesområden eller inriktningar skickas alla ID:n med komma mellan i anropen, directionIds=78,123,154.