Smart participation work package

API Strat workshop 26.3.2014Jaakko Rajaniemi

City of Helsinki

Issue reporting API in CitySDK

http://www.citysdk.eu/developers/

Issue reporting API

•Based on Open311 (also known as GeoReport v2)•http://open311.org/

•http://dev.hel.fi/apis/issuereporting•Open311 used in more than 30 cities in US and now coming to Europe

“The fence is broken at the square next to the railway

station.”

Citizen reports an issue

Status: Received

fence is broken Received

“The fence is broken at the square next to the railway station.”

“Public works department fixes similar issues on avarage in 5 days.”

Moved to the City’s customer service.Moved to the City’s customer service.

Automatic response sent to the citizen: Automatic response sent to the citizen:

Status: In Process

fence is broken In Process

“The fence is broken at the square next to the railway

station.”

Public works department decides to fix this issuePublic works department decides to fix this issue

Status: Being fixed

fence is broken Being fixed

Stara fiksaaTähän palautetekstiJa status vastauksineen

“The fence is broken at the square next to the railway

station.”

Public works department fixes the fence.

Status: Fixed

Issue has been fixed and a notification is sent to the user.Issue has been fixed and a notification is sent to the user.

fence is broken Fixed

Status: Fixed

“The fence is broken at the square next to the railway

station.”

“The issue you reported has been fixed. “

Issue has been fixed and a notification is sent to the user.Issue has been fixed and a notification is sent to the user.

fence is broken Fixed

Issue reporting API which allows

1. Query service request types and definitions Defines request types and extra attributes

2. Submit service requestDescription, image, location, contact information

3. Query individual service requestStatus and other service request details

4. Query services requestsBased on time and location

Query URL structure1. Query service request types and definitions (HTTP GET)

https://[API endpoint]/services.[format] https://asiointi.hel.fi/palautews/rest/v1/services.json https://[API endpoint]/services/[service_code].[format] https://asiointi.hel.fi/palautews/rest/v1/services/171.json

2. Submit service request (HTTP POST) https://[API endpoint]/requests.[format] https://asiointi.hel.fi/palautews/rest/v1/requests.json

3. Query individual service request (HTTP GET) https://[API endpoint]/requests/[service_request_id].[format] https://asiointi.hel.fi/palautews/rest/v1/requests/2278m9r1a1f50dhb1mug.json

4. Query services requests (HTTP GET)https://[API endpoint]/requests.[format]?querystringhttps://asiointi.hel.fi/palautews/rest/v1/requests.json?status=open

Discovery filehttps://asiointi.hel.fi/palautews/rest/v1/discovery.json

Service request typesand language support

http://311api.cityofchicago.org/open311/v2/services.json

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

http://311api.cityofchicago.org/open311/v2/services/4ffa4c69601827691b000018.json

Service definition

Submitting service requestsParameters

• 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 • lat Latitude using the (WGS84) projection. No • long Longitude using the (WGS84) projection. No • service_object_type (CitySDK) Describes the point of interest reference which is used for identifying the

request object. No

• service_object_id (CitySDK) Identifies the point of interest which feedback is linked No • title (CitySDK) Title of the service requests No• address_string Human readable address or description of location. No • email The email address of the person submitting the request No • 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 • media Array of file uploads No

• Additional attributes Additional attributes defined in service definition No

Lots of ways to query• Last service requests: https://asiointi.hel.fi/palautews/rest/v1/requests.json• Individual service request: https

://asiointi.hel.fi/palautews/rest/v1/requests/2278m9r1a1f50dhb1mug.json?extensions=true• Service requests based on received time:

https://asiointi.hel.fi/palautews/rest/v1/requests.json?extensions=true&start_date=2014-03-18&end_date=2014-03-25

• Service requests based on updated time: https://asiointi.hel.fi/palautews/rest/v1/requests.json?extensions=true&updated_after=2014-03-25T08:03:46+03:00&updated_before=2014-03-26T18:03:46+03:00

• Service requests based on service objects: https://asiointi.hel.fi/palautews/rest/v1/requests.json?service_object_id=26055&service_object_type=http://www.hel.fi/servicemap/v2

– http://www.hel.fi/palvelukarttaws/rest/v2/unit/26055

• Service requests based on service_code:https://asiointi.hel.fi/palautews/rest/v1/requests.json? service_code=171,174

• Service requests based on status:https://asiointi.hel.fi/palautews/rest/v1/requests.json?extensions=true&status=closed

• More queries: https://docs.google.com/document/d/10Ggep6WANy1LJcOSpZ8vOgTertUS0Tkk6IQf3Omvibc/edit?usp=sharingDemos

• http://dev.hel.fi/open311-test/mapviewer.html• http://dev.hel.fi/open311-test/servicemap_new.html

Python Three

• Three is simple open source Open311 client

>>from three import Three

>>t = Three(https://asiointi.hel.fi/palautews/rest/v1/', api_key='API_KEY_HERE')

>>resp = t.post('202', name='Jaakko Rajaniemi', lat='60.168321', long='24.952397', description='Traffic sign is broken.',email='jaakko.rajaniemi@hel.fi', media=open('traffic_sign.jpg', 'rb'))

Over 2500 service requests

Metro

Korjaakaupunki.fi

Sanom.at

What next?Before

After??

Use open data for better reports

http://dev.hel.fi/open311-test/reports_and_areas.html

Thank you!

• Jaakko Rajaniemi jaakko.rajaniemi@hel.fi– City of Helsinki

• @jaakko