Demographics¶

The Demographics endpoint gives you access to aggregated location data from X tweet, Facebook fbwall, news msm, and policy policy mentions. You can chose which one you want to see using the filter[filter] query parameter. If you don't specify one, you'll get X demographics by default.

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/demographics`¶

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

Basic GET request to get aggregated demographic data for X.

Example request:

GET /explorer/api/research_outputs/demographics?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[filter]`	No (defaults to X)	`tweet` `fbwall` `msm` `policy` `guideline`	See Mention types for an explanation of these values but note that Altmetric does not hold demographic data for all mention types so only the values in this table are supported. If you don't specify one, you'll get X demographics by default.
`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}`).

Note

The order parameters do not have any effect for the demographics because the results do not include any research outputs.

Response object¶

A GET request to the demographics 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	Two letter country code, or the word "unknown" for mentions within your search without a location attached.
`type`	string	`country`
`attributes > name`	string	Full, English name of country.
`meta`	object	Object containing details relating to the aggregated demographic attention. See Attributes for more information.

How X (Twitter) country data is derived

For filter[filter]=tweet, the country is derived from the free-text Location field on each X user's profile. Posts where the Location field is empty or doesn't resolve to a country contribute to the unknown bucket. See X (Twitter) Data for the methodology and caveats.

Attributes¶

The available meta object keys are as follows:

Key	Type	Description
`mention-count`	number	Number of mentions.
`unique-sources`	number	Number of unique entities mentioning this. ie. distinct X users or policy sources.

Data example¶

{
  "meta": { },
  "links": { },
  "data": [
    {
      "id": "UZ",
      "type": "country",
      "attributes": {
        "name": "Uzbekistan"
      },
      "meta": {
        "mention-count": 3944,
        "unique-sources": 279
      }
    }
  ]
}

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/demographics?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/demographics?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/demographics?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": "GB",
      "type": "country",
      "attributes": {
        "name": "United Kingdom"
      },
      "meta": {
        "mention-count": 4,
        "unique-sources": 3
      }
    },
    {
      "id": "US",
      "type": "country",
      "attributes": {
        "name": "United States"
      },
      "meta": {
        "mention-count": 4,
        "unique-sources": 2
      }
    },
    {
      "id": "unknown",
      "type": "country",
      "attributes": {
        "name": "Unknown"
      },
      "meta": {
        "mention-count": 2,
        "unique-sources": 2
      }
    }
  ]
}