Research Outputs¶

The Research Outputs endpoint provides you with programmatic access to all tracked research outputs (scholarly articles, datasets, and other types) matching your query criteria.

The easiest way to programmatically access this data is by build a search within the Altmetric Explorer and exporting the results to the API. For more information see Using the Altmetric Explorer to create signed API requests.

Search results are paginated and, by default, the size is set to 25 items per page. You can change this so that a maximum of 100 items are returned per request.

Warning

Responses can be quite big in size so increasing the amount of results returned per page could affect memory requirements and response times.

Request¶

`GET /explorer/api/research_outputs`¶

GET /explorer/api/research_outputs?digest={digest}&key={key}&filter[{key}]={value}...&filter[{key}][]={value}

Basic GET request to get the top scoring research outputs.

Example request:

GET /explorer/api/research_outputs?key=YOUR_API_KEY&digest=YOUR_DIGEST HTTP/1.1
Host: www.altmetric.com

Query parameters:

Parameter	Required	Accepts	Description
`digest`	Yes	A valid digest	See Authentication
`key`	Yes	A valid key	See Authentication
`filter[key]`	No	`q` `scope` `title` `published_after` `published_before` `timeframe` `orcid` `identifier_list_id`	For more information regarding filters see Filters section below
`filter[key][]`	No	`author_id` `department_id` `publisher_id` `doi_prefix` `journal_id` `funders` `handle_prefix` `affiliations` `field_of_research_codes` `sustainable_development_goals` `type` `open_access_types` `researcher_id` `grant_id`	Supports searching for multiple values. For more information regarding filters see Filters section below

Filters¶

Filters:

All filters are optional, where a single value is expected filter[publisher_id]={value} when multiple values are accepted filter[{key}][]={value}&filter[{key}][]={value}&filter[{key}][]={value}

Parameter	Multi?	Accepts/Example	Description
`order`	No	Score: `score_asc` `score_desc`	Allows research outputs to be returned in a specific order.
		Publication date: `publication_date_asc` `publication_date`
		Source: `msm` `blogs` `policy` `guideline` `patent` `twitter` `bluesky` `peer_reviews` `weibo` `facebook` `wikipedia` `gplus` `linkedin` `reddit` `pinterest` `f1000` `qna` `videos` `podcasts` `seminars` `syllabus` `citations` `mendeley`
		Mention timeframe: `mentions_1d` `mentions_3d` `mentions_1w` `mentions_1m` `mentions_3m` `mentions_6m` `mentions_1y` `mentions_at`
`publisher_id`	Yes	b4b24c0e-d515-4dea-baa6-6aef404be00d	Springer Nature
`department_id`	Yes	example-university:group:2ba9429d-a319-4018-bd02-02b55314c19d	The department identifier derived from your PURE, Elements, OAI-PMH or CSV integration. Its format is integration-dependent and often includes an instance prefix, so pass it verbatim. List all of your department IDs via the Departments endpoint.
`author_id`	Yes	9a2d7d0a-d1fe-4f04-9ea1-c6112c6eb83b	This author will be the `external_id` from your PURE, Elements, OAI-PMH or CSV integration
`doi_prefix`	Yes	10.1013	This is the DOI prefix
`scope`	No	`all` `institution`	If omitted query will be executed against the full Altmetric database
`journal_id`	Yes	4f6fa6fd3cf058f61000a3f1	This is an internal id
`funders`	Yes	grid.431093.c	GRID ID of the funder
`handle_prefix`	Yes	10016	Handle.net prefix
`affiliations`	Yes	grid.3575.4	GRID ID of the organization
`field_of_research_codes`	Yes	3006	Field of research code
`q`	Yes	health	Supports searching for a title, author name, editor name and/or journal
`sustainable_development_goals`	Yes	3	Supports search for a sustainable development goal using XYZ
`title`	Yes	Good vibrations: the role of music in Einstein's thinking	Search for a research based on it's title
`type`	Yes	`chapter` `book` `clinical_trial_study_record` `article` `dataset` `news`	Search for a research based on it's type
`open_access_types`	Yes	`closed` `oa_all` `bronze` `green` `gold` `hybrid`	Search for a research based on access status
`published_after`	No	2023-06-01	Search for research outputs published after a specific date
`published_before`	No	2023-06-22	Search for research outputs published before a specific date
`timeframe`	No	`at` `1d` `3d` `1w` `1m` `3m` `6m` `1y`	See Timeframes for more information
`orcid`	No	0000-0002-7678-0985	Search for research outputs linked to an ORCID
`identifier_list_id`	No	bba47192-a9f9-4cff-bd0c-79b86f810bf5	UUID of an identifier list. The list can be created either via the Altmetric Explorer (see Limitations) or programmatically via the Identifier Lists endpoint.
`researcher_id`	Yes	ur.015071462574.28	Dimensions Researcher ID. The ID is shown in the researcher's Dimensions profile URL (`app.dimensions.ai/discover/publication?and_facet_researcher={id}`).
`grant_id`	Yes	grant.13864430	Dimensions grant ID. The ID is shown in the grant's Dimensions URL (`app.dimensions.ai/details/grant/{id}`).

