OmaPTV esimerkit

Esimerkkejä rajapinnan käytöstä

Korvaa user_key -arvo abcd1234 DigiFinlandilta saamallasi API-avaimella.

Peruskutsut

Palvelut-rajapinta

Haetaan palveluita rajauksella SERVICE_CLASS = P5.5

curl -X POST https://rajapinnan_osoite/v1/services ^

-H ”Content-Type: application/json” ^

-H ”user_key: abcd1234” ^

-d ”{”mustCriterias”: [{”matchCriteria”: {”field”: ”SERVICE_CLASS”, ”value”: ”P5.5”, ”boost”: 0, ”operator”: ”AND”}}]}”

Organisaatiot-rajapinta

Haetaan organisaatioita, joissa esiintyy sana “koulu”.

curl -X POST https://rajapinnan_osoite/v1/organizations ^

-H ”Content-Type: application/json” ^

-H ”user_key: abcd1234” ^

-d ”{”searchString”: ”koulu”}”

Palvelukanavat-rajapinta

Haetaan palvelukanavia rajauksella AREA_TYPE = LimitedType

curl -X POST https://rajapinnan_osoite/v1/servicechannels ^

-H ”Content-Type: application/json” ^

-H ”user_key: abcd1234” ^

-d ”{”mustCriterias”: [{”matchCriteria”: {”field”: ”AREA_TYPE”, ”value”: ”LimitedType”}}]}”

Sivutus

Kyselyiden palauttaessa paljon vastauksia on usein tarpeellista hakea niitä sivuttamalla. Sivutuksessa määritellään size-parametrilla, montako vastausta on yhdellä sivulla. Page-parametrilla määritellään, monenneltako sivulta vastaukset palautetaan sivunumeroinnin alkaessa nollasta.

Haetaan vain yksi vastaus

Käytetään sivukokoa (size) 1.

curl -X POST https://rajapinnan_osoite/v1/organizations ^

-H ”Content-Type: application/json” ^

-H ”user_key: abcd1234” ^

-d ”{”searchString”: ”koulu”, ”size”: 1}”

Haetaan seuraava sivu

Sivukoko on 1 ja sivu (page) on 1. Sivujen numerointi alkaa nollasta.

curl -X POST https://rajapinnan_osoite/v1/organizations ^

-H ”Content-Type: application/json” ^

-H ”user_key: abcd1234” ^

-d ”{”searchString”: ”koulu”, ”size”: 1, ”page”: 1}”

Attribuuttien rajaus

Palvelun attribuuteista tarvitaan usein vain tietyt attribuutit, jolloin rajaus voidaan toteuttaa excludeServiceFields- ja includeServiceFields-parametreilla. Selkeyden vuoksi tästä lähtien esimerkeissä on vain requestin -d parametrin eli bodyn sisältö.

Kysely:

{ "includeServiceFields": ["id"], "shouldCriterias": [ [ { "matchCriteria": { "field": "SERVICE_CLASS", "value": "P3.1", "boost": 0, "operator": "OR" } } ] ] }

palauttaa vain attribuutin id arvotettuna, koska on käytetty includeServiceFields-parametria. Muiden attribuuttien arvo on joko null tai tyhjä lista riippuen attribuutin tyypistä.

