# PubMed Trends API

> Pay-per-query publication trend analytics from PubMed and OpenAlex for AI agents. All data endpoints require x402 payment in USDC on Base. 36M+ articles indexed. Yearly data cached 24h, daily-resolution data cached 6h.

Base URL: http://pubmed.sekgen.xyz

## Quick Reference

| endpoint | price | description |
|----------|-------|-------------|
| GET /api/v1/explore | $0.10 | Cross-domain discovery or MeSH anomaly detection |
| GET /api/v1/emerging | $0.05 | Topics with accelerating multi-year growth |
| GET /api/v1/hottest-weekly | $0.05 | Topics spiking this week vs recent average |
| GET /api/v1/trending-subtopics | $0.05 | Rising sub-topics within a research field |
| GET /api/v1/trends | $0.01 | Year-by-year publication counts and analytics |
| GET /api/v1/compare | $0.02 | Compare trends across 2-5 terms |
| GET /api/v1/pulse | $0.02 | 7d/30d/90d publication volume with YoY change |
| GET /api/v1/snapshot | $0.01 | Single-year publication count |
| GET /api/v1/keypapers | $0.03 | Scored key papers for a query |
| GET /api/v1/digest | $0.08 | Key papers + MeSH landscape + frequent authors |
| GET /api/v1/author | $0.02 | Researcher profile from OpenAlex |

## Choosing the Right Endpoint

- **"What's interesting? (no prior knowledge)"** → /explore — cross-domain discovery
- **"What's growing fast from a small base?"** → /emerging — CAGR over 3 years, catches new/niche fields
- **"What's spiking right now?"** → /hottest-weekly — current vs last year pace, works for any field size
- **"What sub-topics within this field are rising?"** → /trending-subtopics — intra-field growth from OpenAlex
- **"How has this topic evolved over time?"** → /trends — year-by-year counts and analytics
- **"How do these topics compare?"** → /compare — side-by-side trends with crossover detection
- **"Is there a surge happening now?"** → /pulse — 7d/30d/90d volumes vs year ago
- **"Quick count for one year?"** → /snapshot — low-cost single data point
- **"What are the key papers?"** → /keypapers — scored papers by multi-signal analysis
- **"Give me the full picture"** → /digest — papers + MeSH + authors in one call
- **"Who is this researcher?"** → /author — h-index, works, topics, institution

/emerging works best for niche/new topics. It returns empty for mature fields — use /hottest-weekly instead.
When source=openalex, both /emerging and /hottest-weekly accept free-text topic searches (default: PubMed curated categories).

## Endpoints

### Discovery

#### GET /api/v1/explore — $0.10

Cross-domain discovery or MeSH anomaly detection. Two modes based on `topics` param.

| param | required | default | description |
|-------|----------|---------|-------------|
| topics | no | | Comma-separated domains, max 4. Present: OpenAlex scan. Absent: MeSH anomaly detection |
| limit | no | 5 | Max results (1-20) |
| min_z_score | no | 2.0 | Z-score threshold (anomaly mode only) |
| days | no | 7 | Recent window, 1-30 (anomaly mode only) |

Example: `GET http://pubmed.sekgen.xyz/api/v1/explore?topics=neurodegeneration,epigenetics&limit=5`

Response (topics mode):
```json
{
  "results": [
    { "term": "Amyotrophic Lateral Sclerosis Therapy", "category": "neurodegeneration",
      "spike_ratio": 2.48, "cagr_3y": 0.15, "explore_score": 2.852,
      "latest_year_count": 1200, "trend_direction": "growing" }
  ],
  "topics_scanned": ["neurodegeneration", "epigenetics"],
  "as_of": "2026-02-22"
}
```

Example: `GET http://pubmed.sekgen.xyz/api/v1/explore?limit=3`

Response (anomaly mode):
```json
{
  "results": [
    { "term": "Cardiac Digital Twin", "z_score": 4.2, "recent_weekly": 31,
      "baseline_weekly": 8.4, "spike_ratio": 3.69 }
  ],
  "method": "mesh_anomaly",
  "baseline_days": 90,
  "as_of": "2026-02-21"
}
```

#### GET /api/v1/emerging — $0.05

Topics with accelerating publication rates based on multi-year compound growth. Use `category` for PubMed mode (default) or `topic` + `source=openalex` for free-text search.

