Grynos Ilmoapix v1 avoin rajapinta

Päiväys

Tekijä

Versio

Muutoksen kuvaus

25.08.17

Juhani

1.0.0 beta

Rajapinta julkaistu testikäyttöön.

13.09.17

Juhani

1.0.5

Opettajan nimi poistettu käytöstä.

Lisätty parametrit desc ja changed

17.09.17

Juhani

 

- Lisätty hinta ja lisähinta kurssi-objektiin. Poistettu allcount kurssi-objektilta.

- muutettu kurssi-objektin location-kentän sisältöä.

- lisätty tämä rajapinnan kuvausdokumentti HTML-muodossa /docs-urlilla kasottavaksi

20.09.17

Juhani

 

- Lisätty opetuspaikkahaku

24.11.17

Juhani

1.0.9

- muutettu kurssi-objektin location-merkkijono omaksi locations-objektilistaksi

- lisätty aineryhmäpolkuhaku

- lisätty aineryhmään tkid

12.12.17

Juhani

1.0.10

- lisätty kurssikyselyihin format-parametri

13.12.17

Juhani

 

- lisätty kurssi objektiin opetuspaikat

09.02.18

Juhani

1.0.11

- Lisätty kurssihaun palauttat objektit dokumenttiin

- kurssihaun palauttaman course-objektin additionalPrice muutettu muotoon priceMaterial

- kurssin tarkempien tietojen courseinfo-objektin first_session_date muutettu muotoon firstSession

- kurssin tarkempien tietojen courseinfo-ojektin las_session_date muutettu muotoon lastSession

- kurssin tarkempien tietojen courseinfo-objektin InternetEnrollment muutettu muotoon internetEnrollment

- rajapina-avain käyttöön

- kurssihakuun lisätty parametrit olec ja otea

17.04.18

Juhani

1.0.12

- Lisätty kurssin tarkempien tietojen courseinfo-objektin hakuun ses-parametri käyttöön.

- Lisätty kurssin tarkempiin tietoihin parametrien kuvaus

- poistettu tästä dokumentista viittaukset rajapinnan koko URLiin. Host ja ohjelman nimiosaan viitataan merkkijonolla ”...” .

- rajapinta-avaimen voi antaa pyynnön header-osassa (suositeltu tapa).

07.05.18

Juhani

1.0.13

Kurssin tarkemmat tiedot > Haun palauttamat objektit:

- kurssi-objektin nimi korjattu dokumentissa 'course' > 'courselist'

- kurssi-objektin atribuutin nimi korjattu dokumentissa 'additionalprice' > 'priceMaterial'

- kurssi-objektin attribuutti 'firstSessionWeekdate' poistettu dokumentoinnista

- kurssi-objektin atribuutin nimi nuutettu 'firstRegisterDate' > 'firstEnrollmentDate'

- kurssi-objektin atribuutin nimi nuutettu 'lastRegisterDate' > 'lastEnrollmentDate'

- kurssi-objektin atribuutin nimi nuutettu 'minimumStudentCount' > 'minStudentCount'      

- kurssi-objektin atribuutin nimi nuutettu 'maximumStudentCount' > 'maxStudentCount'

- kurssi-objektiin lisätty puuttuneet rajapinnan palauttamat attribuutit           

           

Kurssihaun palauttamat objektit:

- Kurssi-objektiin lisätty 'teacher'-attribuutti

 

- Lisätty Kurssilajihaku

- Lisätty Opistolistaus

11.05.18

Juhani

1.0.14

- Lisätty kurssihakukyselyyn parametriksi sip (kertalippuilmoittautuminen)

23.05.18

Mikko

1.0.15

- Lisätty kurssihakuun parametri ’eve’: Tapahtuma haku.

- Lisätty kurssihakuun parametri ’cou’: Kurssit haku. Sulkee hausta pois ”Luennot” ja ”Tapahtumat”.

25.05.18

Juhani

1.0.16

- Käyttäjätunnuksen ja salasanan pyyntö sähköpostiosoite muutettu

 

Kurssihaun palauttamat objektit:

- opetuspaikka-objektista poistettu 'path' ja 'address' ja lisätty 'id'.

03.08.18

Mikko

1.0.17

- Lisätty oma kappale virhe viesteille

07.09.18

Juhani

 

- muokattu virheviesti-osiota

- kurssihaku-parametri 'dep' poistettu

- lisätty kurssihakuun parametrit 'offset' ja 'img'

- kurssihaku palauttaa opetuspaikasta nimitiedon

- lisätty pyyntö 'Opetuspaikan varaustiedon haku'

20.09.18

Juhani

 

- poistettu Kurssilajihaku-osio tästä dokumentista ja korvattu Valintalistahaku-osiolla

- lisätty Kurssityyppi, Koulutus, Työtilanne -pyynnöt Valintalistahakuun

03.10.18

Mikko

 

- Lisätty kurssihakuun parametri ’cids’: Kurssi ID listan palautus.

19.12.18

Juhani

 

Lisätty opetuspaikkahakuun

- hakuehdot type, status

- attribuutit parentName, companyID ja ownerID

10.01.19

Juhani

 

Lisätty opetuskielihaku

15.01.19

Juhani

 

Lisätty kurssihakuun parametri 'order'

