dev.hel.fi

The issue reporting API is used by applications for sending service requests to the City of Helsinki.

At the moment, the API is mostly used for sending service requests about broken parts of city infrastructure like street signs, potholes, etc. These kinds of service requests are typically handled by the Public Works Department. However, the API is increasingly used for other types of feedback as well.

The API enables its clients to:

1. Submit new service requests
2. Query individual or multiple service requests and their descriptions and statuses
3. List service request types and definitions of additional attributes

The Issue Reporting API is based on GeoReport API version 2, better known as the Open311 specification. The interface is designed in such a way that any GeoReport v2 compatible client is able to use the interface. This interface is compliant with CitySDK specific enhancements to Open311 and parameters specific to it are marked CitySDK specific.

Helsinki specific details

API keys and testing

Client applications submitting new service requests to the feedback system will need an API key. None of the other methods require an API key.

The City of Helsinki has a separate environment and URL for testing developer applications (test system) before connecting them to the production system (https://asiointi.hel.fi/palautews/rest/v1/). The API key developers use in the test environment is different than the one used in production. The standard developer workflow goes like this:

1. The developer requests an API key for the test system.
2. Using the test API key, the developer implements and tests their client against the test system.
3. The developer requests an API key for the production system. After city personnel has verified that the client conforms to the API terms, the production API key is created and given to the developer. Reserve 1-2 weeks for the verification.
4. The developer's application is deployed using the production system API key and is tested against the production system.

The use of API is subject to following terms: Terms of Service / Käyttöehdot ja lisenssi.

For test and production system API keys contact Timo Tuominen, timo.tuominen@hel.fi, +358 9 310 25495.

Encoding and formats

UTF-8 is required everywhere. The API supports both XML and JSON.

Language support

Finnish and English are supported. In practice, this means that the service request types (GET Service List) can be queried by those languages.

API Methods

GET Service List

Provides a list of acceptable service request types and their associated service codes.

• URL address: https://asiointi.hel.fi/palautews/rest/v1/services.[format].
• Example URL: https://asiointi.hel.fi/palautews/rest/v1/services.json
• Requires API key: No
• Method: GET

Request Parameters:

 Response parameters:

Possible errors

The numbers represent the HTTP status code returned for each error type:

• 400 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)

Example request:

https://asiointi.hel.fi/palautews/rest/v1/services.json?locale=fi_FI

Example response:

[ 
  {
    "service_code": "246",
    "service_name": "Roskaaminen",
    "description": "Ilmoita, jos havaitset suuria määriä roskia yleisillä alueilla, puistoissa tai metsissä.",
    "metadata": false,
    "type": "realtime",
    "keywords": "roska,jäte",
    "group": "Puhtaanapito"
   },
   {
    "service_code": "176",
    "service_name": "Töhryjen poisto",
    "description": "Ilmoita, jos paikkoja tai seiniä on töhritty.",
    "metadata": false,
    "type": "realtime",
    "keywords": "roska,jäte",
    "group": "Puhtaanapito"
    }
 ]

GET Service Definition

Define attributes associated with a service code. At the moment, there are no attributes defined in Helsinki API and therefore no use for this method.

• URL address: https://asiointi.hel.fi/palautews/rest/v1/services/[service code].[format].
• Example URL: https://asiointi.hel.fi/palautews/rest/v1/services/246.json
• Requires API key: No
• Method: GET

Request parameters

Response parameters

TODO

POST Service Request

This method is used for sending service requests to the city's feedback system.

• URL: https://asiointi.hel.fi/palautews/rest/v1/requests.[format]
• Example URL: https://asiointi.hel.fi/palautews/rest/v1/requests.json
• Posting formats: Content-Type application/x-www-form-urlencoded or multipart/form-data
• Requires API key: YES
• HTTP Method POST

Request parameters:

Response parameters:

Possible errors

The numbers represent the HTTP status code returned for each error type:

• 404 - service_code or jurisdiction_id was not found (specified in error response)
• 400 - General Service Error. Any failure during create request processing, e.g. API service is down.

Example request:

POST /palautews/rest/v1/requests.json
Host: asiointi.hel.fi
Content-Type: application/x-www-form-urlencoded; charset=utf-8

api_key=xyz&service_code=001&lat=37.76524078&long=122.4212043&address_string=Unioninkatu 25
&email=jaakko.rajaniemi%40hel.fi&first_name=Jaakko&last_name=Rajaniemi&phone=111111111&
description=Large+sinkhole+is+destroying+the+street &media_url=http%3A%2F%2Ffarm3.static.flickr.com%2F2002%2F225ed4760.jpg

Example response:

[
  {
    "service_request_id":"8fmht6g1470b3qk8pthg",
    "service_notice":""
  }
]

GET Service Requests

This method is used to query the current status of multiple requests.

• URL: https://[API endpoint]/requests.[format]
• Example URL: https://asiointi.hel.fi/palautews/rest/v1/requests.xml?start_date=2010-05-24T00:00:00Z&end_date=2010-06-24T00:00:00Z&status=open
• HTTP Method GET

Request Parameters:

Response Parameters:

Response Volume

The default query limit is a span of 90 days or first 200 requests returned, whichever is smallest.

Possible errors

The numbers represent the HTTP status code returned for each error type:

• 404 - service_code or jurisdiction_id was not found (specified in error response)
• 400 - General Service Error. Any failure during create request processing, e.g. API service is down.

Example Request

https://asiointi.hel.fi/palautews/rest/v1/requests.json?start_date=2013-04-24T00:00:00Z&end_date=2013-05-24T00:00:00Z

Example Response

