Rate Limiting

Rate limiting is a strategy to manage API usage, ensuring system stability and consistent user experience by imposing limits on the number of API calls.

Global Rate Limit

In addition to the module-specific limits below, every endpoint enforces a flat limit of 200 requests per 10 seconds per user, applied across all endpoints. This limit exists to prevent excessive request rates and applies regardless of which module-specific limit also applies to a given endpoint.

Rate Limit Response Headers

When a request is rate limited, the API returns 429 Too Many Requests along with headers describing the current limit state:

HeaderDescription
retry-afterNumber of seconds to wait before retrying. Honour this header when deciding when to retry.
ratelimit-remainingNumber of calls remaining in the current window at the time of this response.
ratelimit-resetNumber of seconds until the current rate limit window resets.

ratelimit-limit

Limit of the rate limit bucket that this response describes. This is the most constrained bucket that applies to the request.

altitude-ratelimit-bucket

Identifier of the bucket that the other rate limit headers describe, in the form bucket:user or bucket:database. For example, rtm:user or stop-analytics:database.

Important:

retry-after is the authoritative signal for when to retry. ratelimit-remaining can appear inconsistent with the enforced limit on a 429 response; do not rely on it to determine whether you are currently rate limited.

API Module Rate Limits

The table below describes module specific rate limits.

If not specified, the "All others" rate limit is applied.

Endpoint

Hourly User Limit

Hourly Database Limit

POST /api/v2/stop-analytics/stop-events

5 calls

20 calls

POST /api/v2/stop-analytics/regional-domicile-analytics

30 calls

60 calls

POST /api/v2/stop-analytics/fuel-point-analytics

5 calls

20 calls

POST /api/v2/stop-analytics/hours-of-service-analytics

5 calls

20 calls

POST /api/v2/origin-destination/closed-matrix

5 calls

20 calls

POST /api/v2/origin-destination/corridor-matrix

5 calls

20 calls

POST /api/v2/origin-destination/open-matrix

5 calls

20 calls

POST /api/v2/origin-destination/routes

30 calls

60 calls

POST /api/v2/origin-destination/segments

30 calls

60 calls

POST /api/v2/regional-travel-metrics/vehicle-distance-traveled

5 calls

20 calls

POST /api/v2/regional-travel-metrics/idle-metrics

5 calls

20 calls

POST /api/v2/regional-travel-metrics/fuel-economy

5 calls

20 calls

POST /api/v2/regional-travel-metrics/modeled-vehicle-distance-traveled

5 calls

20 calls

POST /api/v2/regional-travel-metrics/observed-counts

5 calls

20 calls

POST /api/v2/aadt

5 calls

20 calls

POST /api/v2/traffic/speed-per-segment

60 calls

120 calls

POST /api/v2/zones/by-ids

30 calls

60 calls

POST /api/v2/zones/custom

5,000 calls

20,000 calls

All others

400 calls

20,000 calls

Note:

The Site Intelligence (POI) endpoints are subject only to the global limit of 200 requests per 10 seconds per user. The "All others" limits do not apply to them.

Analysis Size Limits

Although there is no quantifiable measure of how big an analysis can be, Altitude enforces an analysis runtime limit of 6 hours. If the runtime exceeds 6 hours, the analysis may not return an output. There are also size limits on arrays: running an analysis with too many zones can cause an error. The number of days included in the analysis affects the number of allowed O/D pairs. The table below describes the limits.

Note:

An analysis cannot include more than 366 days or more than 3,500 Origins, Destinations, or Custom Zones.

Days

API Maximum O/D Pairs

UI Maximum Number of Zones (Origins, Destinations, or Custom Zones)

Up to 31 days

1,000,000 pairs

600 zones

32 to 93 days

100,000 pairs

300 zones

94 to 366 days

10,000 pairs

100 zones (maximum date range of 1 year)

Note:

If this article does not resolve the issue, contact Altitude Support. Provide the affected email address, the database name, and a description of the error. For API errors, also provide the requestId from the error response, or the X-Request-ID response header.

For questions about a custom integration, contact an Altitude account representative.