Translate¶
Translate research output identifiers (DOIs, PMIDs, arXiv IDs, etc.) into Altmetric IDs. This endpoint is useful when you have a list of identifiers and want to discover which ones Altmetric has data for.
Warning
Calls to this endpoint are only available to license holders. If you call this endpoint without an authorized API key you'll get a 403 response. Contact us for pricing or to request use as a non-commercial entity.
Request¶
This endpoint supports both GET and POST methods. Use GET for small numbers of identifiers and POST when translating larger batches.
GET /{version}/translate/{id}¶
Translate a single identifier or multiple pipe-delimited identifiers into Altmetric IDs.
Example request (single identifier):
Example request (multiple identifiers):
GET /v1/translate/10.1038/news.2011.490|21148220?key=xxx-xxx-xxx-xxx HTTP/1.1
Host: api.altmetric.com
Path parameters:
| Parameter | Required | Accepts | Description |
|---|---|---|---|
version |
Yes | v1 |
See Versioning |
id |
Yes | Single identifier or pipe-delimited identifiers | The identifier(s) to translate. Multiple identifiers can be separated by the pipe character \|. |
POST /{version}/translate¶
Translate identifiers supplied in the request body. This is the recommended method when translating large numbers of identifiers, as it avoids URL length limitations.
Example request:
POST /v1/translate?key=xxx-xxx-xxx-xxx HTTP/1.1
Host: api.altmetric.com
Content-Type: application/x-www-form-urlencoded
ids=10.1038/news.2011.490|21148220|1509.03622
Body parameters:
| Parameter | Required | Accepts | Description |
|---|---|---|---|
ids |
Yes | Pipe-delimited identifiers | The identifier(s) to translate. Multiple identifiers must be separated by the pipe character \|. |
Note
The POST method also accepts identifiers in the URL path (POST /{version}/translate/{id}), which behaves identically to the GET method.
Limits¶
A maximum of 100,000 identifiers can be translated per request. Requests exceeding this limit will receive a 400 Bad Request response.
Supported identifier types¶
The endpoint automatically detects the type of each identifier. The following identifier types are supported:
| Type | Format | Example |
|---|---|---|
| DOI | 10.xxxx/... |
10.1038/news.2011.490 |
| PMID | Numeric | 21148220 |
| arXiv ID | xxxx.xxxxx |
1509.03622 |
| Handle | xxx/yyy or hdl:xxx/yyy |
hdl:cnri.dlib/july95-arms |
| ISBN | isbn:xxxx |
isbn:978-4-87311-336-4 |
| NCT ID | NCTxxxxxxxx |
NCT00888537 |
| Dimensions Publication ID | pub.xxxxxxxxxx |
pub.1091500321 |
| RePEc ID | RePEc:xxx |
RePEc:nbr:nberwo:11929 |
| URN | urn:... |
urn:nbn:se:su:diva-80034 |
| SSRN | ssrn:xxxxxxx |
ssrn:1002907 |
| URI | URL-encoded URI | http%3A%2F%2Fwww.example.org%2Fpath |
HTTP status codes:
| Code | Description |
|---|---|
| 200 OK | The body of the response should contain the data you requested in JSON format. |
| 400 Bad Request | The request was invalid or malformed. Response body is in text format. |
| 403 Forbidden | You aren't authorized for this call. All requests require an API key. Response body is in text format. |
| 404 Not Found | Altmetric doesn't have any details for the research output or set of research outputs you requested. Response body is in text format. |
| 429 Too Many Requests | You are being rate limited. If you haven't already then apply for an API key. Response body is in text format. |
| 502 Bad Gateway | The API version you are using is currently down for maintenance. Response body is in text format. |
Response object¶
A successful request returns a JSON object mapping input identifiers to their corresponding Altmetric IDs. Only identifiers that were successfully translated are included in the response; unknown identifiers are omitted.
| Key | Type | Description |
|---|---|---|
{input_identifier} |
string | The Altmetric ID corresponding to the input identifier. The key is your original identifier and the value is the Altmetric ID. |
Note
Multiple input identifiers may resolve to the same Altmetric ID if they refer to the same research output (e.g., a DOI and PMID for the same article).
Example response¶
Request:
GET /v1/translate/10.1038/news.2011.490|21148220|unknown-id?key=xxx-xxx-xxx-xxx HTTP/1.1
Host: api.altmetric.com
Response:
In this example, both the DOI and PMID resolve to the same Altmetric ID (241939), indicating they refer to the same research output. The unknown identifier (unknown-id) is not included in the response.
Try it yourself¶
Click on any of the URLs below to view example responses for the listed scenarios.
| Scenario | URL |
|---|---|
| Translate a single DOI | https://api.altmetric.com/v1/translate/10.1038/news.2011.490?key=xxx-xxx-xxx-xxx |
| Translate a single PMID | https://api.altmetric.com/v1/translate/21148220?key=xxx-xxx-xxx-xxx |
| Translate a single arXiv ID | https://api.altmetric.com/v1/translate/1108.2455?key=xxx-xxx-xxx-xxx |