Response object¶

A GET request to the research_outputs endpoint returns a JSON object with the following keys where available.

Meta¶

Response object containing meta information about the query that was executed and the response itself.

Query¶

Key	Type	Description
`key`	string	The API key used to make the request
`digest`	string	The digest that was included in the request
`page`	object	For more information see Page
`filter`	object	For more information see Filter

Page¶

Contains pagination details for the response.

Key	Type	Description
`number`	integer	The current page number
`size`	integer	The page size. The default page size is 25 but this can be increased to 100.

Filter¶

Object containing what filter parameters have been provided and applied to the query.

Key	Type	Description
`key`	string	The name of the filter parameter used. For a complete list of filter parameters see Filters
`value`	number	The page size. The default page size is 25 but this can be increased to 100.

Response¶

Object containing information about the response. For example if it was successful or not.

Key	Type	Description
`status`	string	Friendly response status for the request.
`description`	string	A description of the query. This is the same text as appears within the Altmetric Explorer.
`total-results`	number	The total number of results matching the supplied query parameters.
`total-pages`	number	The total number of pages required to iterate in order to consume all matching results.

Meta example¶

{
  "meta": {
    "query": {
      "key": "YOUR_API_KEY",
      "digest": "YOUR_DIGEST",
      "page": {
        "number": 1,
        "size": 25
      },
      "filter": {
        "order": "publication_date",
        "q": "pandemic",
        "scope": "all",
        "timeframe": "3m",
        "type": [
          "article",
          "dataset"
        ]
      }
    },
    "response": {
      "status": "ok",
      "description": "Articles and data sets from the full Altmetric database sorted by publication date with keywords containing pandemic mentioned in the past three months",
      "total-results": 8589,
      "total-pages": 344
    }
  },
  "links": { },
  "data": { },
  "included": { }
}

Errors¶

An array of objects containing information relating to any errors preventing the response from being returned. See Status codes for additional information.

Key	Type	Description
`status`	string	HTTP response code relating to the request.
`code`	string	Altmetric status code for the error.
`title`	string	The Altmetric assigned title for the error.
`detail`	string	A detailed description of what the error is.
`source`	object	An object that contains information relating to the cause of the error. See Source for more information.

Source¶

An object that contains the parameter that resulted in the error.

Key	Type	Description
`key`	string	Currently the only key returned is `parameter`
`value`	string	Available values are `key` and `digest`

Status codes¶

These error codes are common to every Altmetric Explorer API endpoint. Some endpoints define additional error codes, which are documented on their respective pages.

