getting_started:api [GPS Police Support Centre]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== API =====

Our web services API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

----
=== Authentication ===

You authenticate to the API by including an API key in each request. Your account's API key is unique and should be kept secret. 

To obtain your account's API key, sign into HQ and visit your [[https://my.gpspolice.com/hq/info|Account > Info]] page. Your API key is at the bottom-left of the page. Clicking Re-key will generate a new API key for your account and disable the previously-generated API key.

----
=== Usage ===

To use the API, send a GET request to https://my.gpspolice.com/hq/api/v1 that includes your API key along with what data you would like returned. For example, if you wanted to see the current status and location of all the vehicles or assets in your account, you would call:

[[https://my.gpspolice.com/hq/api/v1/API_KEY/assets]]

What is returned is a JSON document containing an array of objects, with each object describing a vehicle:

<well>
[
{
"id": 4316,
"short_name": "Truck 01",
"year": "2005",
"make": "Ford",
"model": "F150",
"colour": "Black",
"license": "",
"vin": "",
"notes": "",
"service_notes": "",
"odometer_meters": 24140000,
"engine_hours_seconds": 9765171,
"uts": 1418704584,
"state_id": 4,
"status": "Engine off",
"latitude": "51.153620",
"longitude": "-114.200325",
"heading": 0,
"speed_mps": "0.00",
"street": "40 Royal Vista Drive NW",
"city": "Calgary",
"province": "AB",
"lsd": "14-22-025-02 W5",
"driver": "Andy",
"imei": "354676050087654",
"airtime_expires": "2017-01-01",
"group": "Sales"
},
{
"id": 6770,
"short_name": "Truck 02",
"year": "2014",
"make": "Toyota",
"model": "Tacoma",
"colour": "Blue",
"license": "",
"vin": "",
"notes": "",
"service_notes": "Use 5W30 synthetic",
"odometer_meters": 7336755,
"engine_hours_seconds": 646451,
"uts": 1424990287,
"state_id": 4,
"status": "Engine off",
"latitude": "51.053252",
"longitude": " -114.04404",
"heading": 87,
"speed_mps": "0.56",
"street": "828 1 Avenue NE",
"city": "Calgary",
"province": "AB",
"lsd": "1-27-024-01 W5",
"driver": "Frank",
"imei": "351579050012345",
"airtime_expires": "2015-03-01",
"group": "Service"
}
]
</well>


To get the same details for a single vehicle, include its ID:

https://my.gpspolice.com/hq/api/v1/API_KEY/assets/1234

To get a list of drivers or places:

https://my.gpspolice.com/hq/api/v1/API_KEY/drivers
https://my.gpspolice.com/hq/api/v1/API_KEY/places

----
=== Rate limit === 
To ensure our web services API remains fast and responsive for all users, please avoid sending requests more often once every 15 seconds.

----
=== In conclusion ===

As you can see, our web services API is pretty simple and (we hope) easy to use. We plan to expand its features in the future, but for now please try it out and let us know what you think!