This post was updated on February 2, 2017.

If you regularly use the E-utilities API, we have important news for you: NCBI is now providing API keys for the E-utilities! After May 1, 2018, NCBI will limit your access to the E-utilities unless you have one of these keys. Obtaining an API key is quick, and simple, and will allow you to access NCBI data faster. If you don’t have an API key, E-utilities will still work, but you may be limited to fewer requests than allowed with an API key.

What is an API key?

An API key is a unique string that you include in your HTTP requests that identifies you to NCBI servers. Think of the API key as a ‘turbocharger’ that lets you get more data, faster, from NCBI.

Why are we doing this?

• Sustainability. The E-utilities API is a free service open to the public and will continue to be; however, without any limits, a single user making too many requests could slow down the service for others. Limiting usage for non-API key users will keep the service faster for everyone.
• Security. Internet security threats abound, and having key-restricted access better enables us to protect the service from malicious attacks and other forms of abuse.
• Performance. API keys give us greater insight into how the community is using the E-utilities, thereby assisting us in making them a better service for you.

Who needs to get a key?

For most casual use, you won’t need an API key at all – you only need to get one if you expect to access E-utilities at a rate of more than three requests per second from a single computer (IP address). Even for higher rates of usage, you won’t need a key before May 1, 2018. After May 1, 2018, any computer (IP address) that submits more than three E-utility requests per second will receive an error message. This limit applies to any combination of requests to EInfo, ESearch, ESummary, EFetch, ELink, EPost, ESpell, and EGquery. Just to be clear, this rate applies only to when we receive the request, not to how long the request executes. You can have more than three concurrent requests running as long as you don’t initiate more than three requests in any one-second window. Even though you won’t need a key before May 1,  keys are already available. You can get one now and begin using it right away.

How do I get a key?

First, you will need an NCBI account. Registering is easy. If you already have an NCBI account, you’re good to go.

To create the key, go to the “Settings” page of your NCBI account. (Hint: after signing in, simply click on your NCBI username in the upper right corner of any NCBI page.)

You’ll see a new “API Key Management” area. Click the “Create an API Key” button, and copy the resulting key. Use the key by adding the parameter api_key to any E-utilities request.

Example: Let’s say that you create a key and its value is “ABCD123”. This would be a simple EInfo request that includes your key:

https://www.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi?db=pubmed&api_key=ABCD123

Now that I have a key, are there still access limits?

Yes. By default, your key will increase the limit to 10 requests/second for all activity from that key. If we receive requests at a higher frequency that include the same key, all requests using that key will receive an error message. If you need higher rates of access, please contact us and we can discuss your situation.

Keep in mind that the request limit applies to all requests using a given key, regardless of the IP address. So if multiple computers are using the same key, then if the sum of their activity causes the request rate to exceed 10 per second, then all of those computers will receive errors.

Here’s what you need to remember:

• Requests without a key will be rate-limited by all activity from their IP address.
• Requests with a key will be rate-limited by all activity from that key. 

Here’s another scenario: let’s say computer A and B both share the same IP address, but only A is using a key. A posts 7 requests / second, while B posts 2 requests / second. A will be fine, but B will receive errors. Why? Since B does not include a key, B’s requests are limited by the IP address, which also includes A’s activity. So the total for that IP is 9 requests / second, which exceeds the limit of three requests / second, resulting in errors for B. A does not receive errors because A’s activity is limited by A’s key, which is only producing 7 requests / second, below the limit of 10 requests / second.

How many keys can I get?

We allow only one API key for each NCBI account. If for any reason you want to replace an existing key with a new one, you can do that on your NCBI account settings page.

I author software that accesses the E-utilities, and this software is used by other people. Do those users need keys?

Yes, but only if your software allows them to post more than three requests/second. For such cases, we recommend that you allow users to enter their own API key as a setting in the software.  Please contact us if you have questions or for more information on this approach.

Questions?

Please contact us if you have any questions or concerns about these new keys, and stay tuned to this blog and our documentation for updates.

• What's New