17.01.19

Juhani

 

- Lisätty kurssihakuun parametri 'uni'

- kurssihaku palauttaa tiedon onko kurssi Verkkoluento, Verkko-opetus vai Avoin yliopisto

17.02.19

Juhani

 

- Lisätty kurssihakuun parametrit 'future', 'seats', 'lnk' ja 'att'.

- Lisätty kurssikoodilla hakuun parametrit 'lnk' ja 'att'.

- Lisätty kurssihaku ja kurssin tarkempien tietojan palautus objekteihin useita arvoja

07.06.19

Juhani

 

- Opetuspaikka pyynnnöstä poistettu parametri ’type

- Lisätty kurssihakuun 'kw' ja 'in_progress'

- Lisätty kurssin tarkempien tietojen hakuun 'lnk' ja 'att'

- Opistolistaukseen parametrisaddress’ ja ’contact

08.06.19

Juhani

 

Kurssihaku palauttaa ’enrollmentNotPossible’ lipun

26.06.19

Juhani

 

Kurssihaun palauttaa ’enrollmentNotPossible’ muutettu muotoon ’enrollmentPossible’ ja logiikka käännetty

23.07.19

Juhani

 

Kurssiobjektille lisätty ’payable’ attribuutti

Kurssiobjektille lisätty ’enrollmentData’ objekti

06.08.19

Juhani

 

Lisätty opistolistaukseen opiston osoite, kontakti ja aukiolo -atribuutit ja listaobjektien kuvaukset

07.08.19

Juhani

 

Lisätty kontaktityypille ’name’. Aiemmin ’type’, sisälsi tekstidataa, nyt datan tyypiksi muutettu Int.

03.01.20

Juhani

 

Muokattu tätä dokumentia.

Johdanto

Ilmoapix on ilmainen ja julkinen rajapinta kurssitietoihin.

Saatavilla on myös ilmoittautumisrajapinta, josta voi lisätietoja kysyä sähköpostitse  api@grynos.com.

Käyttöehdot

Avoimen rajapinnan käyttö on ilmaista niin kaupallisessa sekä ei-kaupallisessa tarkoituksessa. Yleisiä käyttörajoituksia ei ole, mutta Grynos Oy varaa oikeuden estää kohtuutonta rasitusta aiheuttavien osapuolten pääsyn rajapintaan.

Asiakaskäyttöliittymä

Asiakkaan tietojen hallinta on selaimella katsottavissa.

Tietojen hallintaan tarvitaan käyttäjätunnus ja salasana, jotka saa Grynos Oy:ltä lähettämällä pyynnön sähköpostiosoitteeseen api@grynos.com.

Asiakas määrittää uudelleenohjausosoitteen, johon rajapinnan pyynnön vastaus aina palautetaan. Lisäksi asiakas voi muuttaa käyttäjätunnusta ja salasanaansa asiakaskäyttöliittymään.

Asiakaskäyttöliittymässä näkyy luotu rajapinta-avain (Api key), jota käytetään pyyntöjen yhteydessä.

 

Rajapinnan kuvaus

Rajapinta käyttää REST-arkkitehtuuria. Rajapintaan tehdään HTTP GET pyyntö, jonka parametrit välitetään osoitteen query-osassa. Pyyntöön vastataan xml tai json muodossa, jonka asiakasohjelma määrittää pyynnön header-osassa 'Accept' avaimella tai parametrillä format, jonka arvo voi olla 'xml' tai 'json'. Header-osan ‘Accept’ avaimen arvo voi olla 'application/xml' tai 'application/json'.

Merkistönä käytetään utf-8. Rajapinta palauttaa rajoittamattoman määrän tuloksia, mutta sivutusta voi hallita parametreilla limit ja offset.

Rajapinta-avain 

Jokaiseen pyyntöön on lisättävä mukaan rajapinta-avain (apikey), joka toimii pyyntöä suorittavan asiakasliittymän tunnisteena. Rajapinta-avain on annettava pyynnön header-osa, jossa 'apikey' avaimessa rajapinta-avaimen arvo.

Pyynnön rakenne

Pyynnön hakuehdot asetetaan HTTP-polkuun. Kyselyn parametrit yhdistetään JA-konjunktiolla, jolloin tulokseen sisältyvät tietueet, jotka täsmäävät kaikkiin hakuehtoihin. Pilkuilla erotelluissa parametrien arvoissa käytetään TAI-konjunktiota.

Pyyntöjen parametrien kuvauksessa voi olla viittaus päivämäärään tai aikaan esim. 'vvkkpp', tällöin esiintyvillä merkeillä tarkoitetaan seuraavaa  vv = vuosi kahdella numerolla, kk = kuukausi kahdella numerolla, pp = päivämäärä kahdella numerolla, hh = tunti kahdella numerolla, mm = minuutti kahdella numerolla ja ss = sekuntti kahdella numerolla.

Pyynnön rakenne on seuraavanlainen:

... /v1/[pyynnön parametrit]

Sisältöjen kielet ja kielikoodit

Sisällöt tuotetaan oletusarvoisesti suomeksi, muut kielivaihtoehdot ovat Ruotsi ja englanti.

Yleiset parametrit

Parametri

Sallitut arvot

Kuvaus

Oletus

lang

