Issue reporting API specification / Palauterajapinta

General

The issue reporting API is used by applications for sending service request to City of Helsinki. At the moment, API is used for sending service requests about broken street signs, potholes, etc, which are typically handled by the Public Works Department, but the future plan is to use it on other issues as well.

Following functionalities are provided by the API:

  1. Listing of service request types and definitions of the additional attributes
  2. Submitting service requests
  3. Quering individual or multiple service requests and their descriptions and status

The issue reporting API is based on GeoReporting version 2, which is better known as Open311 specification. The interface is designed in such a way that any GeoReporting version 2 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

Testing and API key

Developer applications submitting service request to the feedback system will need API key. All other methods do not require 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 test environment is different than the one used in production. The standard developer workflow would work like this:

  1. Developer requests an API key for the test system
  2. Using the test API key, developer codes and tests their app against the test system
  3. Developer requests an API key for the production system. After city personnel verifies that the app is according to the API terms, the production API key is given to the developer. Reserve 1-2 weeks time for the verification.
  4. Developer's application is deployed using the production system API key and is coded 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 Jaakko Rajaniemi, jaakko.rajaniemi@hel.fi, +358 40 516 5931.

Encoding and formats

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

Language support

Finnish and English languages are supported. In practise, the support 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:

Parameter name Description Required Notes
locale

CitySDK specific

Preferred language No

Locales can be, for example, fi, fi_FI, en, en_GB or en_US. If no locale is given the default value is English.

 Response parameters:

Parameter name Description Required Notes
service_code The unique identifier for the service request type Yes  
service_name The human readable name of the service request type Yes  
description A brief description of the service request type. Yes  
metadata

Determines whether their are additional form fields for this service type.

  • true: This service request type requires additional metadata so the client will need to make a call to the Service Definition method.
  • false: No additional information is required and a call to the Service Definition method is not needed.
Yes At the moment metadata is always set to false.
type

realtime: The service request ID will be returned immediately after the service request is submitted.

Yes At the moment, type is always set to realtime.
keywords A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group. Yes  
group A category to group this service type within. This provides a way to group several service request types under one category such as "sanitation" Yes  

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

Parameter name Description Required Notes
service_code The unique identifier for the service request type. Yes The service_code is specified in the main URL path rather than an added query string parameter.
locale

CitySDK specific

Preferred language No Locales can be, for example, fi, fi_FI, en, en_GB or en_US. If no locale is given the default value is English.

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:

Parameter name Description Required Notes
api_key Api key for submitting service requests Yes  
service_code The unique identifier for the service request type Yes  
description A full description of the service request. Yes This is free form text having min 10 and max 5,000 characters. This may contain line breaks, but not html or code.

title

CitySDK specific

Title of the service requests No
lat Latitude using the (WGS84) projection. No

Currently all service types require location, either lat/long or service_object_id.

long Longitude using the (WGS84) projection. No Currently all service types require location, either lat/long or service_object_id.

service_object_type

CitySDK specific

Describes the point of interest reference which is used for identifying the request object. No If service_object_id is included in the request, then service_object_type must be included.

service_object_id

CitySDK specific

Describes the point of interest reference which is used for identifying the request object. No If service_object_id is included in the request, then service_object_type must be included.
address_string Human readable address or description of location. No  
email The email address of the person submitting the request No If email address is given, service will notify to the email address when service request is processed.
first_name The given name of the person submitting the request No  
last_name The family name of the person submitting the request No  
phone The phone number of the person submitting the request No  
media_url A URL to media associated with the request, e.g. an image No API supports the most typical media formats like jpg, png, gif,.. Note, that URL links must end with a correct filetype like ".jpg", e.g. http://pbs.twimg.com/media/Ay9wUStCEAEtoPC.jpg. Https URLs are not supported at moment.
media Array of file uploads No

A client may POST multiple files as multipart/form-data. This is the equivalent of having multiple <input type="file" name="media[]" /> inputs. Subsequent calls for GET Service Requests should return the URL for this file via the media_urls field. See more on section Uploading media.

 

Response parameters:

Parameter name Description Required Notes
service_request_id The unique ID of the service request created Yes  
service_notice The human readable name of the service request type Yes Currently empty string

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 for 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:

