Helsingin kaupungin palvelukartan ja toimipisterekisterin REST-rajapinnan versio 2

Tämä on rajapinnan toinen versio ja sisältää ensimmäistä versiota laajemmat toiminnot tietojen kyselemiseksi. Versiossa 2 on keskitytty kehittämään rajapinnan hakutoiminnallisuuksia. Rajapintaa kehitetään tarpeiden ja palautteiden pohjalta eteenpäin, lisäten toiminnallisuuksia ja uusia tietoja.

Mitä rajapinnan kautta voi kysellä

• Organisaatiot jotka palveluita tuottavat (esim. kaupungit ja Suomen valtio)
• Yksiköt (virastot) jotka palveluita järjestävät (esim. sosiaalivirasto)
• Alueelliset kunnat (esim. Helsinki, Espoo, Vantaa)
• Toimipisteet joissa palveluita tarjotaan (esim. Rikhardinkadun kirjasto)
• Palvelut joita eri toimipisteissä tarjotaan
• Palveluluokittelun, josta palvelut muodostavat palvelupuun
• Esteettömyyden parametrit (esim. INTERIOR.ACCESSIBLE_WC.existing, INTERIOR.ACCESSIBLE_WC.DOOR.easy_to_open_and_close)
• Toimipisteen esteettömyystiedot rakenteellisesti (esim. INTERIOR.ACCESSIBLE_WC.existing = true, INTERIOR.ACCESSIBLE_WC.DOOR.easy_to_open_and_close = false)

Tietojen kyseleminen rajapinnasta

Tietoja voidaan kysyä rajapinnasta joko yksi tietoalkio kerrallaan - tai listauksina, joka palauttaa tiedot kaikista ko. tyypin tietoalkioista yhdellä kertaa.

Osoitteet joista tietoa voi kysellä, muodostuvat seuraavalla tavalla:

Kysely kaikkien tietoalkioiden listaamiseksi

www.hel.fi/palvelukarttaws/rest/v2/organization/

Ylläoleva kysely palauttaa tiedot kaikista organisaatioista listana JSON-objekteja. Huomioitavaa on, että kaikissa tietomalleissa listauksen tietomalli ja tarkemman kyselyn tietomalli ei ole täysin yhteneväinen. Tämä on dokumentoituna alempana tietomallien kohdalla.

Kysely yhden tietoalkion tietojen saamiseksi

www.hel.fi/palvelukarttaws/rest/v2/organization/91

Ylläoleva kysely palauttaa yhden tietoalkion tiedot.

Rajapinta palauttaa tiedot oletuksena JSON-muodossa ja tukee JSONP-tyyppistä kyselyä, mikäli kyselyyn liittää mukaan callback-parametrin.

Esimerkiksi: http://www.hel.fi/palvelukarttaws/rest/v2/organization/91?callback=foo

Mikäli haluat datan XML-muodossa, liitä kyselyyn parametri ?format=xml

Esimerkiksi: http://www.hel.fi/palvelukarttaws/rest/v2/organization/91?format=xml

Esimerkkiurlit

Osoite organisaatioiden kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/organization/

Osoite yksiköiden kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/department/

Osoite alueellisten kuntien kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/arealcity/

Osoite toimipisteiden kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/unit/

Osoite palveluiden kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/service/

Osoite palvelupuun kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/servicetree/

Osoite esteettömyysparametrien kyselemiseksi: www.hel.fi/palvelukarttaws/rest/v2/accessibility_variable/

Osoite toimipisteen esteettömyystietojen kyselemiseksi: http://www.hel.fi/palvelukarttaws/rest/v2/unit/1/accessibility/

Datamallien kuvaus

Organisaatio

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/organization/91):

{"id":91,"name_fi":"Helsingin kaupunki","name_sv":"Helsingfors stad","name_en":"City of Helsinki","data_source_url":"www.hel.fi"}

Yksikkö

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/department/SOSV):

{"id":"SOSV","name_fi":"Sosiaalivirasto, Helsinki","name_sv":"Socialverket, Helsingfors","name_en":"Social Services Department, Helsinki","abbr":"SOSV","org_id":91}

Alueellinen kunta

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/arealcity/91/):

{"arealcity_id":91,"name_fi":"Helsingin kaupunki","name_sv":"Helsingfors stad","name_en":"City of Helsinki"}

Toimipiste