Status	Code	Title	Details
`400`	`missing_api_key`	Missing API key	Requests to the Altmetric Explorer API must include your API key in the "key" parameter. You did not supply a key.
`400`	`invalid_api_key`	Invalid API key	Requests to the Altmetric Explorer API must include your API key in the "key" parameter. The supplied key was not valid.
`400`	`expired_api_key`	Expired API key	Requests to the Altmetric Explorer API must include your API key in the "key" parameter. The supplied key was expired.
`400`	`invalid_digest`	Invalid API request signature	Requests to the Altmetric Explorer API must be signed with your API secret, and the digest provided in the "digest" parameter. The signature for this request was missing or invalid.
`400`	`invalid_filter_format`	Invalid filter format	The "filter" parameter must be a hash of filter criteria. The supplied filter was not in the correct format.
`400`	`no_api_access`	API access not allowed	Your organisation does not have access to the Altmetric Explorer API.

Errors example¶

{
  "meta": {
    "response": {
      "status": "error"
    }
  },
  "errors": [
    {
      "status": "400",
      "code": "invalid_digest",
      "title": "Invalid API request signature",
      "detail": "Requests to the Altmetric Explorer API must be signed with your API secret, and the digest provided in the \"digest\" parameter. The signature for this request was missing or invalid.",
      "source": {
        "parameter": "digest"
      }
    }
  ]
}

Links¶

Object containing page navigation information.

Key	Type	Description
`self`	string	The `self` link is a URL that refers back to the exact resource representation that was requested.
`first`	string	The `first` link provides a URL to access the first page of results.
`last`	string	The `last` link provides a URL to access the last page of results.
`next`	string	The `next` link provides the URL to access the next page of data. It is not present on the last page of results.
`prev`	string	The `prev` link provides the URL to access the previous page of data. It is not present on the first page of results.

Links example¶

{
  "meta": { },
  "links": {
    "self": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Border%5D=blogs&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Border%5D=blogs&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Border%5D=blogs&key=YOUR_API_KEY&page%5Bnumber%5D=965&page%5Bsize%5D=25",
    "next": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Border%5D=blogs&key=YOUR_API_KEY&page%5Bnumber%5D=2&page%5Bsize%5D=25"
  },
  "data": { },
  "included": { }
}

Data¶

An array of research output objects

Key	Type	Description
`id`	number	Altmetric ID associated with the research output. Altmetric IDs are internal transient identifiers and unstable over the medium term.
`type`	string	`research-output`
`attributes`	object	Object containing details relating to the research output
`relationships`	object	Object containing relationships between the research output and journals, institutional authors, institutional departments, affiliations, fields of research and funders

Attributes¶

Key	Type	Description
`title`	string	Title of the output
`identifiers`	object	Any identifiers Altmetric has disambiguated for this output. Possible values are: `doi`, `handle`, `ssrn`, `uri`, `urn`, `isbn`, `pubmed`, `ads`, `arxiv`, `repec`, `pmc` and `nct`.
`readers > mendeley`	number	Number of people who have bookmarked this output in Mendeley.
`dimensions > citations`	number	The total number of publications that cite this research output. Citation counts are provided by Dimensions.
`mentions`	object	How many of each type of mention. See Mention types for a list of possible values.
`altmetric-score`	number	The current Altmetric Attention Score, rounded up to a whole number as Altmetric displays it everywhere else. A research output scoring 0.25 is reported here as `1`. The Details Page API returns the same score unrounded.
`output-type`	string	The type of output we've detected this is, typically `article`.
`historical-mentions`	object	Timeframes, and the number of mentions if we were only considering mentions for that timeframe. See Timeframes for more information.
`publication-date`	string, "YYYY-MM-DD"	Publication date for the research output.
`badge-url`	string	A URL you can use to display the Altmetric badge of this output.
`oa-status`	boolean	Open Access status for the research output.
`oa-type`	string	Type of Open Access for the research output. Possible values are: `bronze`, `closed`, `gold`, `green`, `hybrid` and empty.
`institution > verified`	boolean	Only present for customers with an institutional data implementation. It is `true` if the research output belongs to the institution.
`sentiment-analysis-totals`	object	A breakdown of how many mentions of this research output fell into each sentiment category. See Sentiment analysis totals below.

The score is rounded up, and averages built on it will be too