Parameter names Description Required Notes
service_request_id To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited. No This overrides all other arguments.
service_code Specify the service type by calling the unique ID of the service_code. No This defaults to all service codes when not declared; can be declared multiple times, comma delimited
start_date Earliest requested_datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. No Must use W3C format, e.g 2010-01-01T00:00:00Z.
end_date Latest requested_datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. No Must use W3C format, e.g 2010-01-01T00:00:00Z.
status Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited. No  
extensions

CitySDK specific

The endpoint provides supplemental details about service requests that are in addition to the ones described in the standard specification. These data are nested in the 'extended_attributes' parameter in the Service Request response. In order to retrieve the new supplemental details, add the query parameter “extensions=true” to the request No See chapter on Extensions.
service_object_type

CitySDK specific

Describes the point of interest reference which is used for identifying the request object. No See chapter on Service Objects.
service_object_id

CitySDK specific

Describes the ID of the service object No If service_object_id is included in the request, then service_object_type must be included.
lat

CitySDK specific

Latitude No Location based search if lat, long and radius are given.
long

CitySDK specific

Longitude No Location based search if lat, long and radius are given.
radius

CitySDK specific

Radius (meters) in which location based search performed. No Location based search if lat, long and radius are given.
updated_after

CitySDK specific

Earliest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and updated_before time (or now). This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes. No Must use w3 format, eg 2010-01-01T00:00:00Z.
updated_before

CitySDK specific

Latest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and the updated_before time. This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes. No When not specified (updated_after is used without updated_before) then updated_before is assumed to be now. Must use w3 format, eg 2010-01-01T00:00:00Z.

Response Parameters:

Parameter names Description Required Notes
service_request_id The unique ID of the service request created. Yes  
status_notes

Explanation of why status was changed to current state or more details on current status than conveyed with status alone

Yes  
status

The current status of the service request.

  • open: it has been reported.
  • closed: it has been resolved.
Yes  
service_code The unique identifier for the service request type Yes  
service_name The human readable name of the service request type No  
description A full description of the request or report submitted. Yes  
agency_responsible The agency responsible for fulfilling or otherwise addressing the service request. No  
service_notice Information about the action expected to fulfill the request or otherwise address the information reported. No Empty string
requested_datetime The date and time when the service request was made. No Must use W3C format, e.g 2010-01-01T00:00:00Z.
updated_datetime The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. No Must use W3C format, e.g 2010-01-01T00:00:00Z.
expected_datetime The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. No No available. Must use W3C format, e.g 2010-01-01T00:00:00Z.
address Human readable address or description of location. No  
lat latitude using the (WGS84) projection. Yes Currently all service types require location, either lat/long or service_object_id.
long longitude using the (WGS84) projection. Yes Currently all service types require location, either lat/long or service_object_id.
media_url A URL to media associated with the request, eg an image. No Contains only one of these elements.
service_object_type

CitySDK specific

Nested in extended_attributes field (extended_attributes.service_object_type). Describes the point of interest reference which is used for identifying the request object.

No See chapter on Service Objects.
service_object_id

CitySDK specific

Nested in extended_attributes field (extended_attributes service_object_id). Describes the ID of the service object. No If service_object_id is included in the request, then service_object_type must be included.
detailed_status

CitySDK specific

Nested in extended_attributes field (extended_attributes.detailed_status) describes detailed. No This can contain multiple status values; comma delimited. See more on section Detailed status of service requests.
media_urls

CitySDK specific

Nested in extended_attributes field (extended_attributes.media_urls) contains URLs to media associated with the request. No The values is array of strings.

Response Volume

Default query limit is a span of 90 days or first 1000 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 for 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:

Parameter names Description Required Notes
service_request_id Unique id of the service request Yes The service_request_id is specified in the main URL path rather than an added query string parameter.
extensions

CitySDK specific

Helsinki endpoint provides supplemental details about service requests that are in addition to the ones described in the Open311 specification. These data are nested in the 'extended_attributes' field in the response. In order to retrieve the new supplemental details, add the query parameter “extensions=true” to any request. See more in No

Options: true, false. Defaults to false. See more on Extensions chapter.

Response Parameters:

Parameter names Description Required Notes
service_request_id Unique id of the service request Yes The service_request_id is specified in the main URL path rather than an added query string parameter.
status_notes Explanation of why status was changed to current state or more details on current status than conveyed with status alone. Yes  
service_name The human readable name of the service request type Yes Empty string
service_code The unique identifier for the service request type Yes  
status

The current status of the service request.

  • open: it has been reported.
  • closed: it has been resolved.
