Mallitoteutuksen AuroraAI-palvelusuosittelijat mahdollistavat annettujen suositusten rajaamisen eri metatietojen perusteella. Tässä artikkelissa esitellään miten rajauskenttiä hyödynnetään rajapintakutsuissa. 

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


Alla esimerkki tekstihaun rajaamisesta "Nuorten palvelut"-palveluluokkaan, rajaamiseen käytetty URI-koodi on noudettavissa yllä olevasta luokitussivulta (URI-kenttä).

{
  "search_text": "harrastustoimintaa nuorille",
  "service_filters": {
    "include_national_services": true,
	"service_classes":["http://uri.suomi.fi/codelist/ptv/ptvserclass2/code/P28"]     ]
  },
  "limit": 5
}


Palvelukokonaisuudet

Palvelukokonaisuus on Suomi.fi-palvelutietovarannossa hallinnoitava vapaavalintainen kokoelma palveluita. Palvelukokonaisuuksien alle voi niputtaa samaan teemaan liittyviä palveluita ja asiointikanavia omasta tai muiden organisaatioista. Palvelukokonaisuutta hyödynnetään esim. portaaleissa pikavalikoiden käytössä tai teemasivujen sisällön hallinnassa  "tässä on kaikki teemaan NN liittyvät palvelut".

Palvelukokonaisuuksia voi hyödyntää myös AuroraAI-palvelusuosittelussa. Suosittelujen tuloksia voidaan rajata käyttäen rajauksena haluttua palvelukokonaisuutta tai -kokonaisuuksia. Tällöin palvelukokonaisuus muodostaa eräänlaisen whitelistin (etukäteen määritettyjen sopivien palveluiden listan), josta varsinainen suosittelu (3x10d tai vapaateksti) tehdään. Palvelukokonaisuuden käyttö PTV:ssä mahdollistaa suosittelun tuloksien tiukemman rajaamisen omavalintaisiin palveluihin. Palvelukokonaisuuksien hallinta edellyttää  

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. Huomioitavaa: palvelukokonaisuus (kuten myös PTV:n palvelukuvaukset) tulee olla tilassa Julkaistu, jotta se toimii AuroraAI-suositteluissa. 

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
}

Huom: PTV voi luoda palvelukokonaisuudelle useamman tunnisteen. Rajaus toimii kiinteällä PTV-tunnisteella.

Aluerajaukset

Suosittelujen tulokset voidaan aluerajauksia hyödyntäen rajata sisältämään vain tietyllä alueella saatavilla olevia palveluita. Aluerajauksia voidaan yhdistellä toisiinsa esimerkiksi hakemalla palveluita tietystä kunnasta ja tietystä maakunnasta. Poikkeuksen muodostaa only_national_services -kenttä, jota ei voi yhdistää muihin aluerajauksiin. Sillä voidaan hakea vain kansallisesti saatavilla olevia palveluita, jos esimerkiksi ei tiedetä käyttäjän sijaintia. Aluerajausten yhdistelmät on kuvattu tarkemmin taulukoissa alla. Rajapinnassa kentät näyttävät seuraavilta:

 "service_filters": {
    "only_national_services": false,
    "include_national_services": true,
    "municipality_codes": [
      "091",
      "638"
    ],
    "region_codes": [
      "02",
      "19"
    ],
    "hospital_district_codes": [
      "04",
      "12"
    ]
   }


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


Aluerajausten yhdistelmät

Taulukossa on esitelty millaisia tuloksia suosittelijat antavat aluerajauksen ja muiden rajausten yhdistelmillä
(tässä esimerkissä palveluluokka, kohderyhmät ja palvelukokonaisuudet toimivat vastaavasti).

caseinclude_nationalmunicipality_codesservice_classTulos

1

ei annettu

ei annettu

ei annettu

Suositteluja kaikista palveluista

2

false

ei annettu

ei annettu

Kaikista ei-valtakunnallisista

3

true

ei annettu

ei annettu

Suositteluja kaikista palveluista

4

false

[1,2,3] 

ei annettu

Suositteluja kunnista 1,2,3

5

true

[1,2,3] 

ei annettu

Valtakunnallisista ja kunnista 1,2,3

6

ei annettu

[1,2,3] 

ei annettu

Valtakunnallisista ja kunnista 1,2,3

7

ei annettu

ei annettu

P1.2

kaikista kunnista ja valtakunnallisista, mutta vain luokasta P1.2

8

true

ei annettu

P1.2

kaikista kunnista ja valtakunnallisista, mutta vain luokasta P1.2

9

false

ei annettu

P1.2

Kaikista ei-valtakunnallisista luokassa P1.2

10

false

[1,2,3] 

P1.2

Kuntien 1,2,3 palvelut luokassa P1.2


Vain valtakunnallisiin palveluihin rajaaminen 

Suosittelija voidaan rajata pelkkiin valtakunnallisiin palveluihin, jolloin muut aluerajaukset eivät ole käytettävissä.
Alla on eritelty Only_national_services -kentän yhdistäminen muihin rajauksiin. Huomaa virheet, jos kenttää yritetään yhdistää muihin aluerajauksiin. 

Only_national_servicesToinen annettu rajausTulos
truemunicipality_codes400 virhe

only_national_services selected. municipality_codes not allowed.

trueregion_codes

400 virhe
only_national_services selected. region_codes not allowed.

truehospital_district_codes400 virhe
only_national_services selected. hospital_district_codes not allowed.
truewellbeing_service_county_codes400 virhe
only_national_services selected. wellbeing_service_county_codes not allowed.
trueinclude_national_services400 virhe
only_national_services selected. include_national_services not allowed.
trueservice_classesValtakunnallisia palveluita annetuista palveluluokista
truetarget_groupsValtakunnallisia palveluita, joilla annettu kohderyhmätieto
trueservice_collectionsValtakunnallisiapalveluita annetuista palvelukokonaisuuksista
truefunding_typeValtakunnallisia palveluita, joilla annettu rahoitustyyppi