altmetric-score is rounded up to a whole number, matching what a customer sees on a details page, on a badge and in the Explorer itself, so every research output with any attention at all reports at least 1. The difference is largest where the score is smallest: 0.25 and 0.5 both become 1. An average of these scores is therefore not the same figure as an average of the unrounded scores the Details Page API returns, and the gap is widest across research outputs with little attention.

Sentiment analysis totals¶

The sentiment-analysis-totals object aggregates the research output's mentions across the seven sentiment categories. It is returned for every research output unless your organization has AI features restricted — including research outputs with no scored mentions, where all seven counts are zero. Sentiment is currently computed for X (tweet) and Bluesky (bluesky) mentions only.

Key	Type	Description
`strong-negative`	number	Number of mentions with strongly negative sentiment.
`negative`	number	Number of mentions with negative sentiment.
`neutral-negative`	number	Number of mentions with slightly negative sentiment.
`neutral`	number	Number of mentions with neutral sentiment.
`neutral-positive`	number	Number of mentions with slightly positive sentiment.
`positive`	number	Number of mentions with positive sentiment.
`strong-positive`	number	Number of mentions with strongly positive sentiment.

Relationships¶

Key	Type	Description
`journal`	object (Journal Resource)	Use the `id` and `type` in the `included` field to find the journal.
`institutional-authors`	Array	Only present for customers with an institutional data implementation and when there are any institutional authors linked to the publication. Use the `id` and `type` in the `included` field to find the author name.
`institutional-departments`	Array	Only present for customers with an institutional data implementation and when there are any institutional departments linked to the publication. Use the `id` and `type` in the `included` field to find the department name.
`affiliations`	Array	Author affiliations associated with individual research outputs are provided by Dimensions and are categorized by GRID. Each affiliation has a GRID ID, which is a unique identifier for that organization. Use the `id` and `type` in the `included` field to find more information about the affiliation.
`fields-of-research`	Array	Subject areas associated with individual research outputs are provided by Dimensions. Subject areas are classified according to the Fields of Research (FoR) system. Use the `id` and `type` in the `included` field to find more information about the subject area.
`funders`	Array	Funding institutions associated with individual research outputs are provided by Dimensions and are categorized by GRID. Each funder has a GRID ID, which is a unique identifier for that organization. Use the `id` and `type` in the `included` field to find more information about the funder.
`sustainable-development-goals`	Array	Sustainable Development Goals associated with individual research outputs are provided by Dimensions. Use the `id` and `type` in the `included` field to find more information about the Sustainable Development Goal.
`supportive-grants`	Array	Supportive Grants associated with individual research outputs are provided by Dimensions. Use the `id` and `type` in the `included` field to find more information about the Supportive Grant.

Data example¶

{
  "meta": { },
  "links": { },
  "data" : [
    {
      "id": 2902796,
      "type": "research-output",
      "attributes": {
        "title": "How Diversity Works",
        "identifiers": {
          "dois": [
            "10.1038/scientificamerican1014-42"
          ],
          "uris": [
            "http://www.nature.com/doifinder/10.1038/scientificamerican1014-42"
          ]
        },
        "readers": {
          "mendeley": 51
        },
        "dimensions": {
          "citations": 19
        },
        "mentions": {
          "blog": 30,
          "fbwall": 750,
          "gplus": 32,
          "msm": 153,
          "qna": 1,
          "tweet": 13623,
          "video": 2,
          "wikipedia": 1
        },
        "altmetric-score": 10808,
        "output-type": "article",
        "historical-mentions": {
          "1d": 3,
          "3d": 8,
          "1w": 18,
          "1m": 97,
          "3m": 409,
          "6m": 1060,
          "1y": 8794,
          "at": 14592
        },
        "publication-date": "2014-09-16",
        "badge-url": "https://api.altmetric.com/v1/donut/2902796_240.png",
        "oa-status": true,
        "oa-type": "gold",
        "institution": {
          "verified": false
        },
        "sentiment-analysis-totals": {
          "strong-negative": 23,
          "negative": 217,
          "neutral-negative": 5,
          "neutral": 362,
          "neutral-positive": 464,
          "positive": 9,
          "strong-positive": 7
        }
      },
      "relationships": {
        "journal": {
          "id": "4f6fa4d33cf058f610000f42",
          "type": "journal"
        },
        "affiliations": [
          {
            "id": "grid.266091.8",
            "type": "grid-affiliation"
          }
        ],
        "fields-of-research": [
          {
            "id": "09",
            "type": "field-of-research"
          }
        ],
        "funders": [
          {
            "id": "grid.238223.c",
            "type": "grid-funder"
          }
        ],
        "sustainable-development-goals": [
          {
            "id": "7",
            "type": "sustainable-development-goal"
          }
        ]
      }
    }
  ],
  "included": { }
}