Esimerkkiobjekti listauksessa (http://www.hel.fi/palvelukarttaws/rest/v2/unit/):

{"id":1,"org_id":91,"name_fi":"Päiväkoti Apila","name_sv":"Päiväkoti Apila","name_en":"Day care Apila","latitude":60.24441,"longitude":24.855764,"northing_etrs_gk25":6679890,"easting_etrs_gk25":25493876,"street_address_fi":"Arentikuja 3","street_address_sv":"Arrendegränden 3","street_address_en":"Arentikuja 3","address_zip":"00410","address_city_fi":"Helsinki","address_city_sv":"Helsingfors","address_city_en":"Helsinki"}


Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/unit/1):

{"id":1,"arealcity_id":91,"org_id":91,"dept_id":"SOSV","org_owned":true,"data_source_url":"www.hel.fi","provider_type":101,"service_ids":[27726,27894,27738,27874,26420,29704,28230],"name_fi":"Päiväkoti Apila","name_sv":"Päiväkoti Apila","name_en":"Day care Apila","latitude":60.24441,"longitude":24.855764,northing_gk25":6681311,"easting_gk25":25492013,"manual_coordinates":false,"street_address_fi":"Arentikuja 3","street_address_sv":"Arrendegränden 3","street_address_en":"Arentikuja 3","address_zip":"00410","address_city_fi":"Helsinki","address_city_sv":"Helsingfors","address_city_en":"Helsinki","citydistrict_name":"kaarela","subdistrict_name":"malminkartano","phone":"09 310 41571","email":"pk.apila@hel.fi","www_fi":"http://www.hel.fi/hki/Sosv/fi/P_iv_hoito/P_iv_kodit/P_iv_koti+Apila/","www_sv":"http://www.hel.fi/hki/Sosv/fi/P_iv_hoito/P_iv_kodit/P_iv_koti+Apila/","www_en":"http://www.hel.fi/hki/Sosv/fi/P_iv_hoito/P_iv_kodit/P_iv_koti+Apila/","address_postal_full":"PL 41810, 00099 Helsingin kaupunki","connections":[{"connection_type":"215","name_fi":"Joukkoliikenneyhteydet tänne","name_en":"Public transport to here","name_sv":"Kollektivtrafik till platsen","www_fi":"http://www.reittiopas.fi/fi/?to_in\u003darentikuja+3,+helsinki","www_sv":"http://www.reittiopas.fi/sv/?to_in\u003darentikuja+3,+helsinki","www_en":"http://www.reittiopas.fi/en/?to_in\u003darentikuja+3,+helsinki"},{"connection_type":"110","name_fi":"Päiväkodinjohtaja Miia Kovalainen, p. 09 310 41571","name_en":"Head of day care centre Miia Kovalainen, p. 09 310 41571","name_sv":"Daghemsföreståndare Miia Kovalainen, p. 09 310 41571","contact_person":"Miia Kovalainen","tel":"09 310 41571","email":"miia.kovalainen@hel.fi"},{"connection_type":"1221","name_fi":"Täytä päivähoitohakemus","name_en":"Application for day care","name_sv":"Ansökan om barndagvård","www_fi":"http://www.hel.fi/hki/sosv/fi/P_iv_hoito/P_iv_kodit/Hakeminen","www_sv":"http://www.hel.fi/hki/sosv/fi/P_iv_hoito/P_iv_kodit/Hakeminen","www_en":"http://www.hel.fi/hki/sosv/fi/P_iv_hoito/P_iv_kodit/Hakeminen"},{"connection_type":"161","name_fi":"Yleistä palautetta Sosiaalivirastolle","name_en":"General feedback to Social Services Department","name_sv":"Allmän respons till Socialverket","www_fi":"http://www.hel.fi/hki/sosv/fi/Palaute","www_sv":"http://www.hel.fi/hki/sosv/sv/Respons","www_en":"http://www.hel.fi/hki/sosv/en/Feedback"}],"events":[],"accessibility_sentences":[{"sentence_group_name":"Saattoliikenne","sentence_fi":"Saattoliikenteen pysähtymispaikka sijaitsee sisäänkäynnin läheisyydessä, josta jalkakäytävälle pääsee siirtymään sujuvasti.","sentence_sv":"Hållplatsen för skjutstrafik ligger i närheten av ingången, på en plats varifrån det är lätt att ta sig till trottoaren.","sentence_en":"The pick-up and drop-off area is located in the vicinity of the entrance, giving easy access to the pavement."},{"sentence_group_name":"Kulkureitti sisäänkäynnille","sentence_fi":"Kulkureitti sisäänkäynnille on tasainen ja riittävän leveä.","sentence_sv":"Rutten till ingången är jämn och tillräckligt bred.","sentence_en":"The route to the entrance is smooth and sufficiently wide."},{"sentence_group_name":"Sisäänkäynti","sentence_fi":"Sisäänkäynti erottuu selkeästi ja on valaistu. Sisäänkäynnin yläpuolella on katos.","sentence_sv":"Ingången är lätt att urskilja och belyst. Ingången har ett tak.","sentence_en":"The entrance stands out clearly and is illuminated. There is a canopy above the entrance."},{"sentence_group_name":"Sisäänkäynti","sentence_fi":"Sisäänkäynnin yhteydessä olevat ovet ovat vaikeasti hahmotettavat. Oven ulkopuolella on riittävästi vapaata tilaa liikkumiselle esim. pyörätuolin kanssa. Ovi avautuu käsin helposti.","sentence_sv":"Dörrarna vid ingången är svåra att överblicka. Utanför dörren finns tillräckligt med fritt utrymme för att röra sig t.ex. med rullstol. Dörren är lätt att öppna för hand.","sentence_en":"The doors connected to the entrance are hard to perceive. Outside the door there is sufficient room for moving e.g. with a wheelchair. The door opens easily manually."},{"sentence_group_name":"Sisäänkäynti","sentence_fi":"Sisäänkäynnin yhteydessä on yli 2 cm korkeita kynnyksiä.","sentence_sv":"Vid ingången finns trösklar som är över 2 cm höga.","sentence_en":"The entrance has thresholds over 2 cm high."},{"sentence_group_name":"Sisätilat","sentence_fi":"Toimipiste sijaitsee samassa kerroksessa kuin sisäänkäynti.","sentence_sv":"Verksamhetsstället ligger på samma plan som ingången.","sentence_en":"The customer service point is located on the same floor as the entrance."},{"sentence_group_name":"Sisätilat","sentence_fi":"Tilassa olevat ovet erottuvat selkeästi.","sentence_sv":"Dörrarna i lokalen är lätta att urskilja.","sentence_en":"The doors in the facility stand out clearly."}]}

HUOM! Toimipisteissä listauksessa ja yksittäisen toimipisteen tietoja haettaessa olevissa objekteissa on kenttien määrässä eroa.

Palvelu

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/service/26244/):