Yes  
description A full description of the request or report submitted. Yes  
agency_responsible The agency responsible for fulfilling or otherwise addressing the service request. No Empty string
service_notice Information about the action expected to fulfill the request or otherwise address the information reported. No Empty string
requested_datetime The date and time when the service request was made. Yes Must use W3C format, e.g 2010-01-01T00:00:00Z.
updated_datetime The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. Yes Must use W3C format, e.g 2010-01-01T00:00:00Z.
expected_datetime The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. No Not available. Must use W3C format, e.g 2010-01-01T00:00:00Z.
address Human readable address or description of location. No  
lat latitude using the (WGS84) projection. No Currently all service types require location, either lat/long or service_object_id.
long longitude using the (WGS84) projection. No Currently all service types require location, either lat/long or service_object_id.
media_url A URL to media associated with the request, eg an image. No May contain more than one of these elements. This feature is coming soon.
service_object_type

CitySDK specific

Nested in extended_attributes field (extended_attributes.service_object_type). Describes the point of interest reference which is used for identifying the request object.

No See chapter on Service Objects.
service_object_id

CitySDK specific

Nested in extended_attributes field (extended_attributes.service_object_id) describes the ID of the object e.g. public toiled in Helsinki Esplanade park  ID = 10844. No

If service_object_id is included, then service_object_type must be also included. See chapter on Service Objects.

detailed_status

CitySDK specific

Nested in extended_attributes parameters (extended_attributes. detailed_status) describes detailed status of the service request. No This can contain multiple status values; comma delimited. See more on Detailed status of service requests chapter
media_urls

CitySDK specific

Nested in extended_attributes field (extended_attributes.media_urls) contains URLs to media associated with the request. No The values is array of strings.

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ä. \n\nLisä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.\n\nTerveisin\nRakennusviraston asiakaspalvelu\n",
    "lat": "60.21263634325148",
    "long": "25.077090230550745",
    "extended_attributes": {
        "title": "Monttu tiessä",
        "detailed_status": "PROCESSED"
    }
  }
]

Error messages

Parameter name Description Required Notes
code The error code representing the type of error. In most cases, this should match the HTTP status code returned in the HTTP header. Yes  
description A human readable description of the error that occurred. This is meant to be seen by the user. Yes  

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 city's issue reporting system, it is not automatically shown publicly in the search results. Each service request is moderated and only when it is published, the service request is visible in the search results.

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)

Service request may contain reference to Helsinki metropolitan area service map unit, i.e. service object. Service object is typically a unit item from the 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:

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

Detailed status of service requests (detailed_status)

The status of each service request is transferred in status parameter. Status can have only values “open” or “closed”. Parameter detailed_status parameter is comma separated list of detailed status values  of the service request.

For interoperability purpose set of detailed status values are specified:

  • RECEIVED – service request is received but nothing is done it. Status field value is open.
  • IN_PROCESS - service request is received and its handling has been started. Status field value is open.
  • PROCESSED - service request has been resolved. Status field value is closed.
  • ARCHIVED - service request has been resolved and archived. Status field value is closed. (Not used in Helsinki)
  • REJECTED -service request has been rejected. Status field value is closed. (Not used in Helsinki)

If a service request is forwarded to Public Works department's Aspa system, its Aspa status is included in the detailed_status parameter. It can have following values:

  • PUBLIC_WORKS_NEW – service request is received but nothing is done it.
  • PUBLIC_WORKS_IN_PROGRESS - service request is been handled by Public Works department.
  • PUBLIC_WORKS_COMPLETED- service request has been resolved.
  • PUBLIC_WORKS_COMPLETED_SCHEDULED_LATER- service request has been resolved and done later. (coming soon!)
  • PUBLIC_WORKS_COMPLETED_REQUIRES_NO_ACTION- service request requires no action. (coming soon!)
  • PUBLIC_WORKS_INTERRUPTED- service request interrupted and no action done. (coming soon!)

Example response:

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

Uploading media

Uploading of media files like images is supported two ways. POST Service Request can reference to image with media_url parameter or media can be uploaded directly as multipart/form-data.

More than one image is supported. If applications send more than one image, special care should be taken on the application side, because of the long upload time. It is also possible to upload using media_url reference and directly multipart/form-data in one shot.

Example of uploading image as multipart/form-data

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

Example response

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

Applications using API

These applications use the API already:

Frequently asked questions

Frequently asked question FAQ is here.