fi, en, sv

Palautettavan tietueen kieliversio

fi

limit

numero

Rajoittaa tulosten määrää per sivu

kaikki

Offset

numero

Monennesta sivusta tulos aloitetaan

0

Hakuehdot ja järjestäminen

Useita hakuehtoja käytettäessä tulos sisältää ne tietueet, jotka löytyvät kaikilla hakuehdoilla. Yksittäiseen hakuehtoon voi lisätä useita arvoja pilkulla eroteltuna, jolloin vähintään yhden arvon on täsmättävä.

Rajapinnan testauspyyntö

Rajapintaan voi suorittaa testauspyynnön, jolloin palautetaan rajapinnan versionumero sekä palvelimen kellonaika.

Testauspyyntö (ei tarvitse rajapinta-avainta):

... /v1/ping

 

Vastaus palauttaa esimerkin mukaisen JSON objektin:

{

    "message": "It's alive!",

    "version": "v1.0.76 (3.1.2020)",

    "timestamp": "Fri Jan 03 16:35:57 EET 2020"

}

 

Virheviestit

Virheen sattuessa, palautusviestit sisältävät muuttujan ’error’. Joissain tilanteissa rajapinta saattaa palauttaa onnistuneesta pyynnöstä myös muuttujan 'error', mutta arvona on 'null'.

Jos pyyntö oli virheellinen rajapinta palauttaa HTTP virheen (404) Not Found, (401) Unauthorized tai (503) Service Unavailable.

Jos pyyntö oli oikein, mutta rajapinta ei pystynyt toteuttamaan pyyntöä, virheviesti palautetaan osana paluuviestiä.

Mallivastaus virheelliseen pyyntöön:

{
  "error": {
    "error_code": 2,
    "message": "No permission, wrong apikey.",
    "http_status_code": 401
  }
}

Mallivastaus onnistuneeseen pyyntöön (OK):

{
  "id": 123456,
  "coursecode": "X181234",   
 
}

Rajapinnan kuvausdokumentti

Rajapinnan kuvausdokumentin HTML muodossa saa auki selaimella pyynnöllä (ei tarvitse rajapinta-avainta):

... /v1/docs

 

Opistolistaus

Rajapinnassa käytetään useissa pyynnöissä opiston id numeroa. Käytettävissä olevat opistot ja id:t saa haettua pyynnöllä

... /v1/company/all

Tässä dokumentissa olevissa pyyntöesimerkeissä opisto id:n paikka URLissa esitetään '[opistoid]'-merkkijonolla.

Parametri

Tyyppi

Kuvaus

lang

String

Kieli. Voi sisältää vain yhden arvon.

format

String

Pyynnön vastauksen tyyppi.

address

Int

Sisällytetäänkö hakutulokseen osoitetiedot (vain arvolla 1).

contact

Int

Sisällytetäänkö hakutulokseen kontaktitiedot (vain arvolla 1).

opening

Int

Sisällytetäänkö hakutulokseen opisto avoinna -tiedot (vain arvolla 1).

 

Haku palauttaa opistosta seuraavat tiedot:

Opistolista (companylist)

Atribuutti

Kuvaus

id

Opiston id

name

Opiston nimi

shortName

Opiston lyhytnimi

nameOfficial

Opiston virallinen nimi

discountAllowed

Onko mahdollista saada alennuksia (jos määritelty opistolla)

addressList

Osoitelistaus osoitetyypeittäin

contactList

Kontaktilistaus kontaktityypeittäin

openingList

Opiston aukioloajat

Opiston osoite-objekti (addressList)

Atribuutti

Kuvaus

streetAddress

Katuosoite

postalCode

Postinumero

city

Kaupunki

type

Osoitetyyppi

cryptedAddress

Katuosoite + kaupunki kryptattuna. Kryptausavain Grynos Keys -ohjelmasta. Omassa käytössä mm. kartan URL -parametrinä.

Opiston kontakti-objekti (contactList)

Atribuutti

Kuvaus

contact

Katuosoite

type

Kontaktityyppi id

name

Kontaktityyppi nimi

Opiston aukiolo-objekti (openingList)

Atribuutti

Kuvaus

beginTime

Alkukellonaika

endTime

Loppukellonaika

validBegin

Alkupäivämäärä

validEnd

Loppupäivämäärä

WeekDayName

Viikonpäivän lyhytnimi

freeText

Vapaateksti

 

 

Kurssihaku

Kutsun osoitteen muoto on seuraava:

... /v1/course/search?[parametrit]

 

Parametrit erotellaan toisistaan & -merkillä.

Kaikki kentät hyväksyvät monta valintaa kerralla pilkuin erotettuna listana (foo,bar,cur), ellei erikseen mainita. Osasta hakuehdoista tarkempi kuvaus mahdollisista arvoista alempana.

Parametri

Tyyppi

Kuvaus

txt

String

Mikä tahansa teksti, joka voi löytyä kurssin nimesta, kuvauksesta yms.

com

String

Opiston id numero.

cgt

Int

Aineryhmän id numero. Voi sisältää vain yhden arvon.

str

String

Opetuspaikan id numero.

tar

String

Kohderyhmän id numero.

tla

String

Opetuskielen id numero.

tim

String