[
{
”id”: ”bfc46496-fa78-450e-81e9-6fea1b854b35”,
”type”: null,
”fundingType”: null,
”serviceChargeType”: null,
”areaType”: null,
”languages”: [],
”serviceClasses”: [],
”ontologyTerms”: [],
”targetGroups”: [],
”lifeEvents”: [],
”industrialClasses”: [],
”legislation”: [],
”requirements”: [],
”organizations”: [],
”serviceDescriptions”: [],
”keywords”: [],
”serviceNames”: [],
”areas”: [],
”generalDescriptionId”: null,
”generalDescription”: null,
”serviceChannels”: null,
”serviceChannelLinks”: []
},………

Attribuutteja voidaan rajoittaa myös luettelemalla poistettavat attribuutit. Tämä toteutetaan excludeServiceFields-parametrilla:

{
"excludeServiceFields":
  ["serviceChargeType","languages","serviceClasses","ontologyTerms"],
"shouldCriterias": [
    [
      {
      "matchCriteria":
      {
      "field": "SERVICE_CLASS",
      "value": "P3.1",
      "boost": 0,
      "operator": "OR"
      }
      }
    ]
  ]
}

Tämä palauttaa rakenteen, missä poistettavat attribuutit eivät sisällä arvoa vaan ne on tyypistä riippuen joko null tai tyhjä lista:

[
  {
    "id": "e3ceacf2-914b-4dcd-9605-b27a28f862c5",
    "type": "Service",
    "fundingType": "PubliclyFunded",
    "serviceChargeType": null,
    "areaType": "LimitedType",
    "languages": [],
    "serviceClasses": [],
    "ontologyTerms": [],
    "targetGroups": [
      {
        "code": "KR1",
        "boost": null,
        "ontologyType": "ptvkohderyhmat",
        "uri": "http://urn.fi/URN:NBN:fi:au:ptvl:v2001",
        "newUri": "http://uri.suomi.fi/codelist/ptv/ptvkohderyhmat/code/KR1",
        "parentId": null,
        "parentUri": null,
        "newParentUri": null,
        "name": [
          {
            "language": "sv",
            "type": null,
            "value": "Medborgare"
          },
          {
            "language": "en",
            "type": null,
            "value": "Citizens"
          },
          {
            "language": "fi",
            "type": null,
            "value": "Kansalaiset"
          }
        ]
      }
    ],…

Tarkemmat esimerkit

includeServiceFields, filterCriterias, termCriteria

Tulokseen halutaan palveluiden id ja fundingType.

Tämä tehdään includeServiceFields määrityksellä:

"includeServiceFields": ["id","fundingType"]

Valitaan palvelut, joiden funding type on “PubliclyFunded”

Rajaava haku tehdään filterCriterias määrityksellä, jolloin mukaan tulee vain ne palvelut, jotka täyttävät ehdot. Tässä tapauksessa käytetään termCriteria määritystä, joka tarkoittaa, että kentän fieldarvon on täsmättävä annetun arvon value kanssa.

{
  "includeServiceFields": ["id","fundingType"],
  "filterCriterias": [
    [
      {
        "termCriteria": {
          "field": "FUNDING_TYPE",
          "value": "PubliclyFunded"
        }
      }
    ]
  ]
}

mahdollisia field kentän arvoja ovat: SERVICE_CLASS, TARGET_GROUP, LIFE_EVENT, ONTOLOGY_TERM, ID, AREA_TYPE, AREA_WELL_BEING_CODE, AREA_CODE, AREA, SERVICE_CHARGE_TYPE, FUNDING_TYPE, SERVICE_TYPE, SUB_AREA_TYPE, LANGUAGE, ORGANIZATION_ID, SERVICE_NAME

mustNotCriteries

Tulokseen halutaan palveluiden id ja fundingType.

Tämä tehdään includeServiceFields määrityksellä:

"includeServiceFields": ["id","fundingType"]

Valitaan palvelut, joiden funding type ei ole “PubliclyFunded”

Rajaava haku tehdään mustNotCriterias määrityksellä, jolloin valitaan palveluita, joissa annettu ehto ei täyty. Tässä tapauksessa käytetään termCriteria määritystä, joka tarkoittaa, että kentän fieldarvon on täsmättävä annetun arvon value kanssa.

{
  "includeServiceFields": ["id","fundingType"],
  "mustNotCriterias": [
      {
        "termCriteria": {
          "field": "FUNDING_TYPE",
          "value": "PubliclyFunded"
        }
      }
    ]
}

fuzzyCriteria

Tulokseen halutaan palveluiden id ja fundingType.

Tämä tehdään includeServiceFields määrityksellä:

"includeServiceFields": ["id","fundingType"]

Valitaan palvelut, joiden funding type on lähellä sanaa “PublicFunded”

Rajaava haku tehdään mustCriterias määrityksellä, jolloin valitaan palveluita, joissa annettu ehto täytyy. Tässä tapauksessa käytetään fuzzyCriteria määritystä, joka tarkoittaa, että kentän fieldarvon on oltava lähellä arvon value kanssa.

{
  "includeServiceFields": ["id","fundingType"],
  "mustCriterias": [
      {
        "fuzzyCriteria": {
          "field": "FUNDING_TYPE",
          "value": "PublicFunded"
        }
      }
    ]
}

wildcardCriteria

Tulokseen halutaan palveluiden id ja fundingType.

Tämä tehdään includeServiceFields määrityksellä:

"includeServiceFields": ["id","fundingType"]

Valitaan palvelut, joiden funding type on sopii hakuun “Public*”

Rajaava haku tehdään mustCriterias määrityksellä, jolloin valitaan palveluita, joissa annettu ehto täytyy. Tässä tapauksessa käytetään wildcardCriteria määritystä, joka tarkoittaa, että kentän fieldarvon on täsmättävä value kanssa, jossa käytetään jokerimerkkiä (*)

{
  "includeServiceFields": ["id","fundingType"],
  "mustCriterias": [
      {
        "wildcardCriteria": {
          "field": "FUNDING_TYPE",
          "value": "Public*"
        }
      }
    ]
}

Ehtojen yhdistäminen, wildcardCriteria, termCriteria

Valitaan palvelut, joiden funding type sopii hakuun “Public*” ja jotka ovat saatavilla maanlaajuisesti Nationwide.

Toisena rajauksena mustCriterias sisällä käytetään termCriteria määritystä, jossa area type rajoitetaan arvoon Nationwide.

{
  "mustCriterias": [
      {
        "wildcardCriteria": {
          "field": "FUNDING_TYPE",
          "value": "Public*"
        }
      },
      {
        "termCriteria": {
          "field": "AREA_TYPE",
          "value": "Nationwide"
        }
      }
    ]
}

fixedServices

Tulokseen halutaan mukaan palvelut, joiden id on tiedossa. Käytetään siihen fixedServices määritystä, jossa annetaan palvelun id ja order. Id on palvelun tunnus ja order on se, millä paikalla vastauksessa palvelun pitää olla.

{
"fixedServices": [
	{
  "id": "527143c5-352e-4724-8096-96f445ca92d6",
  "order": 1
  },
  {
  "id": "747d1a97-6d7e-485e-9a53-5db85138688b",
  "order": 2
  }
]
}

Esimerkkejä rajapinnan käytöstä

Peruskutsut

Palvelut-rajapinta

Organisaatiot-rajapinta

Palvelukanavat-rajapinta

Sivutus

Haetaan vain yksi vastaus

Haetaan seuraava sivu

Attribuuttien rajaus

Tarkemmat esimerkit

includeServiceFields, filterCriterias, termCriteria

mustNotCriteries

fuzzyCriteria

wildcardCriteria

Ehtojen yhdistäminen, wildcardCriteria, termCriteria

fixedServices

Liity uutiskirjeen tilaajaksi