REST API for City of Helsinki Service Map, Version 2

This is the second version of the REST API for City of Helsinki Service Map and it provides wider functionalities to access data. Main focus in the second version has been new search functionalities to filter unit data. The REST API will be improved and developed according to user feedback and needs by adding more functionalities and new data.

Data provided by the REST API

The REST API provides following data:

Retrieving data from the REST API

Data can be retrieved from the REST API as a collection or one item at the time.

How to retrieve data:

Request to list entire collection of one data model

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

The HTTP request above returns information about all organizations as JSON objects. Note that some data models may vary depending on whether they are retrieved as part of a collection or as a single item. For more information read the Description of Data Models.

Request to get one item

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

The HTTP request above returns information about one organization (id=91) as a JSON object.

The REST API returns data in JSON format by default. JSONP pattern is also supported when a callback parameter is added to the request.

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

If you want the data in XML format add parameter format=xml to the request

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

Example URLs

Address to retrieve organizations: www.hel.fi/palvelukarttaws/rest/v2/organization/

Address to retrieve departments: www.hel.fi/palvelukarttaws/rest/v2/department/

Address to retrieve areal cities: www.hel.fi/palvelukarttaws/rest/v2/arealcity/

Address to retrieve units: www.hel.fi/palvelukarttaws/rest/v2/unit/

Address to retrieve services: www.hel.fi/palvelukarttaws/rest/v2/service/

Address to retrieve service tree: www.hel.fi/palvelukarttaws/rest/v2/servicetree/

Address to retrieve accessibility parameters: www.hel.fi/palvelukarttaws/rest/v2/accessibility_variable/

Address to retrieve accessibility information of the unit: http://www.hel.fi/palvelukarttaws/rest/v2/unit/1/accessibility/

Description of Data Models

Organization