Aikarajaus. Vähintään yksi kurssin opetuskerroista järjestetään kyseisenä aikana. Voi sisältää vain yhden arvon.

dat

String

Päivärajaus. Vähintään yksi kurssin opetuskerroista järjestetään kyseisenä päivänä. Voi sisältää vain yhden arvon.

wkd

Int

Viikonpäivä. Vähintään yksi kurssin opetuskerroista järjestetään kyseisenä viikonpäivänä.

lec

String

Luennot (vain arvolla 1). Voi sisältää vain yhden arvon.

eve

Int

Tapahtumat  (vain arvolla 1). Voi sisältää vain yhden arvon.

cou

Int

Kurssit (vain arvolla 1). Sulkee hausta pois ”Luennot” ja ”Tapahtumat”. Voi sisältää vain yhden arvon.

lang

String

Kieli. Voi sisältää vain yhden arvon.

ses

Int

Palauta myös opetuskerrat hakutuloksessa (vain arvolla 1). Voi sisältää vain yhden arvon.

desc

Int

Palauta kuvaustekstit hakutuloksessa (vain arvolla 1). Voi sisältää vain yhden arvon.

changed

Int

Palauta muuttuneet kurssit hakutuloksessa (vain arvolla 1). Voi sisältää vain yhden arvon. HUOM! Kun kysely sisältää 'changed'-parametrin, käytetään parametrejä 'dat' ja 'tim' määrittelemään aikaraja, jonka jälkeen muuttuneet kurssit palautetaan.

format

String

Pyynnön vastauksen tyyppi. Voi sisältää vain yhden arvon.

olec

Int

Verkkoluennot (vain arvolla 1).

otea

Int

Verkko-opetus (vain arvolla 1).

sip

Int

Kertalippuilmoittautumispaikkoja määritelty (vain arvolla 1). Voi sisältää vain yhden arvon.

offset

Int

Monennestako tietueesta eteenpäin tuodaan rivejä haussa. Voi sisältää vain yhden arvon.

limit

Int

Montako tietuetta tuodaan haussa. Voi sisältää vain yhden arvon.

img

Int

Sisällytetäänkö hakutulokseen mahdollinen kurssiin liitetyn kuvan URL  (vain arvolla 1). Voi sisältää vain yhden arvon.

cids

Int

Palauttaa hakutuloksen kaikkien kurssin ID:t muuttujassa ’resultCRIDs’ (vain arvolla 1). Palauttaa kaikki pyynnön tuottamat kurssi ID:t, vaikka pyyntöön olisi määritelty 'limit' -parametri.

order

String

Järjestetään hakutulos. Voi sisältää arvot 1, -1, 2, -2, ,3, -3.

uni

Int

Avoin yliopisto (vain arvolla 1)

future

Int

Vain tulevat kurssit. Voi sisältää vain yhden arvon.

seats

Int

Vain kurssit, joilla tilaa. Voi sisältää vain yhden arvon.

lnk

Int

Sisällytetäänkö hakutulokseen kurssin linkki-lista (vain arvolla 1). Voi sisältää vain yhden arvon.

att

Int

Sisällytetäänkö hakutulokseen kurssin liitetiedosto urlit (vain arvolla 1). Voi sisältää vain yhden arvon.

kw

Int

Sisällytetäänkö hakutulokseen kurssin avainsanat (vain arvolla 1). Voi sisältää vain yhden arvon.

in_progress

Int

Näytä vain alkaneet kurssit, joihin voi ilmoittautua (vain arvolla 1). Voi sisältää vain yhden arvon.

Parametrien arvojoukot

Aikarajaus [tim]

Arvo

Selitys

hhmmss

Jos parametrinä yksi aika-arvo, tarkoittaa se alkukellon aikaa

hhmmss_hhmmss

Jos parametrinä kaksi aika-arvoa, erotellaan ajat toisistaa alaviivalla ”_”. Tällöin ensin annetaan alkuaika ja jälkimmäisena loppuaika.

hhmm tai hh

Parametristä voi jättää minuutti ja sekunttiarvon pois.

Päivärajaus [dat]

Arvo

Selitys

vvkkpp

Jos parametrinä yksi aika-arvo, tarkoittaa se alkupäivämäärää.

vvkkpp_vvkkpp

Jos parametrinä kaksi aika-arvoa, erotellaan ajat toisistaa alaviivalla ”_”. Tällöin ensin annetaan alkuaika ja jälkimmäisena loppuaika.

Viikonpäivä [wkd]

Arvo

Selitys

0

Maanantai

1

Tiistai

2

Keskiviikko

3

Torstai

4

Perjantai

5

Lauantai

6

Sunnuntaui

Luennot [lec]

Arvo

Selitys

1

Haetaan luennoksi merkitty kurssi

Tapahtumat [eve]

Arvo

Selitys

1

Haetaan tapahtumaksi merkitty kurssi

Kurssit [cou]

Arvo

Selitys

1

Haetaan kurssit, joilla ei ole merkintää ”Luennot” tai ”Tapahtumat”.

Kieli [lang]

Arvo

Selitys

en

Englanti

fi

Suomi

sv

Ruotsi

Opetuskerrat [ses]

Arvo

Selitys

1

Palautetaan hakutuloksessa kurssin opetuskertalista

