DEV update: Geotab result and rate limits

At Geotab, we strive to create an open and flexible API that fosters creativity and innovation. We try to strike a balance between providing tools to create powerful applications, integrations and Add-ins, while maintaining overall system health and quality. With this in mind, we are cautiously introducing reasonable result and rate limits into the API. Result and rate limits are meant to encourage API developers to use appropriate APIs for a given use case, as well as to safeguard against unbounded requests.

Starting in version 5.7.1902, select APIs will be limited by:

• How many results can be retrieved in a single request; and
• The rate at which an API can be called.

Result limits

GetFeed requests have been limited to 50,000 results for many years. GetFeed is designed to consume a large amount of data from the API in an incremental fashion. It can be used in situations where more than 50,000 records are requested.

In keeping with these limits, Geotab will be implementing a 50,000 results limit to Get requests. These limits will be applied first to Entity types that provide a GetFeed equivalent method.

The Entities listed below will have Get limits of 50,000 results imposed as of release 1902:

• AnnotationLog
• DVIRLog
• TrailerAttachment
• IoxAddOn
• CustomData
• BinaryData

In a future release, appropriate limits for the following objects will also be applied:

• LogRecord
• StatusData
• FaultData
• Trip
• ExceptionEvent
• ShipmentLog
• DebugData
• UserHosRuleSet
• DutyStatusLog
• FuelTaxDetail (10,000 limit)

Note: In the 1902 release, API calls that yield results larger than 500 MB will result in an Over Limit Error (see below). In previous releases, an Exception would have been thrown.

In future releases, Geotab will be adding GetFeed implementations for Entities which do not currently have a GetFeed API, e,g. Device, Zone, User etc. This is to ensure that you can always get all of a given type before any limit is enabled. The limit will be 50,000 or lower, depending on the size of the entity. We will announce the availability of the new feeds and any limits in advance, giving time to adjust to any integrations as needed.

Geotab will also be implementing limits for other non-generic methods (e.g. GetAddresses, GetCoordinates, GetRoadMaxSpeeds, etc.), which do not make sense to have a feed method but should have a reasonable limit. We are currently investigating limits for these APIs and will provide advanced notice of any change.

Multicall

In future, Multicall will have an accumulating total limit. If the total accumulated results of child requests exceed this limit, an error result will be returned (error details below). Multicall will also be limited to a maximum number of child requests. Limits are still to be determined at this time.

Over Limit error

To ensure your application doesn’t think it has every result that matches the search criteria, when in reality there are more, an error result (“OverLimitException”) may be returned in these scenarios:

• If an API call is made with no results limit, one will be implicitly applied to the request on the server side.
• If the results are of the limit, an error result will be returned.
• If a request is made with a result limit higher than the imposed limit.
• A multicall accumulated limit is exceeded.
• A multicall child request limit is exceeded.

No error will be returned if the provided rate limit matches the imposed limit, and the results match that list.

Example:

{
"error": {
"message": "Supplied results limit (50001) exceeds maximum limit (50000).",
"code": -32000,
"data": {
"id": "16526e19-06b9-4a4a-b2a3-c1dbc0144cd8",
"type": "OverLimitException",
"requestIndex": 0
}
},
"jsonrpc": "2.0"
}

Rate limits

A couple of years ago, Geotab added rate limits to the Authenticate API. Overall this was a positive change to the API and provided a reasonable limit on the number of Authentication attempts per minute improving the overall stability and security of the system. Geotab will be extending limits to a new set of APIs. As with result limits, this process will start with GetFeed requests.

The feed has a couple of common use-cases:

• Getting a constant, near real-time feed of all data reported by devices (GPS), or calculated by the system (Trips).
• Generating large aggregate reports on an off-peak interval.

For a constant poll, we recommend polling for data every 30 seconds. However, we understand for some use cases, this to too infrequent to keep up with the rate of data generated by your vehicles and have created limits accordingly.

Rate limits are applied on a user+database basis, and each Entity type receives an independent rate limit.

Starting in release 1902, rate limits of 1 request-per-second will be applied to GetFeed requests of these Entity types:

• AnnotationLog
• DVIRLog
• ShipmentLog
• TrailerAttachment
• IoxAddOn
• CustomData
• DebugData
• BinaryData
• UserHosRuleSet
• DutyStatusLog
• FuelTaxDetail
• LogRecord
• StatusData
• FaultData
• Trip

As more feeds become available rate limits will apply to those as well.

Multicall

Multicall itself will not be limited at this time; rather, the inner calls will be accumulated towards the limit of that request type as it is executed synchronously. If a multicall child exceeds its limit an error result will be returned (see below).

Over Limit error

When a limit is exceeded, an error result with OverLimitException will be returned. A header (“Retry-After”) is also set with time remaining for the limit to reset.

Header Example:

Retry-After: 58

Error Example:

{
"error": {
"message": "API calls quota exceeded. Maximum admitted 1 per 10s.",
"code": -32000,
"data": {
"id": "b83dc64f-3976-4b35-8e32-c55b3a4adc2f",
"type": "OverLimitException",
"requestIndex": 0
}
},
"jsonrpc": "2.0"
}

Headers

If a rate limit is applied to an API, with the successful request JSON-RPC response, headers are set with rate limit information:

• “X-Rate-Limit-Limit”: the rate limit period (eg. 1s, 1m, 12h, 1d)
• “X-Rate-Limit-Remaining”: number of request remaining
• “X-Rate-Limit-Reset”: UTC date time (ISO 8601) when the limits resets

Example:

X-Rate-Limit-Limit: 10m
X-Rate-Limit-Remaining: 9996
X-Rate-Limit-Reset: 2019-03-26T16:13:11.9440478Z

More Developer news:

Understanding the MyGeotab Binary Data Types

Using the MyGeotab Python API to Create Custom Reports