[
   {
      "service_request_id": "8fmht6g1470b3qk8pthg",
      "service_code": "171",
      "description": "Itäkeskuksen uimahallin edessä kadulla on monttuja ajotiessä.",
      "service_notice": "",
      "requested_datetime": "2013-05-02T11:02:07+03:00",
      "updated_datetime": "2013-05-02T15:32:29+03:00",
      "status": "open",
      "status_notes": "",
      "agency_responsible": "",
      "service_name": "",
      "address": "",
      "address_id": "",
      "zip_code": "",
      "lat": "60.21263634325148",
      "long": "25.077090230550745"
    },
{
      "service_request_id": "1ju4p6v3e04pcpobfv7u",
      "service_code": "178",
      "description": "Tilapäiset merkit voisi ihan hyvin sijoittaa Lautatarhankatu ja Hämeentie kauppakeskus Arabian kohdalla.",
      "service_notice": "",
      "requested_datetime": "2013-04-30T10:52:55+03:00",
      "updated_datetime": "2013-05-01T14:35:01+03:00",
      "status": "closed",
      "status_notes": "Kiitos ilmoituksestanne. Olen välittänyt asian alueen tarkastajalle, joka valvoo tilapäisiä liikennejärjestelyjä ja kaivauksia.",
      "agency_responsible": "",
      "service_name": "",
      "address": "",
      "address_id": "",
      "zip_code": "",
      "lat": "60.189587726063884",
      "long": "24.966438613848045"
    }
]

GET Service Request

This method is used to query the current status of multiple requests.

• URL: https://asiointi.hel.fi/palautews/rest/v1/requests/[service_request_id].[format]
• Example URL: https://asiointi.hel.fi/palautews/rest/v1/requests/1ju4p6v3e04pcpobfv7u.json
• HTTP Method GET

Request Parameters:

Response Parameters:

Possible errors

The numbers represent the HTTP status code returned for each error type:

• 404 - service_code or jurisdiction_id was not found (specified in error response)
• 400 - General Service Error. Any failure during create request processing, e.g. API service is down.

Example Request

https://asiointi.hel.fi/palautews/rest/v1/requests/8fmht6g1470b3qk8pthg.json?extensions=true

Example Response

[ 
   {
    "service_request_id": "8fmht6g1470b3qk8pthg",
    "service_code": "171",
    "description": "Itäkeskuksen uimahallin edessä kadulla on monttuja ajotiessä. 

Lisätietoa: http://metro.fi/paakaupunkiseutu/fiksaus/monttu_tiessa.4/",
    "requested_datetime": "2013-05-02T11:02:07+03:00",
    "updated_datetime": "2013-05-15T08:55:09+03:00",
    "status": "closed",
    "status_notes": "Kiitos ilmoituksestanne. Olemme välittäneet korjauspyynnön alueen katujen kunnossapitoon.

Terveisin
Rakennusviraston asiakaspalvelu
",
    "lat": "60.21263634325148",
    "long": "25.077090230550745",
    "extended_attributes": {
        "title": "Monttu tiessä",
        "detailed_status": "PROCESSED"
    }
  }
]

Error messages

General error:

• 403 – Missing or Invalid API Key (specify in error message)
• 400 – The URL request is invalid or service is not running or reachable. Client should notify us after checking URL

Example Error

HTTP/1.1 403 Forbidden

[
  {
    "code":403,
    "description":"Missing or invalid API key.",
  }
]

Moderation of Service Requests

When a service request is posted to the city's issue reporting system, it is not yet shown publicly in the API's service request listings. Each service request is pre-moderated and only after publishing is the service request visible through the API's listing views.

Before the service request is moderated, the service request details are visible and can be queried by using the service_request_id.

Service Objects (service_object_type, service_object_id)

A service request may contain a reference to a service point using the field service_object_id. These represent service points in the Helsinki metropolitan area service map.

Public toilet in Helsinki service map:

• service_object_id=10844
• service_object_type=http://www.hel.fi/servicemap/v2

Extensions (extended_attributes)

A set of Helsinki specific extensions are carried nested inside extended_attributes parameter. In order to retrieve the new extended attributes in the response, add the query parameter “extensions=true” to the request. The list of parameters are:

• title, feedback system's human readable title for the service request. The value is same as the title parameter given in POST Service Request or if not present the title is shortened from description text.
• service_object_id, see more on Service Objects chapter.
• service_object_type, see more on Service Objects chapter.
• detailed_status, see more at the Detailed status of service requests chapter.

{
"extended_attributes": { 
    "service_object_id": "10844", 
    "title": "Broken toilet", 
    "service_object_type": "http://www.hel.fi/servicemap/v2", 
    "detailed_status": "PROCESSED"
} 

{
"extended_attributes": {  
    "detailed_status": "IN_PROCESS,PUBLIC_WORKS_NEW"
} 

POST /dev/v2/requests.json
Host: api.hel.fi
Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="api_key"

xyzfskldlkfh823y49823
--AaB03x
Content-Disposition: form-data; name="service_code "

001
--AaB03x
Content-Disposition: form-data; name="lat"

60.168569
--AaB03x
Content-Disposition: form-data; name="lon"

24.950627
--AaB03x
Content-Disposition: form-data; name="description"

There is a huge pothole in her
--AaB03x
Content-Disposition: form-data; name="first_name "

John
--AaB03x

Content-Disposition: form-data; name="last_name "

Smith
--AaB03x
Content-Disposition: form-data; name="phone"

0503391387
--AaB03x
Content-Disposition: form-data; name="email"

john.smith@gmail.com
--AaB03x
Content-Disposition: form-data; name="media[]"; filename="image.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary

...contents of image.gif...
--AaB03x

[
    {
        "service_request_id": "2g8rlg8ricmctfo21agm",
        "service_notice": ""
    }
]