Example object (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"}
AttributeExplanation
idNumeric Id
name_fiOrganization name in Finnish
name_svOrganization name in Swedish
name_enOrganization name in English
data_source_urlData source

Department

Example object (http://www.hel.fi/palvelukarttaws/rest/v2/department/SOTE):

{"id":"SOTE","name_fi":"Sosiaali- ja terveysvirasto, Helsinki","name_sv":"Social- och hälsovårdsverket, Helsingfors","name_en":"The Department of Social Services and Health Care, Helsinki","abbr":"SOTE","org_id":91}
AttributeExplanation
idId
name_fiDepartment name in Finnish
name_svDepartment name in Swedish
name_enDepartment name in English
abbrAbbreviation of the department
org_idOrganization id

Areal city

Example object (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"}
AttributeExplanation
arealcity_idNumeric Id. Corresponds official municipal code
name_fiAreal city name in Finnish
name_svAreal city name in Swedish
name_enAreal city name in English

Unit

Example object (collection) (http://www.hel.fi/palvelukarttaws/rest/v2/unit/):

{"id":1,"org_id":91,"provider_type":101,"service_ids":[27726,33122,33116,32524,27874],"sources":[],"name_fi":"Päiväkoti Apila","name_sv":"Päiväkoti Apila","name_en":"Day care Apila","latitude":60.2444,"longitude":24.855799,"northing_etrs_gk25":6681311,"easting_etrs_gk25":25492013,"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","phone":"09 310 41571","email":"pk.apila@hel.fi","www_fi":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila","www_sv":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila","www_en":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila"}


Example object (single item) (http://www.hel.fi/palvelukarttaws/rest/v2/unit/1):

{"id":1,"arealcity_id":91,"org_id":91,"dept_id":"VAKA","org_owned":true,"data_source_url":"www.hel.fi","provider_type":101,"service_ids":[27726,33122,33116,32524,27874],"sources":[],"name_fi":"Päiväkoti Apila","name_sv":"Päiväkoti Apila","name_en":"Day care Apila","latitude":60.2444,"longitude":24.855799,"northing_etrs_gk25":6681311,"easting_etrs_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_id":33,"citydistrict_name":"kaarela","subdistrict_id":333,"subdistrict_name":"malminkartano","phone":"09 310 41571","email":"pk.apila@hel.fi","www_fi":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila","www_sv":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila","www_en":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/P_iv_koti+Apila","address_postal_full":"PL 41910, 00099 Helsingin kaupunki","address_postal_full_fi":"PL 41910, 00099 Helsingin kaupunki","address_postal_full_sv":"PB 41910, 00099 Helsingfors stad","address_postal_full_en":"P.O. Box 41910, 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":"2","name_fi":"Avoinna läpi kesän 2014"},{"connection_type":"2","name_en":"Open all summer 2014"},{"connection_type":"2","name_sv":"Öppet hela sommaren 2014"},{"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/Vaka/fi/P_iv_kotihoito/Hakeminen","www_sv":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/Hakeminen","www_en":"http://www.hel.fi/hki/Vaka/fi/P_iv_kotihoito/Hakeminen"}],"events":[],"accessibility_sentences":[{"sentence_group_name":"Saattoliikenne","sentence_group_fi":"Reitti pääsisäänkäynnille","sentence_group_sv":"Rutten till huvudingången","sentence_group_en":"The route to the main entrance","sentence_fi":"Saattoliikenteen pysähtymispaikka sijaitsee sisäänkäynnin läheisyydessä (etäisyys enintään 5 metriä), josta sisäänkäynnille 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 pääsisäänkäynnille","sentence_group_fi":"Reitti pääsisäänkäynnille","sentence_group_sv":"Rutten till huvudingången","sentence_group_en":"The route to the main entrance","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":"Pääsisäänkäynti","sentence_group_fi":"Pääsisäänkäynti","sentence_group_sv":"Huvudingången","sentence_group_en":"The main entrance","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":"Pääsisäänkäynti","sentence_group_fi":"Pääsisäänkäynti","sentence_group_sv":"Huvudingången","sentence_group_en":"The main entrance","sentence_fi":"Sisäänkäynnin ovet ovat vaikeasti havaittavat. 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":"Pääsisäänkäynti","sentence_group_fi":"Pääsisäänkäynti","sentence_group_sv":"Huvudingången","sentence_group_en":"The main entrance","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_group_fi":"Sisätilat","sentence_group_sv":"I lokalen","sentence_group_en":"In the facility","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_group_fi":"Sisätilat","sentence_group_sv":"I lokalen","sentence_group_en":"In the facility","sentence_fi":"Sisätilojen 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."}]}

Notice! Data model for unit is different when it is retrieved as a part of collection or a single item. Data model for single item contains more data fields.

AttributeExplanation
idNumeric Id
areal_city_idId for the City where the unit is located
org_idOrganization id
dept_idShort name for the organisaation
org_ownedIs the organization owner of this unit
data_source_urlData source
provider_typeService provider. 100 = Not known, 101 = Municipal service, 102 = Service supported by municipality, 103 = Service by federation of municipalities, 104 = State service, 105 = Private service
service_idsId list of services which this unit offers
sourcesList of source systems of the unit. Each object contains source and id fields
name_fiUnit name in Finnish
name_svUnit name in Swedish
name_enUnit name in English
latitudeLocation of the unit in WGS84 coordinates
longitudeLocation of the unit in WGS84 coordinates
northing_etrs_gk25Location of the unit in ETRS-GK25 coordinates
easting_etrs_gk25Location of the unit in ETRS-GK25 coordinates
manual_coordinatesHas unit coordinates been set manually
desc_fiUnit description in Finnish
desc_svUnit description in Swedish
desc_enUnit description in English
street_address_fiStreet address in Finnish
street_address_svStreet address in Swedish
street_address_enStreet address in English
address_zipZip code
address_city_fiCity name in Finnish
address_city_svCity name in Swedish
address_city_enCity name in English
citydistrict_idId for city district
citydistrict_nameName of the city district
subdistrict_idId for sub district
subdistrict_nameName of the sub district
phonePhone number
faxFax number
emailEmail address
www_fiAddress of the unit's web-site
www_svAddress of the unit's Swedish web-site
www_enAddress of the unit's English web-site
address_postal_fullPostal address
address_postal_full_fiPostal address in Finnish
address_postal_full_svPostal address in Swedish
address_postal_full_enPostal address in English
picture_urlUrl to picture
picture_caption_fiCaption in Finnish
picture_caption_svCaption in Swedish
picture_caption_enCaption in English
connectionsList of connection objects of the unit connections. Each object contains following fields: connection_type, name_fi (sv/en) and www_fi ( sv/en ).
eventsList of event objects of the unit events. Each object contains following fields: id, name_fi (sv/en) and www_fi ( sv/en ).
accessibility_sentencesList of units accessibility sentences. Each object contains following fields: sentence_group_name, sentence_group_fi, sentence_group_sv, sentence_group_en, sentence_fi, sentence_sv and sentence_en.
service_descriptionsList of service descriptions which are related to this unit. Each object contains id and available languages of the service description. Id codes correspond to id codes in the Service Register of the city of Helsinki REST API.

Service

Example object (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":[...]}
AttributeExplanation
idNumeric Id
name_fiService name in Finnish
name_svService name in Swedish
name_enService name in English
child_idsList of service id's from child services.
unit_idsList of unit id's which has this service.

Service tree

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

{"id":25554,"name_fi":"Liikenne","name_sv":"Trafik ","name_en":"Traffic","children":[...]}
AttribuuttiArvon selitys
idNumeric Id
name_fiService name in Finnish
name_svService name in Swedish
name_enService name in English
childrenObject list of child services.

Accessibility parameter

Example object (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"]}
AttributeExplanation
variable_idNumeric Id
variable_nameParameter name
valuesList of possible values

Units accessibility information

Example object (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"}]}
AttributeExplanation
unit_idNumeric Id
accessibility_propertiesList of accessibility_property objects of the unit accessibility_properties. Each object contains following fields: varibale_id, variable_name and value.

Search functionalities

Search parameters can be used to filter result sets in queries which are listing units. Search parameters can also be combined.

Search parameters

organization

Filter units based on the organization that produces information.

Example. Units produced by the Suomi.fi organization: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?organization=1000

department

Filter units based on the department that produces information.

Example. Units of the City Museum and Art Museum of Helsinki: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?department=TAIMU+MUSEO

arealcity

Filter units based on the areal city in which the units are located.

Example. Units located in the city of Kauniainen: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?arealcity=235

service

Filter units based on the service provided by the unit.

Example. Swimming halls and outdoor swimming pools: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?service=28148+28150

search

Filter units based on search keywords.

Example. Day care units in Lauttasaari: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?search=lauttasaari+day+care

lat, lon, distance

Distance search.
Notice: lat and lon parameters can contain max five decimals.

Example. Units 250 meters from the tower of the Kallio church: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?lat=60.18406&lon=24.94936&distance=250

Combining search parameters

Example. Swimming halls 500 meters from the tower of the Kallio church: http://www.hel.fi/palvelukarttaws/rest/v2/unit/?service=28148&lat=60.18406&lon=24.94936&distance=500