| param | required | default | description |
|-------|----------|---------|-------------|
| category | no | | oncology, neuroscience, immunology, gene therapy, cardiology. Required for PubMed mode |
| topic | no | | Free-text search. Required for OpenAlex mode |
| source | no | pubmed | `pubmed` or `openalex` |
| window_years | no | 3 | Years to evaluate |
| min_growth_rate | no | 1.0 / 0.3 | Min CAGR (PubMed / OpenAlex default) |
| limit | no | 10 | Max results |

Example (PubMed): `GET http://pubmed.sekgen.xyz/api/v1/emerging?category=oncology&min_growth_rate=0.5`
Example (OpenAlex): `GET http://pubmed.sekgen.xyz/api/v1/emerging?topic=CRISPR&source=openalex`

#### GET /api/v1/hottest-weekly — $0.05

Topics ranked by spike ratio (last 7d vs 30d weekly average). Use `category` for PubMed mode (default) or `topic` + `source=openalex` for free-text search.

| param | required | default | description |
|-------|----------|---------|-------------|
| category | no | | oncology, neuroscience, immunology, gene therapy, cardiology. Required for PubMed mode |
| topic | no | | Free-text search. Required for OpenAlex mode |
| source | no | pubmed | `pubmed` or `openalex` |

Example (PubMed): `GET http://pubmed.sekgen.xyz/api/v1/hottest-weekly?category=oncology`
Example (OpenAlex): `GET http://pubmed.sekgen.xyz/api/v1/hottest-weekly?topic=microbiome&source=openalex`

Response:
```json
{
  "category": "oncology",
  "hottest": [
    { "term": "KRAS inhibitor", "last_7d": 31, "weekly_avg_30d": 20.98, "spike_ratio": 1.478 }
  ],
  "as_of": "2026-02-13"
}
```

#### GET /api/v1/trending-subtopics — $0.05

Rising sub-topics within a research field, powered by OpenAlex topic breakdowns.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | Free-text search defining the field |
| limit | no | 10 | Max results (1-25) |
| window | no | 3 | Years of history (2-5) |

Example: `GET http://pubmed.sekgen.xyz/api/v1/trending-subtopics?query=ulcerative+colitis&limit=10`

Response:
```json
{
  "query": "ulcerative colitis",
  "window_years": 3,
  "results": [
    { "topic_id": "T13569", "topic_name": "Microscopic Colitis",
      "counts": { "2022": 276, "2023": 301, "2024": 335 },
      "cagr": 0.102, "trend_direction": "growing",
      "latest_year_count": 335, "growth_score": 0.257 }
  ],
  "total_topics_found": 162,
  "as_of": "2026-02-22"
}
```

### Analysis

#### GET /api/v1/trends — $0.01

Year-by-year publication counts and growth analytics for a search query.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | PubMed search query |
| start_year | no | -10y | First year |
| end_year | no | now | Last year |

Example: `GET http://pubmed.sekgen.xyz/api/v1/trends?query=CRISPR&start_year=2018&end_year=2025`

Response:
```json
{
  "query": "CRISPR",
  "start_year": 2018,
  "end_year": 2025,
  "total_results": 48523,
  "data": [
    { "year": 2024, "count": 8764, "total_pubmed": 1737687, "proportion": 0.00504, "yoy_growth": 0.074 }
  ],
  "analytics": {
    "peak_year": 2024, "peak_count": 8764, "cagr": 0.052,
    "trend_direction": "growing", "acceleration": 0
  }
}
```

#### GET /api/v1/compare — $0.02

Compare publication trends across 2-5 terms with growth ranking and crossover detection.

| param | required | default | description |
|-------|----------|---------|-------------|
| terms | yes | | Comma-separated, 2-5 terms |
| start_year | no | -10y | First year |
| end_year | no | now | Last year |

Example: `GET http://pubmed.sekgen.xyz/api/v1/compare?terms=CAR-T,bispecific+antibodies&start_year=2018`

#### GET /api/v1/pulse — $0.02

Recent publication volume (7d/30d/90d) with year-over-year change.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | PubMed search query |

Example: `GET http://pubmed.sekgen.xyz/api/v1/pulse?query=CRISPR`

