Dimensions analyses the reference lists of publications and calculates a set of article-level citation indicators. The Dimensions Metrics API gives you programmatic, read-only access to these indicators for any publication in Dimensions, looked up by DOI, PubMed ID or Dimensions ID.
The API is free for non-commercial use and requires no authentication. There is no API key, no header and no registration token to send. The same data powers the Dimensions Badges, which are the quickest way to display these indicators on a web page without writing code.
Base URL: https://metrics-api.dimensions.ai
All endpoints are GET and respond with application/json; charset=utf-8. HTTPS only.
Who can use it
- Individuals may use the API for personal, non-commercial research purposes, including displaying indicators for work they have authored.
- Academic institutions must register first. Registered organisations may use the API for internal, non-commercial purposes, including displaying indicators for their own research outputs on free-to-access websites and applications.
- Any other use (commercial organisations, publishers, product integrations, other use cases): contact info@dimensions.ai with a description of your use case and we will get back to you as soon as possible to tell you what we can do to help.
Registration is a licensing step, not a technical one. Nothing about your requests changes once it is done, and you will not receive credentials. Full conditions are in the Dimensions Badges and Metrics API Terms of Use. This page summarises them and is not a substitute for them.
Quick start
No authentication is required, so a bare curl is enough:
curl https://metrics-api.dimensions.ai/doi/10.1001/jama.2016.9797
{
"doi": "10.1001/jama.2016.9797",
"times_cited": 612,
"recent_citations": 43,
"relative_citation_ratio": 18.3,
"field_citation_ratio": 114.63,
"license": "This data has been sourced via the Dimensions Metrics API, use of which is subject to the terms at https://dimensions.ai/policies/terms/metrics/. Any use by an unregistered organization is not authorized. Please contact info@dimensions.ai for further information."
}Citation counts are live, so the numbers you get back will be at or above the ones shown here.
Endpoints
All three endpoints return the same response object. They differ only in the identifier used to look up the publication, so pick whichever one your system already stores.
Get metrics by DOI
GET /doi/{doi}| Parameter | In | Type | Description |
|---|---|---|---|
doi | path | string | The publication's DOI, without a https://doi.org/ prefix. DOIs contain /, which is accepted either unencoded or percent-encoded as %2F. |
Example: https://metrics-api.dimensions.ai/doi/10.1001/jama.2016.9797
Get metrics by PubMed ID
GET /pmid/{pmid}| Parameter | In | Type | Description |
|---|---|---|---|
pmid | path | integer | The PubMed identifier, e.g. 27400401. |
Example: https://metrics-api.dimensions.ai/pmid/27400401
Get metrics by Dimensions ID
GET /id/{id}| Parameter | In | Type | Description |
|---|---|---|---|
id | path | string | The Dimensions publication ID, e.g. pub.1026722513. |
Example: https://metrics-api.dimensions.ai/id/pub.1026722513
The three examples above all resolve to the same publication, so you can use them to check that a change of identifier does not change the indicators you get back.
Response object
| Field | Type | Description |
|---|---|---|
doi / pmid / id | string / integer / string | The identifier used in the request, echoed back. Only the field matching the endpoint you called is present — doi for /doi/…, pmid for /pmid/…, id for /id/…. pmid is returned as an integer. |
times_cited | integer | Total number of times the publication has been cited by other publications indexed in Dimensions, across all years. Citations are counted from reference lists. |
recent_citations | integer | Number of citations received in the last two years. The window rolls over in the middle of the calendar year: from January to June of year Y it counts citations from Y−2 onwards; from July it counts citations from Y−1 onwards. |
relative_citation_ratio | number | The Relative Citation Ratio (RCR) indicates the relative citation performance of a publication when comparing its citation rate to that of other publications in its area of research. The publication's area of research is defined by the publications that have been cited alongside it. Calculated by the US National Institutes of Health (NIH) and normalized to 1.0 for the median NIH-funded publication in the same area of research and year, so a value above 1.0 indicates a citation rate above that benchmark. Only available for publications with a PubMed record, and not populated for the current or previous calendar year. |
field_citation_ratio | number | Field Citation Ratio (FCR). An article-level indicator of relative citation performance compared with similarly aged articles in the same subject area. A value above 1.0 indicates higher-than-average citation, where the comparison set is defined by Fields of Research (FoR) subject code, publication year and age. Calculated for all publications in Dimensions that are at least two years old and were published in 2000 or later. |
license | string | Licence notice. Always present. States that the data is subject to the Metrics API Terms of Use and that use by unregistered organisations is not authorised. You do not need to display this string, but you must comply with it. |
Missing indicators
When an indicator is not available for a publication — no RCR for a non-PubMed article, no FCR for a publication under two years old — the field is still present, with the value null. It is never returned as 0, and it is never omitted. Citation counts, by contrast, are always integers and are 0 when there are none.
{
"doi": "10.1007/bf02307872",
"times_cited": 0,
"recent_citations": 0,
"relative_citation_ratio": null,
"field_citation_ratio": null,
"license": "…"
}So relative_citation_ratio == null means not calculated for this publication, not cited zero times relative to its field. Treat the two cases differently when you display indicators.
Errors
| Status | When | Body |
|---|---|---|
404 Not Found | No publication matches the identifier, or the identifier is malformed (for example /pmid/abc). | Plain text 404: Not Found, sent as text/plain — not JSON. |
There is no separate status code for a malformed identifier: an unparseable value and an unknown-but-valid one both return the same 404. Your client should treat any non-200 response as no data, and must not assume the body is JSON.
Reasonable use
Use of the API — including the request-rate limit, the attribution requirement, and the restriction on displaying only current (not stale) metrics — is governed by the [Dimensions Badges and Metrics API Terms of Use] (https://www.dimensions.ai/policies-terms-metrics/).
Related
- Dimensions Badges — embeddable widget built on this API
- Dimensions Badges and Metrics API Terms of Use
- Register your organisation