Included¶

A data dictionary that can be used to look up various information as part of the deduplication and disambiguation process.

Key	Type	Description
`id`	string	The identifier that relates to the deduplicated/disambiguated object found in within Data.
`type`	string	The type that relates to the deduplicated/disambiguated object found in within Data. Available types include: `author` `department` `field-of-research` `grid-affiliation` `grid-funder` `sustainable-development-goal` `profile` and `supportive-grant`
`attributes`	object	Type specific attributes that relate to the deduplicated/disambiguated object found in within Data. See Attributes for more information
`relationships`	object	Object containing information about the author of the mention and the research outputs mentioned. See Relationships for more information.

For example, the relationships attribute for a research-output in data might return the following object:

"data": [
  {
    "id": 69136930,
    "type": "research-output",
    "relationships": {
        "affiliations": [
          {
            "id": "grid.133342.4",
            "type": "grid-affiliation"
          }
        ]
    }
  }
]

Rather than the full details for the grid-affiliation being returned every time it appears as part of a relationship we just return its id and type. You'd use this information to query included to get any additional information to have for it.

"included": [
  {
    "id": "grid.133342.4",
    "type": "grid-affiliation",
    "attributes": {
      "name": "University of California, Santa Barbara",
      "country": "United States",
      "acronym": "UCSB"
    }
  }
]

Important

When querying the included lookup dictionary, remember to always use both the id and type as some third-party identifiers might not be unique within the Altmetric Explorer API or may apply to difference contexts.

Attributes¶

Provides additional information about disambiguated/deduplicated objects.

Key	Type	Description
`title`	string	If a journal, the official title of the deduplicated/disambiguated object.
`name`	string	The official name of the deduplicated/disambiguated object.
`issns`	array	An array of unique identifier used for print or electronic periodical publications.
`country`	string	The official name of the country relating to the deduplicated/disambiguated object.
`acronym`	string	If an organization, the GRID acronym associated with the deduplicated/disambiguated object.

Included example¶

{
  "meta": { },
  "links": { },
  "data": [ ],
  "included": [
    {
      "id": "5ebd17d39185c900114d426e",
      "type": "journal",
      "attributes": {
        "title": "Frontiers in Sports and Active Living",
        "issns": [
          "26249367"
        ]
      }
    },
    {
      "id": "grid.5884.1",
      "type": "grid-affiliation",
      "attributes": {
        "name": "Sheffield Hallam University",
        "country": "United Kingdom",
        "acronym": "SHU"
      }
    },
    {
      "id": "11",
      "type": "field-of-research",
      "attributes": {
        "name": "Medical and Health Sciences"
      }
    }
  ]
}

Example response¶

