The City of Ottawa supports the use of the Open311 GeoReport v2 standard. Information on Open311 can be found at Open311.org and the Open311 GeoReport v2 Specification Wiki. The following documentation is intended to support developers in working with this specification by describing what aspects of the specification are and are not supported, as well some specific nuances to this API specification for the City of Ottawa.
Select Service Requests of the following types are currently available:
- Solid Waste
- Roads Maintenance
- Graffiti
- By-law
- Parks and Forestry
- Parking
- Street lighting
Development Process
Applications that are built using the Open311 GeoReport v2 Standard for the City of Ottawa should be tested using the following:
Note that the test API does not create cases in a back-end system and should be used to test API responses only.
A test key is available for the development POST service for those that do not have a production key. Use this key: upxH1uGMCboY3qrXKGRmKWdYaxhaGiDr
In order to secure the City’s back-end systems, applications will require the use of an API key for every request in production. Fill out the registration form in order to obtain an API key.
When applications are ready for production, they should use the following:
There should be no testing in production. All parameters and application features should be tested in development before requesting a key and going live. However, if there is a specific reason where a testing needs to be done in production such as a landing test key holder must do the following:
- Key holders (or developers) must notify SOWeb@ottawa.ca of their testing plan (date and time, service requests to be submitted)
- SOWeb@ottawa.ca will confirm the plan is approved
- Key holders are to use the following values in their test cases:
- First name: Test
- Last Name: Test
- Client address id: __9BQ1OJ
- Address: 100 CONSTELLATION DR, NEPEAN K2G6J8
- Telephone: 6135802424
- Email: testing@ttawa.ca
- Description: Test case please close
- Key holders are to notify SOWeb@ottawa.ca when the cases have been successfully submitted.
Application Requirements
To ensure the delivery of City services and to promote a positive experience for users of third party applications the City requires that developers meet certain mandatory requirements. Access privileges to API services and Data are granted at the sole discretion of the City and may be restricted or terminated at any time as per the Terms of Service.
Mandatory developer requirements
- Third party applications must disclose their privacy statement to users.
- In order to obtain an API key, Developers must provide their contact information. The City reserves the right to share and/or publish this information and will divert all inquiries about third party applications to the developer.
- Applications must submit the client/reporters contact information, including name, address, and email address to the City, where this information is mandatory. Any applications found to be submitting values that were not collected from the user, e.g. default contact information, will have their API key revoked.
- The use City of Ottawa trademarks, including logos, etc. is strictly prohibited.
Recommended developer requirements
- Applications should use the Statuses provided by the City when tracking service requests
- Applications should consider both French and English user interfaces
- Applications should consider Accessibility in interface design, including the guidelines provided by the W3C (WCAG AA).In order to ensure traceability for users who follow-up on their service request with the City directly, applications should provide the service request ID issued by the City to users. This does not preclude application from providing the user with its own tracking number in addition to the City’s service request ID.
Open311 GeoReport v2 Specification and the City of Ottawa
Service Discovery
The base URL for Service Discovery for the City of Ottawa is as follows:
Format Support
The City of Ottawa supports both XML and JSON formatting.
Definitions and Miscellany
jurisdiction_id
The City of Ottawa ignores the “jurisdiction_id” parameter.
Language Support
The City of Ottawa supports both official languages in the API; when used, a request header parameter of “Locale” with the value of “en-CA” or “fr-CA” will take precedence over the default “Accept-Language” header. If the “Locale” request header is not present, the portal will fall back to the user’s default “Accept-Language” header; if no header information is present, the Locale will be set to “en-CA.”
Field Sizes
The Open311 GeoReport v2 Specification does not enable the specification of field sizes; however, there are restrictions on field sizes in the back-end business systems that should be adhered to in the development of an application, as follows:
Known fields
- first_name: 35
- last_name: 40
- email: 60
- description: 2000
- phone: 11 (dashes and parentheses will be stripped; must be a valid North American number)
- media_url: 255
- cde_extension: 6
Attribute fields by type
- string: 40
- number: 40
- text: 2000
- singlevaluelist: 80
- multivaluelist: 80
- datetime: 25
Note that these field lengths may be subject to change.
Supported API Methods
GET Service List
This method is supported.
GET Service Definition
This method is supported.
POST Service Request
This method is supported, with the following notes:
Address Validation
The City of Ottawa supports all three methods of addressing provided by the Open311 GeoReport v2 Specification (address_id, address_string, and latitude and longitude pairings). The preferred method for service address information is a Latitude and Longitude pair. The next best approach is to provide a valid municipal address id (this applies for service address (address_id) and client addresses (client_adress_id or client_adress_id_req) as well). Address strings are also supported, however, tend to be more error prone due to discrepancies in user input. Application developers are responsible for ensuring that the addresses that are submitted are valid; to facilitate this, the City of Ottawa offers the use of an addressing web service:
To ensure a valid municipal address for either the “address_id,” “client_address_id,” or “client_address_id_req” fields, follow these steps:
- Enter the following URL (using the user’s address string, example in bold):https://city-of-ottawa-dev.apigee.net/gis/v1/findAddressCandidates?SingleLine=100+Constellation+DR&outFields=User_fld&f=json
- The response should be as follows (item in bold is the address id):{"spatialReference":{"wkid":102100,"latestWkid":3857},"candidates":[{"address":"100 CONSTELLATION DR","location":{"x":-8434021.1488476545,"y":5676573.4154919367,"z":-100000},"score":100,"attributes":{"User_fld":"__9BQ1OJ"}},...(more results may be included)]}
- Ensure that the address returned is a proper match for the user input, then use the address id returned by the service (the value in the “User_fld” element) to populate the form field (“address_id”, “client_address_id”, or “client_address_id_req”).
End User Contact Information
Some of the services listed on the City of Ottawa portal require client information, such as contact information and/or personal address. The service definition will identify when this is required. Make note of the following attributes in the service definitions:
- contact_info_req - This will indicate that client contact information (first_name, last_name, phone and email) is required for the service request
- client_address_id_req and client_address_string_req - This will indicate that a client address is required for the service request. Client addressing requirements can be met in one of two ways; you have a choice of providing a City of Ottawa postal address and insert it in the "client_address_string_req" parameter or retrieving a City of Ottawa address id through an address service and inserting its value in the “client_address_id_req” parameter.
- If you choose to use a postal address, the API will validate the client_address_string_req parameter to the best of its ability and may produce a validation error should it fail to find the supplied address
- If you chose to use an address id, it can be obtained through the address service as described in address validation section.
- client_address_id and client_address_string - This will indicate that client address details are optional for the service request. Should you choose to supply this information, please follow the same instructions as client_address_id_req and client_address_string_req
Service Definition Fields
- Field names (“code” element) retrieved from the service definition of a particular service need to be encapsulated as attribute [<code_element_value>] (attribute[<code_ element_value>][] for siglevaluelist and multivaluelist datatypes) in your requests as per the GeoReport V2 specification (see http://wiki.open311.org/GeoReport_v2/#post-service-request under “Required Arguments”, “attribute” element).
GET service_request_id from a token
This method is not currently supported.
GET Service Requests
This method is supported, with the following notes:
- Only the Service Request types as defined in the Get Service List method will be available through this method
- A delay of at least five minutes between posting a Service Request and being able to retrieve it through the GET Service Requests method should be expected
- Per the Open311 GeoReport v2 Specification, the default query limit is a span of 90 days or the first 1,000 requests returned, whichever is smallest; this date range may be within the past two (2) years
- The address information will be returned as either Ward information (Ward Name and Number) or Latitude and Longitude (lat, long) pair associated to a Service Address depending on the service request type (see appendix)
GET Service Request
This method is supported, with the following notes:
- Only the Service Request types as defined in the Get Service List method will be available through this method
- A delay of at least five minutes between posting a Service Request and being able to retrieve it through the GET Service Request method should be expected
- In addition to the service_request_id required argument, the email address can be provided as an optional argument to return additional address details beyond the Ward information
GET service requests by specific geographical area
A list of service requests created within a specific geographical area can be retrieved by passing two sets of latitude longitude parameters to your query. The query parameters are defined as follows:
- query_location_lat_1 : top left latitude coordinate
- query_location_lon_1 : top left longitude coordinate
- query_location_lat_2 : bottom right latitude coordinate
- query_location_lon_2 : bottom right longitude coordinate
Sample request: https://city-of-ottawa-dev.apigee.net/open311/v2/requests.xml?query_location_lat_1=45.3463453&query_location_lon_1=-75.8255661&query_location_lat_2=45.287005&query_location_lon_2=-75.716325
GET service requests by updated time
A list of service requests updated starting from a specific date and time can be retrieved. The query parameter is defined as follows:
- updated_datetime: must be formatted in a common subset of ISO 8601. Timezone information (either Z meaning UTC, or an HH:MM offset from UTC) must be included.
Sample request: https://city-of-ottawa-dev.apigee.net/open311/v2/requests.xml?updated_datetime=2019-03-01T01:00:00-04:00
Errors
Any input validation error will be returned in the description as:
- label (field name) error message
Field names may be returned as a comma-separated list.
XML Example
<?xml version="1.0" encoding="utf-8"?>
<errors>
<error>
<code>400</code>
<description>Latitude and Longitude (lat,long) pair is not returning a valid address or intersection.</description>
</error>
</errors>
JSON Example
[{"code":400,"description":"Latitude and Longitude (lat,long) pair is not returning a valid address or intersection."}]
Contact
If you have any questions regarding the City of Ottawa’s Open311 GeoReport v2, please contact SOWeb@ottawa.ca.
Appendix
Service Request Types with Lat/Long displayed
- 2000040-1 Parked or stopped in a bike lane
- 2000046-1 Pay And Display Machine
- 2000081-1 Drain Covers on the Road
- 2000088-1 Graffiti - Public Property - Offensive
- 2000089-1 Graffiti - Public Property - Vandalism
- 2000107-1 Ball Diamond Field Requires Maintenance
- 2000109-1 Trail/Pathway in City Park Requires Maintenance
- 2000111-1 Grass in City Park Requires Maintenance
- 2000111-2 Wild Parsnip, Poison Ivy or Giant Hogweed in municipal park
- 2000112-1 Garbage Cans in Parks
- 2000116-1 Abandoned shopping cart in a City Park
- 2000123-1 Shrub or Bush in City Park Requires Maintenance
- 2000154-1 Ditches
- 2000154-2 Wild Parsnip, Poison Ivy or Giant Hogweed in ditches
- 2000158-1 Area Between Road and Sidewalk (Easement)
- 2000159-1 Curb or Gutter
- 2000161-1 Wild Parsnip, Poison Ivy or Giant Hogweed on area between road lanes (median)
- 2000162-1 Roads Maintenance - General Operations
- 2000162-2 Abandoned shopping cart
- 2000162-3 Dead animal on the road
- 2000163-1 Gravel Shoulder
- 2000163-2 Wild Parsnip, Poison Ivy or Giant Hogweed on sidewalk or road shoulder
- 2000164-1 General Road Maintenance
- 2000164-2 Pothole on the Road
- 2000165-1 General Sidewalk Maintenance
- 2000165-2 Winter Sidewalk Maintenance
- 2000166-1 Garbage cans next to roadways
- 2000186-1 Street Lighting
- 2031035-1 Graffiti - OC Transpo
Service Request Types with ward displayed
- 2000031-1 Disabled parking spaces
- 2000031-2 Fire hydrant or route
- 2000031-3 Unauthorized vehicle parked in your space
- 2000032-1 Intersection
- 2000033-1 Parking - public lanes and alleys
- 2000034-1 Municipal Park
- 2000035-1 No Parking Zone
- 2000036-1 No Stopping Zone
- 2000037-1 Winter Overnight Parking - Restricted Zone
- 2000038-1 Street - Over time limit
- 2000039-1 On Sidewalk
- 2000039-2 Too Far From Curb (impeding traffic)
- 2000068-1 Abandoned shopping cart on City of Ottawa property
- 2000069-1 Abandoned shopping cart on O.C. Transpo property
- 2000099-1 Graffiti - Private Property - Offensive
- 2000099-2 Graffiti - Private Property - Vandalism
- 2000141-1 Obtaining All New Bins
- 2000142-1 Obtaining a New Black Box
- 2000144-1 Obtaining a New Blue Box
- 2000148-1 Obtaining a New Green Bin
- 2000149-1 Obtaining a New Kitchen Container
- 2000157-1 Property damaged by city vehicle
- 2000173-1 Black Box Collection - Houses
- 2000174-1 Blue Box Collection - Houses
- 2000176-1 Order a Garbage and Recycling Collection Calendar
- 2000177-1 Christmas Trees
- 2000178-1 Garbage Collection
- 2000180-1 Green Bin Collection
- 2000197-1 Special Consideration
- 2000341-1 City Trees - Determine Health
- 2000342-1 City Trees - Determine Ownership
- 2000344-1 City Trees - Brush and Wood Removal
- 2000353-1 City Trees - Insect Infestation
- 2000354-1 City Trees - Stump Removal
- 2000365-1 City Trees - New Tree Maintenance
- 2000379-1 City Trees - Trees in Trust
- 2003000-1 Machinery Noise
- 2003001-1 Car Alarm Noise
- 2003002-1 Construction Site Noise
- 2003003-1 Delivery Vehicle Noise
- 2003004-1 Garbage Noise
- 2003006-1 Loud Noise
- 2003009-1 Shouting
- 2003014-1 Dog Previously at Large
- 2003015-1 Dog Barking
- 2003018-1 Dog in Park
- 2003019-1 Unlicensed Dog
- 2003020-1 Pitbull Issue
- 2003022-1 Unlicensed Cat
- 2003023-1 Cat Disturbance
- 2003025-1 Illegal Exotic Animal
- 2003030-1 Private Property Maintenance - Building Exterior
- 2003031-1 Private Property Maintenance - Building Interior
- 2003032-1 Private Property Maintenance - Business Premise Inspection
- 2003034-1 Private Property Maintenance - Derelict Vehicle
- 2003035-1 Private Property Maintenance - Elevators
- 2003036-1 Private Property Maintenance - Exterior Debris and Waste
- 2003038-1 Private Property Maintenance - Grass and Long Weeds
- 2003048-1 Private Property Maintenance - Abandoned shopping cart
- 2003053-1 Lost My Pet
- 2003054-1 Too Many Animals
- 2030713-1 Dog Muzzle Order Violation
- 2030714-1 Stoop and Scoop Violation
- 2030759-1 Oversized Vehicle
- 2030760-1 Front Yard Parking
- 2030764-1 Smoking at a City Facility or Property
- 2030765-1 Smoking in a Common Area
- 2030766-1 Smoking at a Hospital or Long Term Care Facility
- 2030767-1 Smoking at a Restaurant, Bar, Patio
- 2030768-1 Smoking at a School
- 2030769-1 Smoking Shisha or Hookah
- 2030770-1 Tobacco Retail Sales to Minor
- 2030771-1 Tobacco Retail Signage Violation
- 2030772-1 Tobacco Retail Signage Request
- 2030773-1 Smoking in the Workplace Violation
- 2031040-1 Request for Recycling Bins - New Home
