references/pubmed.md
PubMed (NCBI E-utilities)
PubMed provides citations, abstracts, and metadata for 37M+ biomedical and life science articles. It does NOT contain full text -- for that, use PMC.
Base URL
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
Authentication
- API key optional but recommended. Without: 3 req/sec. With: 10 req/sec.
- Pass as:
&api_key=YOUR_KEY - Also include
&tool=your_app_name&[email protected]on all requests.
Key Endpoints
1. eSearch -- Search and get PMIDs
GET /esearch.fcgi?db=pubmed&term={query}&retmode=json
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| db | Yes | -- | pubmed |
| term | Yes | -- | Search query. Supports PubMed syntax: field tags [AU], [TI], [TA], [MH] (MeSH), boolean AND/OR/NOT |
| retmax | No | 20 | Max PMIDs returned (max 10,000) |
| retstart | No | 0 | Pagination offset within the first 10,000 matching IDs |
| retmode | No | xml | json or xml |
| rettype | No | uilist | uilist (IDs) or count (count only) |
| sort | No | Set explicitly | relevance, pub_date, Author, JournalName |
| datetype | No | -- | pdat (publication), mdat (modification), edat (entrez) |
| mindate / maxdate | No | -- | Date range YYYY/MM/DD |
| reldate | No | -- | Items from last N days |
| usehistory | No | -- | y to return WebEnv/query_key; does not bypass the PubMed/PMC ESearch 10,000-ID cap |
Large searches: split the query into disjoint date intervals with fewer than 10,000 hits each, or use NCBI EDirect. Reconcile counts and deduplicate PMIDs across partitions; retstart alone cannot traverse a larger PubMed result.
Example:
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=CRISPR+gene+therapy&retmode=json&retmax=5&sort=pub_date
Response:
{
"esearchresult": {
"count": "224107",
"retmax": "5",
"retstart": "0",
"idlist": ["39984857", "39984678", "39984543", "39984210", "39983901"]
}
}
2. eSummary -- Get document summaries
GET /esummary.fcgi?db=pubmed&id={pmids}&retmode=json
| Parameter | Required | Description |
|-----------|----------|-------------|
| db | Yes | pubmed |
| id | Yes* | Comma-separated PMIDs; prefer POST above about 200 IDs. Alternatively supply WebEnv and query_key |
| retmode | No | json or xml |
Example:
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=39984857,39984678&retmode=json
Response fields: uid, pubdate, source (journal), authors, title, volume, issue, pages, fulljournalname, elocationid (DOI), articleids (PMC, DOI, etc.), pubtype, pmcrefcount
3. eFetch -- Retrieve full records (abstracts, MEDLINE)
GET /efetch.fcgi?db=pubmed&id={pmids}&rettype={type}&retmode={mode}
| rettype | retmode | Returns |
|---------|---------|---------|
| (omit) | xml | Full PubMed XML (citation + abstract) |
| medline | text | MEDLINE format |
| abstract | text | Plain text abstract |
| uilist | text | PMID list |
Example -- get abstracts as XML:
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=39984857&retmode=xml
Use POST for more than about 200 explicit IDs. The XML contains <PubmedArticle> with <MedlineCitation> (title, abstract, MeSH terms, authors) and <PubmedData> (article IDs, publication history).
4. eLink -- Find related articles
GET /elink.fcgi?dbfrom=pubmed&db=pubmed&id={pmid}&cmd=neighbor_score&retmode=json
For cmd=neighbor_score, read linksets[].linksetdbs[].links[] objects with id and score (confirmed in a public JSON response on 2026-09-30); relatedness is not a citation edge. neighbor_score is the documented scored-neighbor command.
Search Syntax Tips
- Field tags:
aspirin[TI](title),Smith J[AU](author),Nature[TA](journal),neoplasms[MH](MeSH heading) - Boolean:
CRISPR AND (therapy OR treatment) - Date range:
2020/01/01:2024/12/31[PDAT] - Publication type:
review[PT],clinical trial[PT] - Organism:
humans[MH],mice[MH]
Rate Limits
- 3 requests/second without API key
- 10 requests/second with API key
- Include
toolandemailparameters on every request - Large batch jobs should run outside peak hours (Mon-Fri 5AM-9PM ET)
Error Format
{"error": "API rate limit exceeded", "count": "11"}
HTTP 400 for bad requests, 429 for rate limiting.
Official sources reviewed 2026-09-30
- https://www.ncbi.nlm.nih.gov/books/NBK25499/