Mention Sources¶

The Mention Sources endpoint gives you access to the number mentions per mention source 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.

Request¶

`GET /explorer/api/research_outputs/mention_sources`¶

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

Basic GET request to get mention data.

Example request:

GET /explorer/api/research_outputs/mention_sources?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[mention_sources_types][]`	No	`type:{profile type}`, for example: `type:msm`, `type:bsk`.	Return only sources of these types. Profile types are listed below and are not the same strings as the mention types used elsewhere.
`filter[mention_sources_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[mention_sources_mentioned_after]`	No	A valid date "YYYY-MM-DD"	Filter mentions created after the specified date. Required whenever `filter[mention_sources_mentioned_before]` is given.
`filter[mention_sources_mentioned_before]`	No	A valid date "YYYY-MM-DD"	Filter mentions created before the specified date. Must be within one year of `filter[mention_sources_mentioned_after]`.
`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

Profile types¶

filter[mention_sources_types][] matches on the type of the profile behind a mention, which is not always the same string as the mention type:

Mention type	Profile type
`msm`	`msm`
`blog`	`blog`
`policy`	`policy`
`guideline`	`guideline`
`tweet`	`tw`
`bluesky`	`bsk`
`fbwall`	`fb`
`weibo`	`sw`
`rdt`	`rdt`
`gplus`	`gplus`
`linkedin`	`linkedin`
`podcast`	`podcast`
`seminar`	`seminar_series`

Mention types that are not in this table have no profile records behind them and cannot be filtered on this endpoint. Use the Mentions endpoint with filter[mention_types][] for those.

This endpoint namespaces the filters it shares with Mentions

The date and country filters are named mention_sources_mentioned_after, mention_sources_mentioned_before and mention_sources_countries here, not mentioned_after, mentioned_before and countries as on the Mentions endpoint. Both spellings produce a valid request signature, so sending the unprefixed name returns unfiltered results with no error rather than being rejected.

The date range is also constrained: an end date requires a start date, and the two must be within a year of each other.

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 mention_sources 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 mention sources endpoint can return:

Status	Code	Title	Details
`400`	`restricted_access`	Access not allowed	Your organisation does not have access to the mention sources endpoint.

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.

Note

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

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"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:422104484",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 699348996,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1682781823577759745",
        "posted-on": "2023-07-22 15:57:05 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:2356088348",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 699345372,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1682774061225500672",
        "posted-on": "2023-07-22 15:26:15 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:2917802474",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 699344798,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1682772847507255296",
        "posted-on": "2023-07-22 15:21:25 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:2917802474",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697216573,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1679085044357292034",
        "posted-on": "2023-07-12 11:07:25 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:1406272358856409097",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697079146,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1678838171088433156",
        "posted-on": "2023-07-11 18:46:25 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:570239474",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697033365,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1678785616291438592",
        "posted-on": "2023-07-11 15:17:35 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:835599412936212480",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697024843,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1678777050826682369",
        "posted-on": "2023-07-11 14:43:33 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:1105492517397692417",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697011025,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1678763763141599236",
        "posted-on": "2023-07-11 13:50:45 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:2917802474",
            "type": "profile"
          }
        },
        "research-outputs": [
          {
            "data": {
              "id": 151229835,
              "type": "research-output"
            }
          }
        ]
      }
    },
    {
      "id": 697008378,
      "type": "mention",
      "attributes": {
        "external-id": "twitter.1678760800834686977",
        "posted-on": "2023-07-11 13:38:59 UTC",
        "post-type": "tweet"
      },
      "relationships": {
        "author": {
          "data": {
            "id": "tw:id:2356088348",
            "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": {
        "timeframe": "3m"
      }
    },
    "response": {
      "status": "ok",
      "description": "All research outputs sorted by Altmetric Attention Score mentioned in the past three months",
      "total-results": 7841836,
      "total-pages": 313674,
      "total-mentions": 75670419
    }
  },
  "links": {
    "self": "https://www.altmetric.com/explorer/api/research_outputs/mention_sources?digest=YOUR_DIGEST&filter%5Btimeframe%5D=3m&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://www.altmetric.com/explorer/api/research_outputs/mention_sources?digest=YOUR_DIGEST&filter%5Btimeframe%5D=3m&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://www.altmetric.com/explorer/api/research_outputs/mention_sources?digest=YOUR_DIGEST&filter%5Btimeframe%5D=3m&key=YOUR_API_KEY&page%5Bnumber%5D=313674&page%5Bsize%5D=25",
    "next": "https://www.altmetric.com/explorer/api/research_outputs/mention_sources?digest=YOUR_DIGEST&filter%5Btimeframe%5D=3m&key=YOUR_API_KEY&page%5Bnumber%5D=2&page%5Bsize%5D=25"
  },
  "data": [
    {
      "id": "msm:yahoo_news",
      "type": "profile",
      "attributes": {
        "profile-type": "msm",
        "name": "Yahoo! News",
        "image": "https://s3.amazonaws.com/weyland.altmetric.com/news_sources/logos/000/000/032/normal/yahoo_news.png?1369846922"
      },
      "relationships": {
        "country": {
          "data": {
            "id": "US",
            "type": "country"
          }
        }
      },
      "meta": {
        "mention-count": 200716
      }
    }
  ],
  "included": [
    {
      "id": "US",
      "type": "country",
      "attributes": {
        "name": "United States"
      }
    }
  ]
}

Mention Sources¶

Request¶

GET /explorer/api/research_outputs/mention_sources¶

Profile types¶

Filters¶

Response object¶

Meta¶

Query¶

Page¶

Filter¶

Response¶

Meta example¶

Errors¶

Source¶

Status codes¶

Errors example¶

Additional error codes¶

Links¶

Links example¶

Data¶

Attributes¶

Relationships¶

Deduplicated object¶

Data example¶

Included¶

Attributes¶

Relationships¶

Included example¶

Example response¶

`GET /explorer/api/research_outputs/mention_sources`¶