Response:
```json
{
  "query": "CRISPR",
  "current": { "7d": 312, "30d": 957, "90d": 2778 },
  "year_ago": { "7d": 176, "30d": 705, "90d": 2046 },
  "change": { "7d": 0.773, "30d": 0.357, "90d": 0.358 },
  "as_of": "2026-02-13"
}
```

#### GET /api/v1/snapshot — $0.01

Single-year publication count for quick lookups.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | PubMed search query |
| year | no | now | Year to count |

Example: `GET http://pubmed.sekgen.xyz/api/v1/snapshot?query=mRNA+vaccine&year=2025`

Response:
```json
{
  "query": "mRNA vaccine",
  "year": 2025,
  "count": 4521,
  "total_pubmed": 1880997,
  "proportion": 0.002403
}
```

### Papers

#### GET /api/v1/keypapers — $0.03

Scored key papers ranked by journal prestige, publication type, MeSH relevance, and cross-strategy hits. Returns PMIDs for follow-up via PubMed MCP `get_article_metadata`.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | PubMed search query |
| start_year | no | -5y | First year |
| end_year | no | now | Last year |

Example: `GET http://pubmed.sekgen.xyz/api/v1/keypapers?query=base+editing&start_year=2023&end_year=2025`

Response:
```json
{
  "query": "base editing",
  "start_year": 2023,
  "end_year": 2025,
  "papers": [
    { "pmid": "38291045", "title": "Therapeutic base editing in vivo...",
      "journal": "Nature", "pub_year": 2024, "pub_type": "research",
      "score": 8, "score_breakdown": { "top_journal": 3, "review_or_trial": 0,
        "mesh_major_topic": 2, "multi_strategy_hit": 1, "relevance_rank": 2 } }
  ]
}
```

#### GET /api/v1/digest — $0.08

Full research digest: scored papers + MeSH landscape + frequent authors. The bridge between trend analytics and article-level research.

| param | required | default | description |
|-------|----------|---------|-------------|
| query | yes | | PubMed search query |
| start_year | no | -5y | First year |
| end_year | no | now | Last year |

Example: `GET http://pubmed.sekgen.xyz/api/v1/digest?query=base+editing&start_year=2023&end_year=2025`

Response:
```json
{
  "query": "base editing",
  "papers": [
    { "pmid": "38291045", "title": "Therapeutic base editing in vivo...",
      "journal": "Nature", "pub_year": 2024, "score": 8 }
  ],
  "mesh_terms": ["Base Editing", "CRISPR-Cas Systems", "Gene Editing"],
  "authors": [{ "name": "David Liu", "appearances": 4 }]
}
```

### People

#### GET /api/v1/author — $0.02

Researcher profile from OpenAlex. Provide either `name` or `orcid`.

| param | required | default | description |
|-------|----------|---------|-------------|
| name | no | | Author name search |
| orcid | no | | ORCID identifier |

One of `name` or `orcid` is required.

Example: `GET http://pubmed.sekgen.xyz/api/v1/author?name=David+Liu`

Response:
```json
{
  "name": "David R. Liu",
  "orcid": "0000-0002-9943-7557",
  "works_count": 432,
  "cited_by_count": 98234,
  "h_index": 142,
  "i10_index": 298,
  "current_institution": { "name": "Harvard University", "country": "US" },
  "top_topics": [{ "name": "CRISPR Gene Editing", "count": 87 }],
  "counts_by_year": [{ "year": 2025, "works": 18, "cited_by": 12450 }]
}
```

## Payment

All `/api/v1/*` routes return HTTP 402 without a valid x402 payment. Your x402 client reads payment requirements from the 402 response, signs a USDC transfer on Base, and retries with an `X-PAYMENT` header.

With the awal CLI:
```
awal x402 pay "http://pubmed.sekgen.xyz/api/v1/trends?query=CRISPR"
```

