REST API for City of Helsinki Service Map, Version 4

Introduction

This is the 4th version of the REST API for City of Helsinki Service Map and it provides wider functionalities to access data. Main focus in the fourth 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.

We welcome feedback on the interface and on how you utilise the interface in your projects. You can send your feedback by e-mail to henna.niemi@hel.fi and kati.seppala@hel.fi.

Data provided by the REST API

The REST API provides following data:

Organizations that provide information (e.g. cities and the State of Finland)
Departments that maintain units (e.g. The Department of Social Services and Health Care, Helsinki)
Areal cities in which units are located (e.g. Helsinki, Espoo, Vantaa)
Units which provide services (e.g. Rikhardinkatu Library)
Services (ontology words) that are provided by units
Ontology tree composed by services (ontology words) in hierarchy
Accessibility parameters (e.g. INTERIOR.ACCESSIBLE_WC.existing, INTERIOR.ACCESSIBLE_WC.DOOR.easy_to_open_and_close)
Accessibility information of the units (e.g. INTERIOR.ACCESSIBLE_WC.existing = true, INTERIOR.ACCESSIBLE_WC.DOOR.easy_to_open_and_close = false)

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

https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/

The HTTP request above returns information about all areal cities 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 specifications of the individual queries below.

Request to get one item

https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/91

