AuroraAI-palvelusuosittelijat mahdollistavat annettujen suositusten rajaamisen eri metatietojen perusteella. Tässä artikkelissa esitellään miten uusia rajauskenttiä hyödynnetään rajapintakutsuissa.
Aluerajaukset
Aiemmin suosittelukutsuissa on ollut mahdollista rajata tuloksia käyttäen yhtä kuntakoodia:
"municipality_code": "091"
Kuntakoodeja on mahdollista antaa useampia. Lisäksi voidaan antaa listat maakunnista ja sairaanhoitopiireistä, joita käytetään palautettavien palvelujen rajaamiseen vastaavasti kuin kuntakoodeja. Lisäksi voidaan antaa tieto siitä, halutaanko tuloksiin valtakunnallisia palveluita. Rajapintakutsussa nämä aluerajaukset näyttävät tältä:
"service_filters": {
"include_national_services": false,
"municipality_codes": [
"091",
"638"
],
"region_codes": [
"02",
"19"
],
"hospital_district_codes": [
"04",
"12"
],
"service_classes": [
"http://uri.suomi.fi/codelist/ptv/ptvserclass2/code/P1.2",
"http://uri.suomi.fi/codelist/ptv/ptvserclass2/code/P25.3"
]
},
Aluerajaukset on siis jatkossa ryhmitelty yhdessä palveluluokkien kanssa service_filters-otsikon alle. Kentät eivät ole pakollisia eli minimimuutoksena rajapintakutsua päivitettäessä voidaan siirtää haluttu kuntakoodi vanhasta service_filter-kentästä uuteen service_filters-listaan. Lisätoimintoja voidaan ottaa käyttöön tarpeen mukaan.
Käytetyt numeromuotoiset koodit kunnille, maakunnille ja sairaanhoitopiireille löydät Yhteentoimivuusalustalta:
Kuntakoodit 2022: https://koodistot.suomi.fi/codescheme;registryCode=jhs;schemeCode=kunta_1_20220101
Maakuntakoodit 2022: https://koodistot.suomi.fi/codescheme;registryCode=jhs;schemeCode=maakunta_1_20220101
Sairaanhoitopiirien koodit 2022: https://koodistot.suomi.fi/codescheme;registryCode=jhs;schemeCode=sairaanhoitop_1_20220101
Palveluluokkarajaukset
Aluerajausten lisäksi tuloksia voidaan rajata hyödyntäen julkisten palvelujen palveluluokkia. Rajapinta ottaa vastaan listan halutuista pää- ja alaluokista ja palauttaa vain kyseisiin palveluluokkiin kuuluvia palveluita. Palveluluokat rajataan listalla URI-koodeja, jotka löytyvät Yhteentoimivuusalustalta.
Julkisten palvelujen luokitus: https://koodistot.suomi.fi/codescheme;registryCode=ptv;schemeCode=ptvserclass2
Palvelukokonaisuudet
Palvelukokonaisuus on Suomi.fi-palvelutietovarannossa hallinnoitava vapaavalintainen kokoelma palveluita. Suosittelujen tuloksia voidaan rajata käyttäen rajauksena haluttua palvelukokonaisuutta tai -kokonaisuuksia. Tällöin palvelukokonaisuus muodostaa eräänlaisen whitelistin, josta varsinainen suosittelu (3x10d tai vapaateksti) tehdään. Tämä mahdollistaa suosittelun tuloksien tiukemman rajaamisen palvelukohtaisesti.
Kokonaisuuksia hallinnoidaan Palvelutietovarannossa, jonne tunnukset haetaan Suomi.fi-palveluhallinnasta. Palvelukokonaisuudet eivät muuta alkuperäisiä palvelukuvauksia ja ne voivat sisältää vapaasti eri organisaatioiden palveluja.
Rajapintakutsussa palvelukokonaisuutta käytetään vastaavasti kuin muitakin rajauskenttiä. Niitä voidaan myös tarpeen mukaan yhdistää muihin rajauksiin. Esimerkkikutsussa (alla) tekstihaku on rajattu koskemaan tiettyä palvelukokonaisuutta ja lisäksi on sallittu kansalliset palvelut.
{
"search_text": "nuorten työttömyys",
"service_filters": {
"include_national_services": true,
"service_collections": [
"16f7b099-3ab2-49c8-a646-9b029de85f20"
]
},
"limit": 5
}