Programmatically with [@x402/fetch](https://www.npmjs.com/package/@x402/fetch).

## Example Workflows

### Weekly Research Briefing ($0.29)

1. Call /hottest-weekly for all 5 categories ($0.25) to find spiking topics
2. Call /pulse on the 2 standout topics ($0.04) for year-over-year context
3. Synthesize into a briefing

### Trend-to-Papers Deep Dive ($0.09-$0.11)

1. Call /trends or /pulse to identify a trend ($0.01-$0.02)
2. Call /digest with the same query ($0.08) for scored papers, MeSH landscape, and authors
3. Pass returned PMIDs to PubMed MCP `get_article_metadata` for full abstracts

## Errors

| status | meaning |
|--------|---------|
| 400 | Missing or invalid parameters |
| 402 | Payment required |
| 502 | Upstream API error (NCBI or OpenAlex) |

## Categories

Valid values for `category` in /emerging and /hottest-weekly (PubMed mode):

- **oncology**: CAR-T cell therapy, bispecific antibodies, antibody drug conjugate, immune checkpoint inhibitor, ctDNA liquid biopsy, tumor infiltrating lymphocytes, oncolytic virus therapy, cancer neoantigen vaccine, KRAS inhibitor, CDK4/6 inhibitor, PARP inhibitor, radiopharmaceutical therapy, chimeric antigen receptor NK cell, cancer organoid, spatial transcriptomics cancer, ctDNA minimal residual disease, tumor treating fields, cancer ferroptosis, circular RNA cancer biomarker, artificial intelligence drug resistance cancer, single cell proteomics tumor, cancer extracellular vesicle liquid biopsy, photoimmunotherapy cancer, PROTAC degrader oncology, tumor microbiome
- **neuroscience**: anti-amyloid antibody, tau PET imaging, CGRP antagonist migraine, deep brain stimulation, brain-computer interface, optogenetics therapy, antisense oligonucleotide neurodegeneration, psychedelic assisted psychotherapy, GLP-1 agonist neurodegeneration, alpha-synuclein antibody, gene therapy spinal muscular atrophy, focused ultrasound brain, neuroinflammation biomarker, digital phenotyping mental health, closed-loop neurostimulation, focused ultrasound blood brain barrier, psychedelic neuroplasticity, gut brain axis microbiome, AI drug discovery neurodegeneration, digital biomarker cognition, brain organoid disease model, glymphatic system sleep, CRISPR neurological disorder, senolytic neurodegeneration, neuroimmune interaction microglia
- **immunology**: mRNA vaccine, CAR-T autoimmune, regulatory T cell therapy, IL-17 inhibitor, JAK inhibitor, bispecific antibody autoimmune, tolerogenic dendritic cell, complement inhibitor, microbiome immunotherapy, IgG4 related disease, thymic stromal lymphopoietin, chimeric autoantibody receptor, B cell depletion autoimmune, innate lymphoid cell, trained immunity, mRNA cancer vaccine, CRISPR T cell engineering, IL-33 pathway, trained immunity epigenetic, immune checkpoint autoimmune, single cell immune profiling, nanoparticle vaccine adjuvant, mucosal immunity mRNA, immune aging immunosenescence, spatial transcriptomics immune
- **gene therapy**: CRISPR gene editing, base editing, prime editing, AAV gene therapy, lipid nanoparticle mRNA, epigenome editing, in vivo gene editing, RNA interference therapeutic, gene therapy hemophilia, gene therapy sickle cell, CRISPR diagnostics, gene drive, synthetic biology therapeutic, cell-free DNA therapeutic, tRNA therapeutic, epigenetic editing, in vivo base editing, lipid nanoparticle delivery optimization, RNA editing ADAR, programmable RNA medicine, circular RNA therapeutic, self-amplifying RNA, gene therapy retinal dystrophy, meganuclease gene correction, extracellular vesicle gene delivery
- **cardiology**: PCSK9 inhibitor, SGLT2 inhibitor heart failure, GLP-1 agonist cardiovascular, cardiac gene therapy, RNA therapeutics cardiovascular, artificial heart, transcatheter valve replacement, cardiac regeneration stem cell, lipoprotein(a) inhibitor, myosin inhibitor cardiac, cardiac digital twin, wearable ECG monitoring, AI cardiac imaging, cardiac organoid, inflammasome inhibitor cardiovascular, cardiac patch tissue engineering, AI ECG screening, gut microbiome cardiovascular, clonal hematopoiesis cardiovascular, cardiac fibrosis reversal, siRNA cardiovascular therapeutic, remote cardiac monitoring wearable, perivascular adipose tissue, cardiac reprogramming direct, CRISPR cardiovascular disease