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 3 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, and keys are already available now. After May 1, 2018, any computer (IP address) that submits more than 3 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.
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:
Now that I have a key, are there still access limits?
Yes. By default, your key will increase the limit to 10 requests/second. If you submit at a higher frequency, your requests will receive an error message. If you need higher rates of access, please contact us and we can discuss your situation.
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 3 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.