Kuvaustekstit [desc]

Arvo

Selitys

1

Palautetaan hakutuloksessa kurssin kuvaus. ja internetkuvaus tekstit

Muuttuneet kurssit [changed]

Arvo

Selitys

1

Palautetaan hakutuloksessa muuttuneet kurssit. Käytetään parametrejä 'dat' ja 'tim' määrittelemään aikaraja, jonka jälkeen muuttuneet kurssit palautetaan. Jos  'dat'-parametriä ei anneta, palautetaan oletuksena viimeisen vuorokauden sisällä muuttuneet pyynnön tekohetkestä.

Järjestys [order]

Arvo

Selitys

1

Ensimmäisen opetuskerran mukaan nousevasti (oletus, jos 'order' -parametria ei ole määritelty). Laskevana arvolla -1.

2

Aakkosittain kurssin nimen, -koodin mukaan nousevasti. Laskevana arvolla -2.

3

Julkinen alkaen päiväyksen mukaan nousevasti. Laskevana arvolla -3.

 

Vastausmuoto [format]

Arvo

Selitys

xml

Palautetaan hakutulos XML-muodossa

json

Palautetaan hakutulos JSON-muodossa

 

Rajapintapyynnöllä saatavat id numerot

Parametri

Kuvaus

Pyyntö

cgt

Aineryhmän id

... /v1/subjectgroup/all

str

Opetuspaikan id

... /v1/location/all

tar

Kohderyhmän id

... /v1/commonselection/targetgroup

tla

Opetuskielen id

... /v1/teachinglanguage

Esimerkkikutsuja:

Kurssihaku

Vapaasanahaussa termi 'testaus' ja näytä vain kaksi ensimmäistä:

... /v1/course/search?txt=testaus&limit=2

kurssikoodina 'H173590':

... /v1/course/search?txt=H173590

Työväenopisto ja aineryhmän id

... /v1/course/search?com=[opistoid]&cgt=86

 

Aineryhmän id, kaksi eri opetuspaikkaa, Kurssi alkaa '01.08.2017 - 31.12.2017'

... /v1/course/search?cgt=116&str=327,306&dat=170801000000_171231235959

 

Kahdesta eri opistosta, aineryhmän id

... /v1/course/search?com=[opistoid],[opistoid]&cgt=176

 

Vastaus suomen kielisenä, 1.9.2017 klo 00:04:00 jälkeen muuttuneet kurssit

... /v1/course/search?lang=fi&dat=170901&tim=000400&changed=1

 

Viimeisen vuorokauden aikana muuttuneet kurssit

... /v1/course/search?changed=1

 

Viimeisen vuorokauden aikana muuttuneet kurssit JSON muodossa

... /v1/course/search?changed=1&format=json

Kurssihaun palauttamat objektit

Haku palauttaa kurssista seuraavat tiedot:

Kurssilista (courselist)

Atribuutti

Kuvaus

language

Kieli, jolla mahdolliset käännettävät tiedot käännetään

wholecount

Haun palauttama tulosmäärä (ilman limit rajoitusta)

resultCRIDs

ID Lista kaikista löydetyistä kursseista (pilkku eroteltu). Palautetaan, jos hakuparametri 'cids' arvossa 1.

total

Haun palauttama tulosmäärä tähän hakuun

limit

Haun palauttama maksimitulosmäärä

course

Haun palauttaman yhden kurssin tiedot

Kurssi (course)

Atribuutti

Kuvaus

id

Kurssin id ilmonetissa

code

kurssikoodi

name

nimi

locations

Kursin opetuspaikkalista

price

Kokonaishinta

priceMaterial

Lisähinta

teacher

Opettaja (mikäli opisto asettanut tiedon näkyväksi).

firstSession

Ensimmäisen opetuskerran aloitusaika

firstSessionEND

Ensimmäisen opetuskerran lopetusaika

firstSessionWeekdate

Ensimmäisen opetuskerran viikonpäivä

lastSession

Viimeinen opetuskerta

InternetEnrollment

Internet ilmoittautuminen

minStudentCount

Oppilaiden minimimääräkurssilla, jotta kurssi mahdollisesti lähtee käyntiin

maxStudentCount

Oppilaiden maksimimäärä kurssilla. Ylimenevät jono-tilaan.

firstEnrollmentDate

Ensimmäinen ilmoittautumispäivä

lastEnrollmentDate

Viimeinen ilmoittautumispäivä

acceptedCount

Hyväksyttyjen oppilaiden määrä. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi.

SinglePaymentCount

Kertalippuilmoittaumiselle varatut paikat. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi tai toiminto ei ole käytössä.

wwwlink

Kurssin www-osoite ilmoittautumisjärjestelmään

image

Kurssille asetettu kuva.

isEvent

Onko kurssi tapahtuma

isGeneralLecture

Onko kurssi yleisluento

isCourse

Onko kurssi kurssi

isOnlineLecture

Onko kurssi verkkoluento

isOnlineTeaching

Onko kurssi verkko-opetusta

isOpenUniversity

Onko kurssi avoin yliopisto-opetusta

structureName

Opetuspaikka polku

structureNameID

Opetuspaikan id

companyID

Opiston id

lastCancellationDate

Viimeinen ilmoittautumisen perumispäiväys

