X (formerly Twitter) data in Altmetric's APIs and exports¶

This page describes what X data Altmetric makes available through the Details Page API, the Explorer API, and the Explorer CSV exports, how geographic data is derived, and how to hydrate Tweet and User IDs into full posts via X's own APIs.

The information here applies equally to:

• The Details Page API (Fetch responses, in particular the posts.twitter and demographics.geo.twitter sections).
• The Explorer API (Mentions and Demographics endpoints).
• The CSV exports produced by the Explorer.

Background¶

Altmetric has tracked attention from X (formerly Twitter) since the early days of the platform. In July 2019, as part of our licensing agreement with X, we made changes to the X data surfaced in our APIs and CSV exports. On 30 June 2024, X retired the Gnip enterprise products that had previously fed us this data, and we now ingest X mentions via the X API v2 Filtered Stream.

The list of fields available in our APIs and CSV exports has not changed across these transitions. For backwards compatibility, the API and CSV exports continue to use the legacy Twitter field names — for example tweet_id, tweeter_id, cited_by_tweeters_count, and a license value of gnip.

What X data is available¶

The Altmetric APIs and CSV exports include the following X-related data, where applicable:

• Post ID (the X identifier for an individual post, also referred to as a Tweet ID).
• User ID (the X identifier for the posting account).
• Post date (the date and time the post was published).
• Aggregated post counts for a research output.
• Aggregated demographics (for example, member of the public, researcher, practitioner, science communicator).
• Aggregated post counts by country.

In the Explorer API the Post ID is exposed as external-id, and the User ID as id under author. In the Details Page API they are exposed as tweet_id and tweeter_id respectively. In the Explorer CSV exports the Post ID is the External Mention ID column and the User ID is the Outlet or Author column. The post date is exposed as posted-on in the Explorer API, posted_on in the Details Page API, and the Mention Date column in the Explorer CSV exports.

Reconstructing a post URL¶

Given a Post ID and a User ID you can reconstruct the canonical URL to the original post:

https://twitter.com/{user_id}/status/{post_id}

For example, a post with User ID 895631986718461954 and Post ID 920932138668691457 can be opened at:

https://twitter.com/895631986718461954/status/920932138668691457

X will resolve the numeric handle to the current screen name at request time, so this works even if the user has changed their handle since posting.

Geographic data¶

Altmetric provides country-level geographic context for X attention by associating each X profile with a country. The country is derived from the free-text Location field on the user's X profile — for example, a profile listing "California" resolves to the United States. Country data is exposed in the Explorer interface, in demographics.geo.twitter on the Details Page API, in the Demographics endpoint of the Explorer API, and in country breakdowns in the Explorer CSV exports.

The country is associated with the profile, not with the individual post — X does not expose per-post coordinates to us, and never has.

Where the country derivation comes from¶

Prior to 30 June 2024, X delivered a derived country code alongside each post via its Gnip enterprise feed. When X retired that feed, Altmetric brought the resolution in-house so that customer-facing fields would continue to be populated. The input data is the same — the user's free-text Location field on their X profile — and the same caveats apply.

Caveats¶

Because the Location field on an X profile is free-form, there are several cases where no country can be attached to a post:

• The user has left the Location field blank.
• The user has entered something fictional or non-geographic (for example, "Narnia", "Everywhere", "the internet").
• The user has entered something too ambiguous to resolve to a country (for example, "UCLA" alone, with no city or country context).
• The user has entered something that resolves to more than one country (for example, an ambiguous place name shared by several countries).

In all these cases the post is still collected and counted; it simply contributes to the overall mention totals without contributing to the country-level breakdown.

A small number of posts collected prior to the June 2024 transition may show country data derived under X's previous methodology. The customer-facing fields are identical in either case.

Obtaining additional X information¶

If your project needs information about posts or users that is not available through Altmetric's APIs, you will need to request it directly from X. You can use the Post IDs and User IDs returned by Altmetric's APIs to query the X API.

With an active X API plan, you can hydrate Post IDs via the v2 tweets lookup endpoint, which accepts up to 100 IDs per request and returns metadata only for posts that are still publicly available. Deleted, suspended, or otherwise unavailable posts are silently dropped.