{"id":26244,"name_fi":"Oikeusturva ja demokratia","name_sv":"Rättsskydd och demokrati","name_en":"Legal protection and democracy","child_ids":[...],"unit_ids":[...]}

Palvelupuu

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/servicetree/25554/):

{"id":25554,"name_fi":"Liikenne","name_sv":"Trafik ","name_en":"Traffic","children":[...]}

Esteettömyyden parametri

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/accessibility_variable/1/):

{"variable_id":1,"variable_name":"OUTSIDE.01.ACCESSIBLE_PARKING_SPACE.count","values":["0","1","2","3","4","5","6","7","8","9","10","more_than_10"]}

Toimipisteen esteettömyystiedot

Esimerkkiobjekti (http://www.hel.fi/palvelukarttaws/rest/v2/unit/1/accessibility/):

{"unit_id":1,"accessibility_properties":[{"variable_id":1,"variable_name":"OUTSIDE.01.ACCESSIBLE_PARKING_SPACE.count","value":"0"},{"variable_id":5,"variable_name":"OUTSIDE.01.PICKUP_AND_DROPOFF_AREA.near_entrance","value":"true"},{"variable_id":6,"variable_name":"OUTSIDE.01.PICKUP_AND_DROPOFF_AREA.easy_access_to_pavement","value":"true"},{"variable_id":7,"variable_name":"ROUTE_TO_ENTRANCE.01.surface","value":"smooth"},{"variable_id":8,"variable_name":"ROUTE_TO_ENTRANCE.01.width","value":"sufficiently_wide"},{"variable_id":9,"variable_name":"ROUTE_TO_ENTRANCE.01.guided","value":"not_guided_but_clear"},{"variable_id":10,"variable_name":"ROUTE_TO_ENTRANCE.01.illuminated","value":"false"},{"variable_id":11,"variable_name":"ROUTE_TO_ENTRANCE.01.uses_movement_guiding_material","value":"false"},{"variable_id":12,"variable_name":"ROUTE_TO_ENTRANCE.01.steep_slope","value":"false"},{"variable_id":13,"variable_name":"ROUTE_TO_ENTRANCE.01.STEPS.existing","value":"false"},{"variable_id":19,"variable_name":"ROUTE_TO_ENTRANCE.01.RAMP.existing","value":"false"},{"variable_id":23,"variable_name":"ROUTE_TO_ENTRANCE.01.level_lift","value":"false"},{"variable_id":24,"variable_name":"ROUTE_TO_ENTRANCE.01.wheelchair_lift","value":"false"},{"variable_id":25,"variable_name":"ROUTE_TO_ENTRANCE.01.LIFT.existing","value":"false"},{"variable_id":33,"variable_name":"ENTRANCE.01.ALTERNATIVE_ENTRANCE.easiest","value":"false"},{"variable_id":35,"variable_name":"ENTRANCE.01.appearance","value":"canopy_above_entrance"},{"variable_id":36,"variable_name":"ENTRANCE.01.illuminated","value":"true"},{"variable_id":37,"variable_name":"ENTRANCE.01.STEPS.existing","value":"false"},{"variable_id":43,"variable_name":"ENTRANCE.01.RAMP.existing","value":"false"},{"variable_id":47,"variable_name":"ENTRANCE.01.level_lift","value":"false"},{"variable_id":48,"variable_name":"ENTRANCE.01.wheelchair_lift","value":"false"},{"variable_id":49,"variable_name":"ENTRANCE.01.LIFT.existing","value":"false"},{"variable_id":57,"variable_name":"ENTRANCE.01.DOOR.sufficiently_room_for_wheelchair_in_front","value":"true"},{"variable_id":58,"variable_name":"ENTRANCE.01.DOOR.stands_out_clearly","value":"false"},{"variable_id":59,"variable_name":"ENTRANCE.01.DOOR.glass_door","value":"true"},{"variable_id":60,"variable_name":"ENTRANCE.01.DOOR.glass_door_contrast_marking","value":"false"},{"variable_id":61,"variable_name":"ENTRANCE.01.DOOR.opening_method","value":"opens_easily_manually"},{"variable_id":63,"variable_name":"ENTRANCE.01.threshold_height","value":"over_20mm"},{"variable_id":64,"variable_name":"ENTRANCE.01.FOYER.existing","value":"true"},{"variable_id":65,"variable_name":"ENTRANCE.01.FOYER.sufficiently_room_for_wheelchair","value":"true"},{"variable_id":66,"variable_name":"SERVICE_POINT.type","value":"long_term_stay"},{"variable_id":68,"variable_name":"SERVICE_POINT.same_floor_as_entrance_no_need_for_lift","value":"true"},{"variable_id":79,"variable_name":"INTERIOR.uses_movement_guiding_material","value":"false"},{"variable_id":91,"variable_name":"INTERIOR.threshold_height","value":"under_20mm"},{"variable_id":92,"variable_name":"INTERIOR.STEPS.existing","value":"false"},{"variable_id":98,"variable_name":"INTERIOR.RAMP.existing","value":"false"},{"variable_id":102,"variable_name":"INTERIOR.level_lift","value":"false"},{"variable_id":103,"variable_name":"INTERIOR.wheelchair_lift","value":"false"},{"variable_id":104,"variable_name":"INTERIOR.DOORS.stand_out_clearly","value":"true"},{"variable_id":105,"variable_name":"INTERIOR.DOORS.glass_door","value":"false"},{"variable_id":107,"variable_name":"INTERIOR.ACCESSIBLE_WC.existing","value":"false"}]}

Hakutoiminnallisuudet

Toimipisteitä listaavissa kyselyissä on mahdollista käyttää hakuparametrejä. Hakuparametrien avulla kyselystä palautuvien toimipisteiden joukkoa on mahdollista rajata halutulla tavalla. Hakuparametrejä voi myös yhdistellä.

Hakuparametrit

Hakutulosten rajoittaminen yhteen tai useampaan tietoja tuottavaan organisaatioon.

Esimerkki. Suomi.fi-rajapinnasta luetut toimipisteet: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?organization=1000

Hakutulosten rajoittaminen yhteen tai useampaan yksikköön.

Esimerkki. Helsingin Taidemuseon ja Kaupunginmuseon toimipisteet: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?department=TAIMU+MUSEO

Hakutulosten rajoittaminen yhden tai useamman kaupungin alueelle.

Esimerkki. Kauniaisissa sijaitsevat toimipisteet: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?arealcity=235

Toimipisteiden haku yhden tai useamman palvelun avulla.

Esimerkki. Uimahallit ja maauimalat: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?service=28148+28150

Toimipisteiden etsiminen hakusanoilla.

Esimerkki. Lauttasaaren päiväkodit: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?search=lauttasaari+p%E4iv%E4koti

Etäisyyshaku.
HUOM: lat ja lon -parametrit voivat sisältää maksimissaan viisi desimaalia

Esimerkki. Toimipisteet 250 metrin etäisyydellä Kallion kirkon tornista: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?lat=60.18406&lon=24.94936&distance=250

Hakuparametrien yhdistely

Esimerkki. Uimahallit 500 metrin etäisyydellä Kallion kirkon tornista: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?service=28148&lat=60.18406&lon=24.94936&distance=500