link

Kurssille määritellyt www-linkit

attachment

Kurssille määritellyt liitetiedostot www-linkkeinä

enrollmentData

Ilmoittautuminen mahdollista

Opetuspaikka (location)

 

Atribuutti

Kuvaus

id

Kurssin opetuspaikan id. Opetuspaikan tarkemmat tiedot saa kysymällä sen Opetuspaikkahaulla.

path

Kurssin opetuspaikan nimi.

Ilmoittautumistieto (enrollmentData)

 

Atribuutti

Kuvaus

enrollmentStarted

Onko ilmoittautuminen alkanut. Arvolla 1, on alkanut.

enrollmentExpired

Onko ilmoittautuminen umpeutunut. Arvolla 1, on umpeutunut.

enrollmentPossible

Onko ilmoittautuminen mahdollista. Arvolla 1, on mahdollista.

unenrollmentPossible

Onko ilmoittautumisen peruminen mahdollista. Arvolla 1, on mahdollista.

advancedEnrollmentPossible

Onko ennakkoilmoittautuminen mahdollista. Arvolla 1, on mahdollista.

seatsRemainingInfo

Näytetään, mikäli opisto ei ole sallinut vapaiden paikkojen määrän näyttämistä. Tarkempi kuvaus alla.

Paikkaa jäljellä tieto (seatsRemainingInfo)

 

Atribuutti

Kuvaus

name

Sisältää numeroarvon, jos vapaita paikkoja on kolme tai vähemmän. Muussa tapauksessa tekstin ’Ilmoittaudu’ tai ’Ilmoittaudu jonoon’.

value

Sisältää arvon 1, jos vapaita paikkoja enemmän kuin kolme. Arvon 2, jos ilmoittautuminen vain jonoon. Aarvon 3, jos vapaita paikkoja kolma tai vähemmän.

 

Kurssin tarkemmat tiedot

 

Parametri

Tyyppi

Kuvaus

ses

Int

Palauta myös opetuskerrat hakutuloksessa (vain arvolla 1),. Voi sisältää vain yhden arvon.

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

img

Int

Sisällytetäänkö hakutulokseen mahdollinen kurssiin liitetyn kuvan URL  (vain arvolla 1).

lnk

Int

Sisällytetäänkö hakutulokseen mahdolliset kurssiin liitetyt linkit (URL:it)  (vain arvolla 1).

att

Int

Sisällytetäänkö hakutulokseen mahdolliset kurssiin liitetyt liitetiedostot (URL:it)  (vain arvolla 1).

 

Kurssi tiedot tunnetulla kurssi id:llä:

... /v1/course/11325

 

Kurssi tiedot tunnetulla kurssikoodilla:

... /v1/course/code/H173590

 

Kurssi tiedot tunnetulla kurssikoodilla JSON-muodossa:

... /v1/course/code/H173590?format=json

 

Haun palauttamat objektit

Haku palauttaa kurssista seuraavat tiedot:

Kurssi (courseinfo)

Atribuutti

Kuvaus

id

Kurssin id ilmonetissa

code

kurssikoodi

name

nimi

departmentID

Kurssin ainealuetiimin id

description

kuvausteksti

descriptionInternet      

kuvausteksti

location

Sisältää listan kurssin käyttämistä opetuspaikoista. Jos formaatina XML, palautetaan juurielementtinä ’locations

price

hinta

priceMaterial

lisähinta

teacher

Opettaja (mikäli opisto asettanut tiedon näkyväksi).

firstSession

Ensimmäinen opetuskerta

lastSession

Viimeinen opetuskerta

companyID

Opiston id numero.

firstEnrollmentDate

Ensimmäinen ilmoittautumispäivä

lastEnrollmentDate

Viimeinen ilmoittautumispäivä

lastCancellationDate

Viimeinen perusmispäivä

minStudentCount

Oppilaiden minimimääräkurssilla, jotta kurssi mahdollisesti lähtee käyntiin

maxStudentCount

Oppilaiden maksimimäärä kurssilla. Ylimenevät jono-tilaan.

startingDateFromCalendar

Ensimmäisen opetuskerran päiväys

internetRegistering

Internet ilmoittautuminen mahdollista

reviewDate

Kurssin tarkistuspäiväys

additionalInfoLink

Lisätiedot-linkki (ei välttämättä ole URL)

wwwLink

Kurssin www-osoite ilmoittautumisjärjestelmään

equipment

Väline

book

Oppikirja/oppimateriaali

descriptionForFirstSession

Ensimmäiselle kerralle mukaan -teksti

enrollmentNotPossible

Ilmoittautuminen ei mahdollista -valinta kurssilla

useFollowDate

Ennakkoilmoittautumispäiväykset asetettu

followDateStart

Ennakkoilmoittautumisen alkupäiväys

followDateEnd

Ennakkoilmoittautumisen loppupäiväys

parentIDs

Edeltävän kurssin id

status

Kurssin tilan id

skillLevel

Taitotaso

skillLevelName

Taitotason nimi

discounts

Alennukset

acceptedCount

Hyväksyttyjen oppilaiden määrä. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi.

singlePaymentCount

Kertalippuilmoittaumiselle varatut paikat. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi tai toiminto ei ole käytössä.

reserveCount

