API Overview

Postman

The requests from this documentation can be made via Postman

View Postman API Reference

Resource Patterns

Resources URI patterns try to follow the general convention:

/vehicles - represents all the vehicles

/vehicles/:id - represents a particular vehicle ID

/vehicles/:id/remote/state - see the state of a particular vehicle ID

/vehicles/:id/routes - see the routes of a particular vehicle ID

etc.

Pagination

Requests to a collection of resources (such as: Users, Vehicles, Devices, etc...) are automatically paginated and will return a set of 200 resources by default.
You can request up to 1000 items per page (up to 500 Devices) by using the set parameter.

When making request to the resources you will see the following additional fields in the response.

Example:

/vehicles

{
  "set": 2,
  "total": 5,
  "data": [...],
  "page": 1,
  "pages": 3
}

By default the API returns the first page of result (page: 1), to navigate through the total number of pages pass the parameter page until you reach pages.

Assume we have 252 vehicles, and we make a request to the API without passing parameters, by default it will return the first 200 items:

GET /vehicles

{
  "set": 200,
  "total": 252,
  "data": [...],
  "page": 1,
  "pages": 2
}

If we limit the request to sets of 100, then we'll get a response with 3 pages worth of data, (1 & 2 of 100 and the 3rd page with 52)

GET /vehicles?set=100

{
  "set": 100,
  "total": 252,
  "data": [...],
  "page": 1,
  "pages": 3
}

To navigate through the pages pass page until you reach pages

GET /vehicles?set=100&page=2

{
  "set": 100,
  "total": 252,
  "data": [...],
  "page": 2,
  "pages": 3
}

GET /vehicles?set=100&page=3

{
  "set": 52,
  "total": 252,
  "data": [...],
  "page": 3,
  "pages": 3
}

Since page=pages we are done traversing the items.

Searching

You can search for specific results on the API using the search URL param in GET requests.

This param works for all resources except for the /devices API.

# Search for vehicle names that match
https://api.pegasusgateway.com/vehicles?search.name=CR2013

# Search for trips reports that are generated daily for the past 7 days
https://api.pegasusgateway.com/tasks?search.schedule=[%220%209%20*%20*%20*%22]&search.processes.0.0.script=trips2&search.processes.0.1.back.days=7

HTTP Verbs

Status codes

Rates

The API handles limits to the different resources on a per user and global rate for the whole site:

Rawdata & Counters:

• global: 60/minute; 800/hour
• per user: 3/second; 30/minute; 500/hour

Trips:

• global: 120/minute, 1600/hour
• per user: 6/second, 30/minute, 500/hour

Trips:

• global: 120/minute, 1600/hour
• per user: 6/second, 30/minute, 500/hour

Geofences:

• global: 2500/minute
• per user: 125/minute

Geofence Types

• global: 240/minute
• per user: 80/minute

Reversegeo

• global: 1200/minute, 15000/hour
• per user: 200/minute, 4200/hour

Other resources such as vehicles, groups, assets, etc. apply an anti DDOS (Distibuted Denial of Service) limit, which would only be reached if various machines spam the API.

Whenever you hit the limit the API returns a 429 Status Code. At which point it is important that your app suspends more subsequent requests to the API until the limit is reset.

🚧

IP Bans

If your app continues to make requests after it hits a 429 the API will eventually block the originating IP address.

// example response when limit is exceeded and an HTTP 429 is returned

{
  "reason": "vehicles",
  "message": "Rate exceeded",
  "limit": 10,
  "id": "ec2ec6e51a42f40d12e7009787d833b8",
  "value": 11.0455
}

The API returns some response headers which include X-RateLimit-* keys so you know when it's safe to make requests again.

> HTTP/1.1 429 TOO MANY REQUESTS
> Connection: keep-alive
> Content-Length: 135
> Content-Type: application/json
> Date: Sun, 30 Sep 2018 16:45:13 GMT
> Server: nginx
> X-Peg-Id: 1
> X-Peg-Server: F
> X-Peg-User-Id: 54
> X-RateLimit-Limit: 10
> X-RateLimit-Remaining: 0
> X-RateLimit-Reset: 1538325923

{reason: "vehicles", message: "Rate exceeded", limit: 10, id: "ec2ec6e51a42f40d12e7009787d833b8",…}

The response tells us there's a limit of 10 requests, and the client has 0 remaining, the limit resets back to 10 at the following epoch timestamp: 1538325923 - Sun, 30 Sep 2018 16:45:23 GMT

👍

Solutions for rate limiting

If your application is on the verge or is constantly hitting the api rate limits you can checkout the Live Communications section which allows you to subscribe to the vehicle's data in realtime or Forwarders which allows you to receive all the vehicle's data in a JSON format to any external endpoint, for example your own database for further manipulation.

Units

By default the API uses the following units unless otherwise stated:

Speed and acceleration units vary per resource, but will normally take the form of

• distance_unit / time_unit
• distance_unit / time_unit / second

The API's of Rawdata, Counters and Trips support unit parameters, which can modify the output to the desired units.

👍

API Caching

Server level caching is done on requests that are similar, therefore it's important to specify the units of a request in order to make it as atomic as possible. More info below

Allowed values

The API allows you to specify multiple values for each unit of measurement.

You may also pass user for either the distance or volume parameters, where applicable. The API will return the values in accordance with the users preference.

Speed

Where applicable, the speed is determined by the distance and time units (default: meter/second)

The Counters and Trips API's allows you to override this unit, by specifying one of kph , mph or user, where user falls back to either kph or mph based on the users distance preference (mile or km)

Acceleration

The acceleration field is always the speed units, per second

• meter/second/second
• mile/hour/second.

Timezones

The API by default returns all timestamps in UTC (GMT+0).

You can change the timestamp by passing a URL param tz with an allowed timezone value or an HTTP header value with"X-Time-Zone" and an allowed timezone value.

URL param: tz=America/New_York

HTTP Header: "X-Time-Zone": "America/New_York"

Caches

Note that the API does server level caching for similar data requests. If for example you make multiple requests for a vehicle's rawdata with a specific date range the first request will hit the server but any subsequent request will hit the cache and return stored data.

To know if a request is cached you can take a look at the response header: x-cache-status, which will change to HIT when it's a cached request.

To take advantage of server level caching it's important that the requests are as atomic as possible, meaning that they're specific enough that it will return the exact results you look for. In other words, pass the units and timezone every time so that you get a cache hit.