1. Documentation
  2. Rate Limits

Rate Limits

By default, you don't need an access token to use Ballot API. Just start making requests to endpoints! However, since these requests are unauthenticated we will rate limit how fast you can make requests to prevent abuse.

We rate limit requests using the "leaky bucket" method. We only respond to requests at the above rate (e.g. the leak in the bucket). If you send more requests than the rate limit, your requests will queue up (e.g. filling up the bucket). If you max out the queue limit (e.g. overflow the bucket), we will begin rejecting your requests with a 429 Too Many Requests response.

If you see a 429 response code , check the Retry-After header for how many seconds to wait until trying the request again.

If you have an website or native app where you are making requests from that client, our rate limits shouldn't affect your application much. Since our rate limits are per-IP address, each of your users will likely be able to use the API at the default rate limit.

A good practice for websites (e.g. javascript webapps), and native apps is to only send one API request at a time and wait for the response before sending another request.

If you have a central server that is going to make a significant volume of requests, you will likely run into our default rate limits pretty quickly. There are several options to get around our default limits.

Option 1: Self-rate limit.
Queue up requests on your server and then dispatch them to our API until you start seeing 429 responses. Then, wait the given Retry-After seconds and start making requests again. This basically is making a leaky bucket you can manage on your side.

Option 2: Run a local mirror.
Our dataset is public domain and our software is open source, so you are welcome to download a copy and run the API on your internal network.

Option 3: Donate hosting costs.
If you don't want to mirror the API yourself, you can donate to this project and we'll dedicate some extra servers to accomodate your extra requests.

If you are on a large shared or public network (e.g. a college campus or conference center), everyone on your network will likely have the same IP address and so everyone will be sharing the same rate limit. If there's a lot of people using our API on your network, you might start seeing 429 responses fairly often.

We don't want shared networks to disrupt user experience, so we do offer whitelisting certain IP ranges for bigger rate limits. Simply open a pull request , and we'll see what we can do.

With the default rate limits, it would take quite a long time to scan or scrape the entire API. But there's really no reason to! The entire dataset is public domain and you can download a copy.