Mentions¶

The Mentions endpoint gives you access to all of the individual mentions of the research outputs from your search.

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.

Note

This endpoint can return a large number of results, and so it is paginated. Please refer to the Pagination section of the documentation to see how this works.

Important

This is the only endpoint that returns individual X (Twitter) post IDs, so it is subject to a limit on how many your organization can retrieve — see X post ID limit for the policy. Track your usage with the X-TweetIDRateLimit-Limit and X-TweetIDRateLimit-Remaining response headers; once the limit is reached, requests return a tweet_id_rate_limit_exceeded error.

Request¶

`GET /explorer/api/research_outputs/mentions`¶

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

Basic GET request to get mention data.

Example request:

GET /explorer/api/research_outputs/mentions?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
`include`	No	`journal` `profile` `research-output`	`journal` shows information about the relevant journal, like ISSNs. `profile` shows information about the author of the mention. `research-output` shows information about the research output that has been mentioned. If omitted all types will be included.
`filter[sentiment][]`	No	A sentiment score from `-3` to `3`.	Return only mentions carrying these sentiment scores. See Sentiment scores below. Sentiment is computed for X and Bluesky mentions only.
`filter[highlights]`	No	`true`	Return only the mentions the Explorer treats as highlights, the same subset shown on its Highlights tab. Any other value is ignored.
`filter[mention_types][]`	No	A mention type, for example: `msm`, `tweet`, `bluesky`, `rdt`.	Return only mentions of these types. See Mention types for the list. A type this endpoint holds no mentions for returns an empty result rather than an error, so check the spelling before reading anything into it.
`filter[mention_sources][]`	No	`type:{mention type}`, or the id of a mention source.	Return only mentions from these sources. `type:msm` is equivalent to `filter[mention_types][]=msm`; an id restricts the results to one outlet or account.
`filter[countries][]`	No	A valid ISO 3166-1 country code, alpha-2 or alpha-3, for example: `IT`, `US`, `IE`, `ITA`.	Subdivision codes such as `US-CA` are not accepted and are ignored. A full and complete list can be found here: https://en.wikipedia.org/wiki/ISO_3166-1
`filter[mentioned_after]`	No	A valid date "YYYY-MM-DD"	Filter mentions created after the specified date.
`filter[mentioned_before]`	No	A valid date "YYYY-MM-DD"	Filter mentions created before the specified date.
`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

Sentiment scores¶

filter[sentiment][] matches on the numeric score, not its name:

Score	Meaning
`-3`	Strong negative
`-2`	Negative
`-1`	Neutral negative
`0`	Neutral
`1`	Neutral positive
`2`	Positive
`3`	Strong positive

Passing a name such as Positive rather than its score is not a valid filter value.

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 mentions 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"
      }
    }
  ]
}

Additional error codes¶

In addition to the common error codes, the mentions endpoint can return:

Status	Code	Title	Details
`400`	`tweet_id_rate_limit_exceeded`	X post ID rate limit exceeded	X post ID rate limit exceeded, please see X-TweetIdRateLimit headers and try again later.

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 objects.

Key	Type	Description
`id`	number	Unique internal identifier for this mention.
`type`	string	`mention`
`attributes`	object	Object containing information about the mention. 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.

Attributes¶

The available attributes object keys are as follows:

Key	Type	Description
`url`	string	Shows the external page where the mention can be seen.
`posted-on`	string "YYYY-MM-DD HH:MM:SS UTC"	The time when the author published their mention.
`post-type`	string	For example `fbwall`. See Mention types for a complete list.
`summary`	string	An excerpt of the body of the post.
`external-id`	string	The third-party identifier for the mention.
`sentiment-analysis`	array	The sentiment expressed by this mention towards each research output it mentions. Each entry is an object with a `research-output-id` (number) and a `sentiment` (string). See Sentiment analysis below.

Note

For licensing reasons an X mention carries only its identifiers: no post body, and no account handle or display name. See X data.

Sentiment analysis¶

The sentiment-analysis attribute is present on scored mentions, unless your organization has AI features restricted. Sentiment is currently computed for X (tweet) and Bluesky (bluesky) posts only; mentions of other types, and individual research outputs within a mention that have not been scored, are omitted from the array. When none of the mention's research outputs have been scored, the attribute is omitted entirely rather than returned as an empty array. A mention can reference more than one research output, so the array contains one entry per scored research output.

Key	Type	Description
`research-output-id`	number	The Altmetric ID of the research output this sentiment applies to.
`sentiment`	string	One of `Strong negative`, `Negative`, `Neutral negative`, `Neutral`, `Neutral positive`, `Positive`, `Strong positive`.

Relationships¶

The available relationships object keys are as follows:

Key	Type	Description
`author`	object	Use this to find the deduplicated author in the `included` resources. See Deduplicated object for more information.
`research-outputs[]`	array	Use these to find the deduplicated research outputs in the `included` resources. See Research Outputs for more information.

Deduplicated object¶

Key	Type	Description
`data > id`	string	The identifier for the object.
`data > type`	string	The type of the deduplicated object. Available types are `profile` `research-output`

Data example¶

{
  "meta": { },
  "links": { },
  "data": [
    {
      "id": 699586580,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1683398879893495809",
        "posted-on": "2023-07-24 08:49:03 UTC",
        "post-type": "tweet",
        "sentiment-analysis": [
          {
            "research-output-id": 151229835,
            "sentiment": "Positive"
          }
        ]
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:422104484",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    }
  ],
  "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.

Where the included object is a research-output the Altmetric Explorer API will return a research-output object. See Research Outputs - Data for a full list of attributes.

Relationships¶

The relationships key is only present on a research-output object. See Research Outputs - Relationships for a full list of attributes.

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": 10,
      "total-pages": 1
    }
  },
  "links": {
    "self": "https://www.altmetric.com/explorer/api/research_outputs/mentions?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/mentions?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/mentions?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": 699586580,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1683398879893495809",
        "posted-on": "2023-07-24 08:49:03 UTC",
        "post-type": "tweet",
        "sentiment-analysis": [
          {
            "research-output-id": 151229835,
            "sentiment": "Positive"
          }
        ]
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:422104484",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    }
  ],
  "included": [
    {
      "id": "tw:id:422104484",
      "type": "profile",
      "attributes": {
        "profile-type": "tw"
      }
    },
    {
      "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": 0,
          "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
        }
      },
      "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"
          }
        ]
      }
    }
  ]
}

Mentions¶

Request¶

GET /explorer/api/research_outputs/mentions¶

Sentiment scores¶

Filters¶

Response object¶

Meta¶

Query¶

Page¶

Filter¶

Response¶

Meta example¶

Errors¶

Source¶

Status codes¶

Errors example¶

Additional error codes¶

Links¶

Links example¶

Data¶

Attributes¶

Sentiment analysis¶

Relationships¶

Deduplicated object¶

Data example¶

Included¶

Attributes¶

Relationships¶

Included example¶

Example response¶

`GET /explorer/api/research_outputs/mentions`¶