Varapaikat. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi.

queueCount

Jonopaikat. Jos arvossa -1, tietoa ei anneta rajapinnan kautta näkyväksi.

plannedHours

Suunnitellut tunnit.

teachingLanguages

Opetuskielet.

companyName

Opiston pitkä nimi.

companyNameShort

Opiston lyhyt nimi

childCourseName

Jatkokurssin koodi ja nimi

parentCourseCode

Edeltävän kurssin koodi

parentCourseName

Edeltävän kurssin nimi

courseTypeID

Kurssityypin id (mikäli opisto asettanut tiedon näkyväksi)

courseTypeName

Kurssityyppi (mikäli opisto asettanut tiedon näkyväksi)

image

Kurssille asetettu kuva.

teachingSession

Opetuskertalista

link

Kurssille määritellyt www-linkit

attachment

Kurssille määritellyt liitetiedostot www-linkkeinä

isEvent

Onko tapahtuma

isGeneralLecture

Onko yleisluento

isCourse

Onko kurssi

isOnlineLecture

Onko verkkoluento

isOnlineTeaching

On verko-opetus

isOpenUniversity

Onko avoin yliopsito

structureName

Opetuspaikan nimi (alue tasolle)

structureNameID

Opetuspaikan id (alue tasolle)

structureNameB

Opetuspaikan nimi (rakennus tasolle)

structureNameBID

Opetuspaikan id (rakennus tasolle)

payable

Onko kurssi maksettavissa ilmonetin kautta (vain arvolla 1)

enrollmentData

Sisältää muuttujia ilmoittautumiseen liittyen

Opetuskerta (teachingSession)

id

Opetuskerran id

start

aloituspäivä ja aika

end

Loppumispäivä ja aika

teachingplace

Opetuspaikka

status

tila-tieto

Ilmoittautumistieto (enrollmentData)

enrollmentStarted

Onko ilmoittautuminen alkanut

enrollmentExpired

Onko ilmoittautuminen umpeutunut

enrollmentPossible

Onko ilmoittautuminen mahdollista

unenrollmentPossible

Onko ilmoittautumisen peruminen mahdollista

advancedEnrollmentPossible

Onko ennakkoilmoittautuminen mahdollista. Arvolla 1, on mahdollista.

seatsRemainingInfo

Näytetään, mikäli opisto ei ole sallinut vapaiden paikkojen määrän näyttämistä. Tarkempi kuvaus alla.

notification

Suositellut ilmoitukset käyttäjälle

Paikkaa jäljellä tieto (seatsRemainingInfo)

 

Atribuutti

Kuvaus

name

Sisältää numeroarvon, jos vapaita paikkoja on kolme tai vähemmän. Muussa tapauksessa tekstin ’Ilmoittaudu’ tai ’Ilmoittaudu jonoon’.

value

Sisältää arvon 1, jos vapaita paikkoja enemmän kuin kolme. Arvon 2, jos ilmoittautuminen vain jonoon. Aarvon 3, jos vapaita paikkoja kolma tai vähemmän.

 

Aineryhmähaku

Parametri

Tyyppi

Kuvaus

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

 

Kaikki aineryhmät saa haettua kyselyllä

... /v1/subjectgroup/all

Yksi tunnettu aineryhmä:

... /v1/subjectgroup/576

Haun palauttamat objektit

Haku palauttaa kurssista seuraavat tiedot:

Aineryhmä (subjectgroup)

id

Aineryhmän id

name

Nimi

parentid

Aineryhmän isäntäaineryhmä (puurakenteessa)

tkid

Tilastokeskuksen aineryhmä luokitus (Opetushallinnon koulutusluokitus 2002).

 

Aineryhmäpolkuhaku

Parametri

Tyyppi

Kuvaus

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

level

Int

Polkutason numero. Voi sisältää vain yhden arvon. Arvolla 1=polun ensimmäinen taso, 2 = toinen taso jne.

separator

String

Erotinmerkki, jolla polun tasot erotellaan toisistaan

 

Kaikki aineryhmät saa haettua polkumuotoisena kyselyllä

... /v1/subjectgroup/path

Kaikki aineryhmät, tasoon 2 asti, erotinmerkkinä ;

... /v1/subjectgroup/path?level=2&separator=;

Haun palauttamat objektit

Haku palauttaa kurssista seuraavat tiedot:

Aineryhmä (subjectgroup)

id

Aineryhmän id ilmonetissa

name

Nimi

path

Aineryhmän puurakenne

pathid

Aineryhmän puurakenne id:t

level

Aineryhmän taso

 

Opetuspaikkahaku

Parametri

Tyyppi

Kuvaus

com

String

Opiston id numero.

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

status

Int

Voi sisältää arvon 0 tai 1 (ne, joita ei näytetä ilmoittautumisjärjestelmässä). Jos arvo muu kuin 0 tai 1, asetetaan 0.

 

Kaikki opetuspaikat saa haettua kyselyllä

... /v1/location/all

Kaikki tietyn opiston opetuspaikat saa haettua kyselyllä

... /v1/location/all?com=[opistoid]

Yksi tunnettu opetuspaikka

... /v1/location/39

Haun palauttamat objektit

Haku palauttaa kurssista seuraavat tiedot:

Paikka (location)

