Rate-limit Policy Journey-Planner-v3

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

Level	Trip-request Quota	Trip-requests SpikeArrest	Other-request Quota	Other-request SpikeArrest
Non-identified consumers	30	2	60	20
Consumers identified with `Et-Client-Name`	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 (RFC 6585: Additional HTTP Status Codes ).

Example Spike arrest violation response headers (only given upon violation):

Spike-Allowed: 2
Spike-Range: per-second

Example 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.