API Rate Limits

The API access is regulated in multiple levels. For plan FREE, the rate limiting is primarily considered on a per IP basis. For paid plans, it’s on a per Application basis.

Daily Limits

Each plan provides different daily limits per request types. For ex. plan FREE allows total of 100 combined requests per day, which includes both LookupRequest and SearchRequest. But SearchRequest is limited up to 40 per day. For paid plans, daily limits are separated by request types. Ex. for plan DEV, you can send 2,000 SearchRequest and 20,000 LookupRequest everyday.

To avoid service interruption, we allow daily limits adjustment for paid plans. But usage above the plan limits will be charged at the overage rate described in each plan. The overage fee will be rounded up to the nearest 10s or 100s hits based on the function call which is described in each plan and will be charged in each next billing cycle together with the monthly-based subscription fee. You need to send us an email request for the limit adjustment. Each account is allowed for one adjustment per billing cycle.

Burst Limits

On top of daily rate limits, API requests are also limited by a burst rate. Ex. for plan FREE, your application is limited up to 6 requests per minute. Requests sent faster than that will be declined with HTTP status 429. In order to regain the access, your application has to wait for the next window period. Think of it the same as the daily limits, but with a much smaller window.

HTTP Headers and Response

Ensure that you inspect the HTTP headers, as they provide pertinent data on where your application is at for a given rate limit on the method that you just utilized.

Note that the HTTP headers are contextual. When Burst Limits are hit, they indicate the rate limit for the Burst Limits. Otherwise they indicate the Daily Limits of the plan your application is registered with.

X-RateLimit-Limit: the rate limit ceiling for that given type of request

X-RateLimit-Remaining: the number of requests left for the limited window period

X-RateLimit-Reset: the daily limits reset time in Unix time

X-RateLimit-Current: the current count for that given type of request in the window period. It appears only when you requested Daily Limits to be set above the plan limits and the X-RateLimit-Remaining hits 0.

X-RateLimit-Limit → 100
X-RateLimit-Remaining → 85
X-RateLimit-Reset → 1462696544

Best Practice

Reuse the connection

Maintain an open connection and send batch requests through the same connection is much more efficient than opening a new connection for each request.

Note that connections with no activity for up to 5 minutes will be closed by our API Gateway.

Keep requests in a sustainable rate

Keep API requests under Burst Limits is quite important. Once requests exceeded the burst limit, application should sleep until X-RateLimit-Reset in order to regain the access. If application kept sending request after burst limit was reached, the API Gateway or Server would extend the X-RateLimit-Reset from the latest requests.