Attention Summary¶

The Attention Summary endpoint gives you access to the aggregated attention data for research outputs matching your query.

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 is a single page endpoint, and so has no need for pagination.

Request¶

`GET /explorer/api/research_outputs/attention`¶

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

Basic GET request to get aggregated attention data grouped by source and date.

Example request:

GET /explorer/api/research_outputs/attention?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 for more information.
`key`	Yes	A valid key	See Authentication for more information.
`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 attention 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 objects

Key	Type	Description
`id`	number	One of the supported Altmetric attention sources, like `fbwall` (Facebook). See Mention types for a complete list.
`type`	string	`source`
`meta`	object	Object containing details relating to the aggregated attention. See Attributes for more information.

Attributes¶

The available meta object keys are as follows:

Key	Type	Description
`total`	number	The total number of mentions for your query, for the specific attention source.
`dates[]`	array	A breakdown of each of the dates that a mention occurred, and how many times on that day it was mentioned. The date is returned in ascending order.
`dates[] > date`	string	The date of the mention.
`dates[] > count`	String, "YYYY-MM-DD"	The total number on mentions on this date.

Data example¶

{
  "meta": { },
  "links": { },
  "data": [
    {
      "id": "msm",
      "type": "source",
      "meta": {
        "total": 1,
        "dates": [
          {
            "date": "2000-12-13",
            "count": 1
          }
        }
      },
      {
      "id": "twitter",
      "type": "source",
      "meta": {
        "total": 3,
        "dates": [
          {
            "date": "2001-02-04",
            "count": 1
          },
          {
            "date": "2005-07-04",
            "count": 2
          }
        }
      }
  ]
}

Example response¶

{
  "meta": {
    "query": {
      "key": "YOUR_API_KEY",
      "digest": "YOUR_DIGEST",
      "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/attention?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",
    "first": "https://www.altmetric.com/explorer/api/research_outputs/attention?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",
    "last": "https://www.altmetric.com/explorer/api/research_outputs/attention?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"
  },
  "data": [
    {
      "id": "tweet",
      "type": "source",
      "meta": {
        "total": 10,
        "dates": [
          {
            "date": "2023-07-11",
            "count": 5
          },
          {
            "date": "2023-07-12",
            "count": 1
          },
          {
            "date": "2023-07-22",
            "count": 3
          },
          {
            "date": "2023-07-24",
            "count": 1
          }
        ]
      }
    }
  ]
}