CitySDK smart participation API presentation.

1. Smart participation work package
API Strat workshop 26.3.2014
Jaakko Rajaniemi
City of Helsinki

2. Issue reporting API in CitySDK
http://www.citysdk.eu/developers/

3. 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

4. “The fence is broken at the
square next to the railway
station.”
Citizen reports an issue

5. Status: Received
fence is broken
Received

6. “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

7. “The fence is broken at the
square next to the railway
station.”
Public works department
decides to fix this issue
Public works department
decides to fix this issue
Status: Being fixed
fence is broken
Being fixed

8. Stara fiksaaTähän palauteteksti
Ja 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

9. 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

10. Issue reporting API which allows
1.Query service request types and definitions
Defines request types and extra attributes
1.Submit service request
Description, image, location, contact information
1.Query individual service request
Status and other service request details
1.Query services requests
Based on time and location

11. Query URL structure
1. 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
1. Submit service request (HTTP POST)
 https://[API endpoint]/requests.[format]
https://asiointi.hel.fi/palautews/rest/v1/requests.json
1. Query individual service request (HTTP GET)
 https://[API endpoint]/requests/[service_request_id].[format]
 https://asiointi.hel.fi/palautews/rest/v1/requests/2278m9r1a1f50dhb1mug.json
1. Query services requests (HTTP GET)
https://[API endpoint]/requests.[format]?querystring
https://asiointi.hel.fi/palautews/rest/v1/requests.json?status=open

12. Discovery file
https://asiointi.hel.fi/palautews/rest/v1/discovery.json

13. Service request types
and language support
http://311api.cityofchicago.org/open311/v2/services.json
https://asiointi.hel.fi/palautews/rest/v1/services.json?locale=fi_FI

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

15. Submitting service requests
Parameters
• 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

16. 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&en
• 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=ht
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=sharing
Demos
• http://dev.hel.fi/open311-test/mapviewer.html
• http://dev.hel.fi/open311-test/servicemap_new.html

17. 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'))

18. Over 2500 service requests

22. Metro

23. Korjaakaupunki.fi

24. Sanom.at

25. What next?
Before
After??
Use open data for better reports
http://dev.hel.fi/open311-test/reports_and_areas.html

26. Thank you!
• Jaakko Rajaniemi jaakko.rajaniemi@hel.fi
– City of Helsinki
• @jaakko