Rate-limit Policy Journey-Planner-v3
- Andreas Tryti
- Tom Erik Støwer
Journey-Planner-v3 is a national service for journey planning for all public transport in Norway. This service is used by many journey planner apps and other services and can be considered a part of the digital infrastructure for the Norwegian mobility sector. To ensure normal usage and stability of this service rate-limiting policies apply for all users. Users without an agreement with Entur will get the default policy and partners of Entur will have a custom policy.
There are two separate polices:
Trip-request - One policy only applies for trip-requests as these are the most resource consuming.
Other-request - One policy applies for all other request available in the GraphQL API.
Each policy is split into to elements:
Quota - the number of request pr. minute, calculated using a counter within a time window of one minute that starts at the first request and is reset every minute. E.g. given a quota policy of 10 requests per minute, a violation will occur if a request is sent after the counter has reached its limit of 10 requests within the current time window.
SpikeArrest - the number of request pr. second, calculated by keeping track of time elapsed since last request. E.g. a spike arrest policy of two requests per second, means a violation will occur if a request is sent within half a second after the previous request.
Policy levels
Level | Trip-request Quota | Trip-requests SpikeArrest | Other-request Quota | Other-request SpikeArrest |
|---|---|---|---|---|
Non-identified consumers | 30 | 2 | 60 | 20 |
Consumers identified with | 500 | 150 | 1000 | 200 |
Entur Partners | custom | custom | custom | custom |
Monitoring of policy status
It is expected that consumers have control over their policy status with respect to traffic patterns. All responses from the service contain headers with details about current usage and remaining quota. When spike arrest occurs, headers are supplied containing the spike arrest policy itself. If your request violates one of the policies you will get a response with status code 429 (https://datatracker.ietf.org/doc/html/rfc6585#section-4 ).
Example Spike arrest violation response headers (only given upon violation):
Spike-Allowed: 2
Spike-Range: per-secondExample Quota headers (all responses have these headers, except when there is a spike arrest violation):
Rate-Limit-Allowed: 30
Rate-Limit-Available: 29
Rate-Limit-Expiry-Time: Mon Jan 16 2023 12:17:34 GMT-0000 (UTC)
Rate-Limit-Range: "per-minute"
Rate-Limit-Used: 1
Re-try policy
It makes sense for clients to implement a conservative re-try policy on spike-arrest violations as spikes in traffic loads may occur.
Clients should NOT implement a re-try policy for quota-violations. Upon quota violation, clients should wait at least until Rate-Limit-Expiry-Time before trying again.