3.11 API Documentation


General notes


This API expands the possibilities to obtain information, creation and control to the programmatic level of the system, in order to integrate the data to third-party applications, fitting different user models.


Jurisdiction_id


As a means to allow this API to distinguish multiple jurisdictions within one API endpoint we've included a "jurisdiction_id" which will be the unique identifier for cities:



Resources


The system is composed of two different objects: services and requests.


Services


The public API only offers look-up methods (GET) to obtain information about a service or a group of them.

Action

List all Services

Method
GET

Resource
/services

Request parameters
Parameter Description Type Compulsory
jurisdiction_id Jurisdiction identification number Integer Yes

Returns

List of all services registered into the jurisdiction.

Sample JSON response
[
{
"service_code":"001",
"service_name":"Service 001",
"description":"Service 001 description",
"metadata":"true",
"group":"group 1",
"keywords":"keyword1, keyword2",
"type":"realtime",
},
{
"service_code":"002",
"service_name":"Service 002",
"description":"Service 002 description",
"metadata":"true",
"group":"group 1",
"keywords":"keyword3, keyword4",
"type":"realtime",
},
]

Action

Service Definition

Method
GET

Resource
/services/{service_code}

Request parameters
Parameter Description Type Compulsory
jurisdiction_id Jurisdiction identification number Integer Yes
service_code Service identification code String Yes
Returns

List of attributes associated with a service_code {id}.

Sample JSON response
{
"service_code":"001",
"attributes":"[
{
"variable":"true",
"code":"WHISHETN",
"datatype":"singlevaluelist",
"required":"true",
"datatype_description":"single value list",
"order":""Tickets"",
"description":"realtime",
"values":[
{
"key":"1",
"name":"value1",
},
{
"key":"2",
"name":"value2",
}
]
}
]
}

Requests


The public API offers look-up methods to post a request and track the status of that request and other requests.

Action

Post a Request

Method
POST

Request Parameters
Parameter Description Type Compulsory
jurisdiction_id Jurisdiction identification number Integer Yes
apy_key String Yes
service_code Service identification code String Yes
location parameter A full location parameter must be submitted String One of lat & long address_string or address_id
attribute An array of key/value responses based on Service Definitions String Yes
lat Latitude using the (WGS84) projection String No
long Longitude using the (WGS84) projection String No
address_string Human entered address or description of locatio String No
address_id The internal address ID used by a jurisdiction's master address repository or other addressing system Integer No
email The email address of the person submitting the request String No
device_id The unique device ID of the device submitting the request. This is usually only used for mobile devices Integer No
account_id The unique ID for the user account of the person submitting the request Integer No
first_name The given name of the person submitting the request String No
last_name The family name of the person submitting the request String No
phone The phone number of the person submitting the request String No
description A full description of the request or report being submitted String No
media_url A URL to media associated with the request, eg an image String No
Sample JSON response
[
{
"service_request_id ":"26585",
"service_notice":"Service notice",
"account_id":"null",
}

]

Action

List Service Requests

Method
GET

Resource
/requests

Request parameters
Parameter Description Type Compulsory
service_request_id To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited Integer No
service_code Specify the service type by calling the unique ID of the service_code String No
start_date Earliest 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 String No
service_code Specify the service type by calling the unique ID of the service_code.
Format: 2010-01-01T00:00:00Z
String No
end_date Latest 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.
Format: 2010-01-01T00:00:00Z
String No
status Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited;
Options:open, closed.
No
Returns

List of all services requests registered into the jurisdiction.

Sample JSON response
[
{
"service_request_id":"1",
"status":"closed",
"status_notes":"Duplicate request",
"service_name":"service name",
"service_code":"001",
"description":"null",
"agency_responsible":"null",
"requested_datetime":"2014-02-10 12:10:13",
"updated_datetime":"2014-02-10 12:10:13",
"expected_datetime":"2014-02-10 12:10:13"
"address":"null",
"address_id":"5458483",
"zipcode":"12345",
"lat":"37.762221815",
"long":"-122.4651145 ",
"media_url":"null",
},
{
"service_request_id":"2",
"status":"open",
"status_notes":"null",
"service_name":"service name",
"service_code":"001",
"description":"null",
"agency_responsible":"null",
"requested_datetime":"2014-02-10 12:10:13",
"updated_datetime":"2014-02-10 12:10:13",
"expected_datetime":"2014-02-10 12:10:13"
"address":"null",
"address_id":"5458483",
"zipcode":"12358",
"lat":"37.762221815",
"long":"-122.4651145 ",
"media_url":"null",
},

]

Action

List Service Request

Method
GET

Resource
/requests

Request parameters
Parameter Description Type Compulsory
jurisdiction_id Jurisdiction identification number Integer Yes
service_request_id Integer Yes
Returns

The current status of an individual request.

Sample JSON response
[
{
"service_request_id":"1",
"status":"closed",
"status_notes":"Duplicate request",
"service_name":"service name",
"service_code":"001",
"description":"null",
"agency_responsible":"null",
"requested_datetime":"2014-02-10 12:10:13",
"updated_datetime":"2014-02-10 12:10:13",
"expected_datetime":"2014-02-10 12:10:13"
"address":"null",
"address_id":"5458483",
"zipcode":"12345",
"lat":"37.762221815",
"long":"-122.4651145 ",
"media_url":"null",
},

]

Tokens


Get the service_request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a token.This call is only necessary if the response from POST Service Request contains a token.

Action

List Service Request id from a Token

Method
GET

Resource
/tokens{token_code}

Request parameters
Parameter Description Type Compulsory
jurisdiction_id Jurisdiction identification number Integer Yes
TOKEN This is obtained from the POST Service Requests method Integer Yes

Returns

Details about Service Request id from a token

Sample JSON response
< ?xml version= "1.0" encoding="utf-8"?>
<service_requests>
<request>
<service_request_id>293944</service_request_id>
<service_notice>
The City will inspect and require the responsible party to
correct within 24 hours and/or issue a Correction Notice
</service_notice>
<account_id>
</request>
</service_requests>