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.

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

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

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.

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

Example URLs

Organization

Find All Organizations

Request:

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

Corresponding curl command:

$ curl 'http://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=dc2c86cb-8266-448d-a949-85ef03649ddd HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/department/?organization=dc2c86cb-8266-448d-a949-85ef03649ddd' -i -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

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/1 HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/department/1' -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%EF%BF%BDk%EF%BF%BDintilippuautomaatti HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/unit/?search=Pys%EF%BF%BDk%EF%BF%BDintilippuautomaatti' -i -H 'Accept: application/json'

Request parameters

None of the parameters is compulsory

Parameter Description

organization

Organization Id

department

Department Id

suborganization

To limit the output to a certain sub organization

arealcity

Areal City

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

Find Single Unit by Id

Example Request:

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

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/unit/1' -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/1/accessibility/ HTTP/1.1
Accept: application/json
Host: www.hel.fi

Corresponding curl command:

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

Find Accessibility Shortage of a Single Unit

Example Request:

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

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/unit/1/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 'http://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 'http://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 'http://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 'http://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

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 'http://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 'http://www.hel.fi/palvelukarttaws/rest/v4/arealcity/91' -i -H 'Accept: application/json'

Areal City’s Path Parameters

Table 5. /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 'http://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 'http://www.hel.fi/palvelukarttaws/rest/v4/ontologyword/1' -i -H 'Accept: application/json'

Ontology Word’s Path Parameters

Table 6. /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 'http://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 'http://www.hel.fi/palvelukarttaws/rest/v4/ontologytree/1' -i -H 'Accept: application/json'

Ontology Tree’s Path Parameters

Table 7. /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 'http://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 'http://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 'http://www.hel.fi/palvelukarttaws/rest/v4/accessibility_shortage/' -i -H 'Accept: application/json'

Find All Connections

Request:

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

Corresponding curl command:

$ curl 'http://www.hel.fi/palvelukarttaws/rest/v4/connection/?official=yes' -i -H 'Accept: application/json'