Plumx metrics api

PlumX Metrics API

Overview

PlumX (by Elsevier/Plum Analytics) tracks 5 categories of research impact metrics beyond traditional citations: Usage, Captures, Mentions, Social Media, and Citations. It covers 130M+ research artifacts including articles, datasets, presentations, and videos. Available via Elsevier's API infrastructure. Requires an Elsevier API key.

Metric Categories

Category	What it measures	Examples
Usage	Reading/viewing	Abstract views, PDF downloads, HTML views
Captures	Saving for later	Mendeley readers, CiteULike bookmarks
Mentions	Commentary	Blog posts, news articles, Wikipedia refs
Social Media	Sharing/discussion	Tweets, Facebook shares, Reddit posts
Citations	Formal references	Scopus, CrossRef, PubMed citations

API Endpoints

Base URL

https://api.elsevier.com/analytics/plumx/

Get Metrics by DOI

curl -H "X-ELS-APIKey: $ELSEVIER_API_KEY" \
  "https://api.elsevier.com/analytics/plumx/doi/10.1038/nature14539"

Get Metrics by Other IDs

# By PubMed ID
curl -H "X-ELS-APIKey: $ELSEVIER_API_KEY" \
  "https://api.elsevier.com/analytics/plumx/pmid/25428114"

# By ISBN
curl -H "X-ELS-APIKey: $ELSEVIER_API_KEY" \
  "https://api.elsevier.com/analytics/plumx/isbn/9780262035613"

# By Scopus ID
curl -H "X-ELS-APIKey: $ELSEVIER_API_KEY" \
  "https://api.elsevier.com/analytics/plumx/scopusId/84920765826"

Response Structure

{
  "count_categories": [
    {
      "name": "capture",
      "total": 15432,
      "count_types": [
        {"name": "READER_COUNT", "total": 15432, "sources": [
          {"name": "Mendeley", "total": 15432}
        ]}
      ]
    },
    {
      "name": "socialMedia",
      "total": 3250,
      "count_types": [
        {"name": "TWEET_COUNT", "total": 2800},
        {"name": "FACEBOOK_COUNT", "total": 450}
      ]
    },
    {
      "name": "citation",
      "total": 2100,
      "count_types": [
        {"name": "Scopus", "total": 1800},
        {"name": "CrossRef", "total": 2100}
      ]
    },
    {
      "name": "usage",
      "total": 45000,
      "count_types": [
        {"name": "ABSTRACT_VIEWS", "total": 30000},
        {"name": "LINK_OUTS", "total": 15000}
      ]
    },
    {
      "name": "mention",
      "total": 85,
      "count_types": [
        {"name": "NEWS_COUNT", "total": 45},
        {"name": "BLOG_COUNT", "total": 25},
        {"name": "WIKIPEDIA_COUNT", "total": 15}
      ]
    }
  ]
}

Python Usage

import os
import requests

API_KEY = os.environ["ELSEVIER_API_KEY"]
BASE_URL = "https://api.elsevier.com/analytics/plumx"
HEADERS = {"X-ELS-APIKey": API_KEY, "Accept": "application/json"}


def get_plumx_metrics(doi: str) -> dict:
    """Get PlumX metrics for a paper by DOI."""
    resp = requests.get(
        f"{BASE_URL}/doi/{doi}",
        headers=HEADERS,
    )
    resp.raise_for_status()
    data = resp.json()

    metrics = {}
    for cat in data.get("count_categories", []):
        category_name = cat["name"]
        metrics[category_name] = {
            "total": cat["total"],
            "breakdown": {},
        }
        for ct in cat.get("count_types", []):
            metrics[category_name]["breakdown"][ct["name"]] = ct["total"]
    return metrics


def compare_impact(dois: list) -> list:
    """Compare PlumX metrics across multiple papers."""
    results = []
    for doi in dois:
        metrics = get_plumx_metrics(doi)
        results.append({
            "doi": doi,
            "citations": metrics.get("citation", {}).get("total", 0),
            "captures": metrics.get("capture", {}).get("total", 0),
            "social": metrics.get("socialMedia", {}).get("total", 0),
            "usage": metrics.get("usage", {}).get("total", 0),
            "mentions": metrics.get("mention", {}).get("total", 0),
        })
    return results


# Example: analyze a paper's multi-dimensional impact
metrics = get_plumx_metrics("10.1038/nature14539")
for category, data in metrics.items():
    print(f"\n{category.upper()} (total: {data['total']})")
    for metric_type, count in data["breakdown"].items():
        print(f"  {metric_type}: {count}")

# Example: compare two papers
# comparison = compare_impact([
#     "10.1038/nature14539",
#     "10.1126/science.aax2342",
# ])

PlumX vs Other Altmetric Services

Feature	PlumX	Altmetric.com	Crossref Event Data
Metric categories	5 comprehensive	Attention Score	Events only
Coverage	130M+ artifacts	30M+ outputs	DOI-based
Social media	Twitter, Facebook, Reddit	Twitter, Reddit, News	Twitter, Reddit, Wikipedia
Usage data	Yes (views, downloads)	No	No
Capture data	Yes (Mendeley readers)	Mendeley readers	No
Free access	Limited	Limited widget	Full API free

References

• PlumX Metrics
• Elsevier Developer Portal
• PlumX API Documentation