{
  "meta": {
    "query": {
      "key": "YOUR_API_KEY",
      "digest": "YOUR_DIGEST",
      "page": {
        "number": 1,
        "size": 25
      },
      "filter": {
        "identifier_list_id": "bba47192-a9f9-4cff-bd0c-79b86f810bf5",
        "scope": "all"
      }
    },
    "response": {
      "status": "ok",
      "description": "All research outputs from the full Altmetric database with 1 identifier sorted by Altmetric Attention Score",
      "total-results": 1,
      "total-pages": 1
    }
  },
  "links": {
    "self": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Bidentifier_list_id%5D=bba47192-a9f9-4cff-bd0c-79b86f810bf5&filter%5Bscope%5D=all&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Bidentifier_list_id%5D=bba47192-a9f9-4cff-bd0c-79b86f810bf5&filter%5Bscope%5D=all&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://www.altmetric.com/explorer/api/research_outputs?digest=YOUR_DIGEST&filter%5Bidentifier_list_id%5D=bba47192-a9f9-4cff-bd0c-79b86f810bf5&filter%5Bscope%5D=all&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25"
  },
  "data": [
    {
      "id": 151229835,
      "type": "research-output",
      "attributes": {
        "title": "A systematic narrative review of extrinsic strategies to improve affective responses to exercise",
        "identifiers": {
          "dois": [
            "10.3389/fspor.2023.1186986"
          ]
        },
        "readers": {
          "mendeley": 0
        },
        "dimensions": {
          "citations": 0
        },
        "mentions": {
          "tweet": 10
        },
        "altmetric-score": 5,
        "output-type": "article",
        "historical-mentions": {
          "1d": 0,
          "3d": 1,
          "1w": 4,
          "1m": 10,
          "3m": 10,
          "6m": 10,
          "1y": 10,
          "at": 10
        },
        "publication-date": "2023-07-11",
        "badge-url": "https://api.altmetric.com/v1/donut/151229835_240.png",
        "oa-status": true,
        "oa-type": "gold",
        "institution": {
          "verified": false
        },
        "sentiment-analysis-totals": {
          "strong-negative": 0,
          "negative": 1,
          "neutral-negative": 0,
          "neutral": 7,
          "neutral-positive": 1,
          "positive": 1,
          "strong-positive": 0
        }
      },
      "relationships": {
        "journal": {
          "id": "5ebd17d39185c900114d426e",
          "type": "journal"
        },
        "affiliations": [
          {
            "id": "grid.253553.7",
            "type": "grid-affiliation"
          },
          {
            "id": "grid.5884.1",
            "type": "grid-affiliation"
          }
        ],
        "fields-of-research": [
          {
            "id": "11",
            "type": "field-of-research"
          },
          {
            "id": "1117",
            "type": "field-of-research"
          },
          {
            "id": "42",
            "type": "field-of-research"
          },
          {
            "id": "4206",
            "type": "field-of-research"
          }
        ]
      }
    }
  ],
  "included": [
    {
      "id": "5ebd17d39185c900114d426e",
      "type": "journal",
      "attributes": {
        "title": "Frontiers in Sports and Active Living",
        "issns": [
          "26249367"
        ]
      }
    },
    {
      "id": "grid.253553.7",
      "type": "grid-affiliation",
      "attributes": {
        "name": "California State University, Bakersfield",
        "country": "United States",
        "acronym": "CSUB"
      }
    },
    {
      "id": "grid.5884.1",
      "type": "grid-affiliation",
      "attributes": {
        "name": "Sheffield Hallam University",
        "country": "United Kingdom",
        "acronym": "SHU"
      }
    },
    {
      "id": "11",
      "type": "field-of-research",
      "attributes": {
        "name": "Medical and Health Sciences"
      }
    },
    {
      "id": "1117",
      "type": "field-of-research",
      "attributes": {
        "name": "Public Health and Health Services"
      }
    },
    {
      "id": "42",
      "type": "field-of-research",
      "attributes": {
        "name": "Health Sciences"
      }
    },
    {
      "id": "4206",
      "type": "field-of-research",
      "attributes": {
        "name": "Public Health"
      }
    }
  ]
}

Research Outputs¶

Request¶

GET /explorer/api/research_outputs¶

Filters¶

Response object¶

Meta¶

Query¶

Page¶

Filter¶

Response¶

Meta example¶

Errors¶

Source¶

Status codes¶

Errors example¶

Links¶

Links example¶

Data¶

Attributes¶

Sentiment analysis totals¶

Relationships¶

Data example¶

Included¶

Attributes¶

Included example¶

Example response¶

`GET /explorer/api/research_outputs`¶