id

Aineryhmän id ilmonetissa

name

Nimi

path

Opetuspaikan nimi (alue, kaupunginosa, rakennus, huone)

pathid

Opetuspaikan id. Jos useita erotinmerkillä eroteltuna, vastaa id 'path'-attribuutin vastaavia.

streetAddress

Opetuspaikan osoite

postalCode

Opetuspaikan postinumero

city

Opetuspaikan kaupunki

parentid

Opetuspaikan isäntäopetuspaikan id

parentName

Opetuspaikan isäntäopetuspaikan nimi

companyID

Opetuspaikan opistoid

ownerID

Opetuspaikan omistajaopiston opistoid (tämä opisto on jakanut paikan)

typeID

Opetuspaikan tason tyyppi, 101 = rakennus, 102 = huone, 103 = alue, 104 = asuinalue

 

Opetuspaikan varaustiedon haku

Parametri

Tyyppi

Kuvaus

com

String

Opiston id numero.

str

String

 

dat

String

Päiväysrajaus. Annetaan muodossa vvkkpp tai vvkkpphhmmss. Jos vain yksi arvo määritelty, asetetaan se haun alkupäiväykseksi ja haetaan kaikki tapahtumat siitä eteenpäin. Jos halutaan määrittää aikaväli, annetaan se muodossa vvkkpp_ vvkkpp tai vvkkpphhmmss_vvkkpphhmmss. Jos tämä hakuehto jätetään tyhjäksi, haetaan hakuhetkestä vuorokausi eteenpäin.

sct

String

Varaustapahtuman tyyppi. Voi sisältää arvot 'R' (varaus)  ja/tai 'C' (paikka suljettu). Ilman parametriä, vastaa arvoa 'R'.

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

 

Hakuhetkestä vuorokausi eteenpäin olevat kaikkien opetuspaikkojen varaukset

... /v1/location/reservation

 

Suljetut opetuspaikat aikaväliltä 3.9.2018 klo 00:00:00– 5.9.2018 klo 23:59:59

.../v1/location/reservation?format=xml&dat=180903_180905&sct=C

 

Varaukset aikaväliltä 3.9.2018 klo 12:30:00 – 5.9.2018 klo 17:00:00

.../v1/location/reservation?format=xml&dat=180903123000_180905170000

 

Varaukset kahdessa opetuspaikassa, aikaväliltä 1.9.2018 klo 00:00:00 – 5.9.2018 klo 23:59:59

.../v1/location/reservation?format=xml&dat=180901_180905&str=44,69

 

Haun palauttamat objektit

Haku palauttaa varauksesta seuraavat tiedot:

Tapahtuma (event )

Atribuutti 'type'

Tapahtuman tyyppi. Arvo 'Reservation' = varaus. Arvo 'Closed' = paikka suljettu.

id

Varaustapahtuman id

start

Alkamispäiväys

end

Päättymispäiväys

teachingPlace

Opetuspaikka

caption

Otsikkoteksti

description

Kuvausteksti

company

Varauksen tehneen opiston tiedot

Opetuspaikka (teachingPlace)

id

Opetuspaikan id

path

Nimi puurakenteena

Opiston tiedot (company)

id

Opiston id

name

Nimi

discountAllowed

Onko alennusmahdollistettu. Arvolla 1, on mahdollistettu.

 

Valintalistahaku

Valintalistat ovat samanrakenteista tietoa, mutta lajiteltu tyyppeihin. Tyyppi asetetaan URL-parametriin kyselyn polussa.

URL-parametri

Kuvaus

coursetypes

Kurssityyppi

educations

Koulutus

workstatuses

Työtilanne

 

 

Parametri

Tyyppi

Kuvaus

com

String

Opiston id numero. Voi sisältää vain yhden arvon.

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

 

Kaikki tyypin objektit saa haettua kyselyllä

... /v1/commonselection/[URL-parametri]

Kaikki tietyn opiston  tyypin objektit saa haettua kyselyllä

... /v1/commonselection/[URL-parametri]?com=[opiston id]

Yhden tietyn tyypin objekti, jonka csid on 70

... /v1/commonselection/[URL-parametri]/70

Mikäli opisto ei ole sallinut tyypin tietojen palautusta rajapinnan kautta, palautetaan kyseisen opiston tiedoista error-objekti.

Haku palauttaa kurssista seuraavat tiedot:

Atribuutti

Kuvaus

csid

Valintalistaobjektin id

id

Tyypin id

name

Tyypin nimi

companyID

Opiston id, jolle tyyppi kuuluu. Voi puuttua pyynnön vastauksesta tai olla arvossa 0, jolloin tieto ei ole opistokohtainen.

Opetuskielihaku

Parametri

Tyyppi

Kuvaus

format

String

Pyynnön vastauksen tyyppi.

lang

String

Kieli. Voi sisältää vain yhden arvon.

 

Kaikki opetuskeilet saa haettua kyselyllä

... /v1/teachinglanguage

Haku palauttaa opetuskielestä seuraavat tiedot:

Atribuutti

Kuvaus

id

Tyypin id

name

Tyypin nimi

nameFI

Tyypin nimi suomeksi

nameEN

Tyypin nimi englanniksi

nameSV

Tyypin nimi ruotsiksi