The HTTP request above returns information about one areal city (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: https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/91?callback=foo

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

Example: https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/?format=xml

Example URLs

Address to retrieve organizations: https://www.hel.fi/palvelukarttaws/rest/v4/organization/
Address to retrieve departments: https://www.hel.fi/palvelukarttaws/rest/v4/department/
Address to retrieve areal cities: https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/
Address to retrieve units: https://www.hel.fi/palvelukarttaws/rest/v4/unit/
Address to retrieve ontology words: https://www.hel.fi/palvelukarttaws/rest/v4/ontologyword/
Address to retrieve ontology tree: https://www.hel.fi/palvelukarttaws/rest/v4/ontologytree/
Address to retrieve accessibility parameters: https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_variable/
Address to retrieve accessibility information of the unit: https://www.hel.fi/palvelukarttaws/rest/v4/unit/31/accessibility/

Organization

Find All Organizations

Request:

GET /palvelukarttaws/rest/v4/organization/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/organization/' -i \
    -H 'Accept: application/json'

Department

Filter Departments

Without any request parameters, all departments are returned

Example Request:

GET /palvelukarttaws/rest/v4/department/?organization=83e74666-0836-4c1d-948a-4b34a8b90301 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/department/?organization=83e74666-0836-4c1d-948a-4b34a8b90301' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`organization`	Organization Id
`suborganization`	To limit the output to a certain sub organization

organization

Organization Id

suborganization

To limit the output to a certain sub organization

Find Single Department by Id

Example Request:

GET /palvelukarttaws/rest/v4/department/cc70d1d8-3ca7-416a-9ea7-27e6b7ce58a8 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/department/cc70d1d8-3ca7-416a-9ea7-27e6b7ce58a8' -i \
    -H 'Accept: application/json'

Path parameters

Table 1. /palvelukarttaws/rest/v4/department/{departmentId}
Parameter	Description
`departmentId`	Department Id

Unit

Filter Units

Without any request parameters, all published units are returned

Example Request:

GET /palvelukarttaws/rest/v4/unit/?search=Pys%C3%A4k%C3%B6intilippuautomaatti HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit/?search=Pys%C3%A4k%C3%B6intilippuautomaatti' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`organization`	Organization Id
`department`	Department Id
`suborganization`	To limit the output to a certain sub organization
`arealcity`	Areal City (in which municipality is the unit located)
`search`	Search Keywords (can be multiple, in which case are delimited by + sign)
`ontologyword`	Ontology Word Ids (can be multiple, in which case are delimited by + sign)
`ontologytree`	Ontology Tree Ids (can be multiple, in which case are delimited by + sign)
`lon`	Used together with 'lat' and 'distance'. Geographical longitude
`lat`	Used together with 'lon' and 'distance'. Geographical latitude
`distance`	Used together with 'lon' and 'lat'. Given the geographical location with the given latitude and longitude, filter units within this distance in meters
`description`	To limit the output to units linked to a certain description id (see the service register query vpalvelurekisteri/description)
`newfeatures=yes`	Modifies the output by appending five additional structures: - Areal City (in which municipality is the unit located) - Service owner fields (displayed_service_owner_type, displayed_service_owner_fi/sv/en) - Provided Languages (languages spoken in the unit) - Regions (administrative regions, such as municipality codes, whose citizens are served) - Building info (vtj_prt, vtj_prt_verified)
`ontologyworddetails=yes`	Modifies the output by appending additional information on educational ontology words (school years, detailed curriculum)
`connectionmode=separateopeninghourfield`	Has an influence when querying Single Unit: in the Connection structure, reveals connection id codes and opening hours as separate fields

organization

Organization Id

department

Department Id

suborganization

To limit the output to a certain sub organization

arealcity

Areal City (in which municipality is the unit located)

search

Search Keywords (can be multiple, in which case are delimited by + sign)

ontologyword

Ontology Word Ids (can be multiple, in which case are delimited by + sign)

ontologytree

Ontology Tree Ids (can be multiple, in which case are delimited by + sign)

lon

Used together with 'lat' and 'distance'. Geographical longitude

lat

Used together with 'lon' and 'distance'. Geographical latitude

distance

Used together with 'lon' and 'lat'. Given the geographical location with the given latitude and longitude, filter units within this distance in meters

description

To limit the output to units linked to a certain description id (see the service register query vpalvelurekisteri/description)

newfeatures=yes

Modifies the output by appending five additional structures:
- Areal City (in which municipality is the unit located)
- Service owner fields (displayed_service_owner_type, displayed_service_owner_fi/sv/en)
- Provided Languages (languages spoken in the unit)
- Regions (administrative regions, such as municipality codes, whose citizens are served)
- Building info (vtj_prt, vtj_prt_verified)

ontologyworddetails=yes

Modifies the output by appending additional information on educational ontology words (school years, detailed curriculum)

connectionmode=separateopeninghourfield

Has an influence when querying Single Unit: in the Connection structure, reveals connection id codes and opening hours as separate fields

Find Single Unit by Id

Example Request:

GET /palvelukarttaws/rest/v4/unit/31 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit/31' -i \
    -H 'Accept: application/json'

Path parameters

Table 2. /palvelukarttaws/rest/v4/unit/{unitId}
Parameter	Description
`unitId`	Unit Id

Find Accessibility of a Single Unit

Example Request:

GET /palvelukarttaws/rest/v4/unit/31/accessibility/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit/31/accessibility/' -i \
    -H 'Accept: application/json'

Find Accessibility Shortage of a Single Unit

Example Request:

GET /palvelukarttaws/rest/v4/unit/31/accessibility_shortage/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit/31/accessibility_shortage/' -i \
    -H 'Accept: application/json'

Accessibility Variable

Find All Accessibility Variables

Request:

GET /palvelukarttaws/rest/v4/accessibility_variable/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_variable/' -i \
    -H 'Accept: application/json'

Find Single Accessibility Variable by Id

Example Request:

GET /palvelukarttaws/rest/v4/accessibility_variable/1 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_variable/1' -i \
    -H 'Accept: application/json'

Accessibility Variable’s Path Parameters

Table 3. /palvelukarttaws/rest/v4/accessibility_variable/{variableId}
Parameter	Description
`variableId`	Accessibility Variable Id

Accessibility Viewpoint

Find All Accessibility Viewpoints

Request:

GET /palvelukarttaws/rest/v4/accessibility_viewpoint/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_viewpoint/' -i \
    -H 'Accept: application/json'

Find Single Accessibility Viewpoint by Id

Example Request:

GET /palvelukarttaws/rest/v4/accessibility_viewpoint/11 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_viewpoint/11' -i \
    -H 'Accept: application/json'

Accessibility Viewpoint’s Path Parameters

Table 4. /palvelukarttaws/rest/v4/accessibility_viewpoint/{viewpointId}
Parameter	Description
`viewpointId`	Accessibility Viewpoint Id

Accessibility Question

Find All Accessibility Questions

Request:

GET /palvelukarttaws/rest/v4/accessibility_question/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_question/' -i \
    -H 'Accept: application/json'

Find Single Accessibility Question by Id

Example Request:

GET /palvelukarttaws/rest/v4/accessibility_question/15 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_question/15' -i \
    -H 'Accept: application/json'

Accessibility Question’s Path Parameters

Table 5. /palvelukarttaws/rest/v4/accessibility_question/{questionId}
Parameter	Description
`questionId`	Accessibility Question Id

Accessibility Place

Find All Accessibility Places

Request:

GET /palvelukarttaws/rest/v4/accessibility_place/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_place/' -i \
    -H 'Accept: application/json'

Find Single Accessibility Place by Id

Example Request:

GET /palvelukarttaws/rest/v4/accessibility_place/6 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_place/6' -i \
    -H 'Accept: application/json'

Accessibility Place’s Path Parameters

Table 6. /palvelukarttaws/rest/v4/accessibility_place/{placeId}
Parameter	Description
`placeId`	Accessibility Place Id

Areal City

Find All Areal Cities

Request:

GET /palvelukarttaws/rest/v4/arealcity/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/' -i \
    -H 'Accept: application/json'

Find Single Areal City by Id

Example Request:

GET /palvelukarttaws/rest/v4/arealcity/91 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/arealcity/91' -i \
    -H 'Accept: application/json'

Areal City’s Path Parameters

Table 7. /palvelukarttaws/rest/v4/arealcity/{arealcityId}
Parameter	Description
`arealcityId`	Areal City Id

Ontology Word

Find All Ontology Words

Request:

GET /palvelukarttaws/rest/v4/ontologyword/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/ontologyword/' -i \
    -H 'Accept: application/json'

Find Single Ontology Word by Id

Example Request:

GET /palvelukarttaws/rest/v4/ontologyword/1 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/ontologyword/1' -i \
    -H 'Accept: application/json'

Ontology Word’s Path Parameters

Table 8. /palvelukarttaws/rest/v4/ontologyword/{ontologyWordId}
Parameter	Description
`ontologyWordId`	Ontology Word Id

Ontology Tree

Find All Ontology Trees

Request:

GET /palvelukarttaws/rest/v4/ontologytree/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/ontologytree/' -i \
    -H 'Accept: application/json'

Find Single Ontology Tree by Id

Example Request:

GET /palvelukarttaws/rest/v4/ontologytree/1 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/ontologytree/1' -i \
    -H 'Accept: application/json'

Ontology Tree’s Path Parameters

Table 9. /palvelukarttaws/rest/v4/ontologytree/{ontologyTreeId}
Parameter	Description
`ontologyTreeId`	Ontology Tree Id

Massive Queries

Find All Accessibility Properties

Request:

GET /palvelukarttaws/rest/v4/accessibility_property/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_property/' -i \
    -H 'Accept: application/json'

- - -

Find All Accessibility Sentences

Request:

GET /palvelukarttaws/rest/v4/accessibility_sentence/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_sentence/' -i \
    -H 'Accept: application/json'

- - -

Find All Accessibility Shortages

Request:

GET /palvelukarttaws/rest/v4/accessibility_shortage/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/accessibility_shortage/' -i \
    -H 'Accept: application/json'

- - -

Find All Connections

Request:

GET /palvelukarttaws/rest/v4/connection/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/connection/' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`connectionmode=separateopeninghourfield`	Reveals connection id codes and opening hours as separate fields

connectionmode=separateopeninghourfield

Reveals connection id codes and opening hours as separate fields

- - -

Find All Ontology Word Details of Units

Request:

GET /palvelukarttaws/rest/v4/ontologyword_details/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/ontologyword_details/' -i \
    -H 'Accept: application/json'

- - -

Find All Descriptions of Units

Request:

GET /palvelukarttaws/rest/v4/unit_description/?municipality=91 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit_description/?municipality=91' -i \
    -H 'Accept: application/json'

Request parameter

The parameter is compulsory

Parameter Description

Parameter	Description
`municipality`	Municipality Code (by default 91, that is, City of Helsinki)

municipality

Municipality Code (by default 91, that is, City of Helsinki)

- - -

Find All Unit Properties

Request:

GET /palvelukarttaws/rest/v4/unit_property/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit_property/' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`unit`	Unit Id
`organization`	Organization Id
`department`	Department Id
`arealcity`	Areal City (in which municipality is the unit located)

unit

Unit Id

organization

Organization Id

department

Department Id

arealcity

Areal City (in which municipality is the unit located)

- - -

Find All Accessibility Question Choices of Units

Request:

GET /palvelukarttaws/rest/v4/unit_accessibility_choice/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit_accessibility_choice/' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`unit`	Unit Id
`organization`	Organization Id
`department`	Department Id
`arealcity`	Areal City (in which municipality is the unit located)

unit

Unit Id

organization

Organization Id

department

Department Id

arealcity

Areal City (in which municipality is the unit located)

- - -

Find All Accessibility Place Entries of Units

Request:

GET /palvelukarttaws/rest/v4/unit_accessibility_place/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/unit_accessibility_place/' -i \
    -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

Parameter	Description
`unit`	Unit Id
`organization`	Organization Id
`department`	Department Id
`arealcity`	Areal City (in which municipality is the unit located)

unit

Unit Id

organization

Organization Id

department

Department Id

arealcity

Areal City (in which municipality is the unit located)

- - -

Find All Entrances of Units

Request:

GET /palvelukarttaws/rest/v4/entrance/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'https://www.hel.fi/palvelukarttaws/rest/v4/entrance/' -i \
    -H 'Accept: application/json'

Entrance’s Path Parameters

Table 10. /palvelukarttaws/rest/v4/entrance/{entranceId}
Parameter	Description
`entranceId`	Entrance Id