Access and authentication
Anyone can access the REST API, no signup or registration is required. We offer the following access options:
| Option | How to authenticate |
|---|
| Public | No authentication or identification. |
| Polite | Include your email address in the mailto parameter or agent header. |
| Metadata Plus | Include your API key in the request header as Crossref-Plus-API-Token: Bearer [API key] |
The option you choose affects the rate limits. We recommend the polite option so that we can contact you if there is an issue.
Metadata Plus is our premium service that offers higher rate limits and priority support, and is designed for those who wish to integrate Crossref metadata into production services. If you subscribe to the service, you receive an API key. You can test your API key using cURL:
curl -I -H "crossref-api-key: Bearer [API key]" "https://api-crossref-org.ezproxy.galter.northwestern.edu/v1/works"
If successful, the HTTP status code will be 200 (it will be 401 if the token is not valid) and the response header will contain x-api-pool: plus.
Request limits
In order to make the data accessible to all and keep the service stable, we operate limits that apply to individual users.
Rate limits: These are included in the results headers under x-rate-limit-limit and x-rate-limit-interval and depend on the pool accessed by your request. This gives the maximum number of requests you can make in a given time period. The public and polite pools have a rate limit of 50 requests per second, and the Plus pool has a limit of 150 requests per second.
Concurrent request limits: Users of the public and polite pools are limited to 5 concurrent requests.
If you exceed the rate limits, you will receive a 429 HTTP response. In this case, wait a short while and try your request again at a lower rate or with lower concurrency.
Rate limits are usually applied and removed automatically. In the rare case that we apply a block manually, we will first make an effort to contact you to resolve the issue. For this reason we strongly recommend providing a mailto parameter in all requests. Blocked users will receive a 403 HTTP response and you can contact our support team to ask for a block to be removed.
Best practice
By using our REST API, you are part of our community that supports open access to scholarly metadata. We ask that you are considerate of other users and don’t take actions that will make the API unstable, and hence unusable for others. You can do this by:
- Caching responses so you don’t make the same requests repeatedly. Be considerate about the frequency with which you refresh your cache.
- Use the
mailto parameter and specify a User-Agent header that identifies you and your script. - Handle HTTP response codes and monitor response times. Back off if the response times start to increase.
See more recommendations about how to get the most from the API.
