gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/pubmed-database/references/api_reference.md

# PubMed E-utilities API Reference

## Overview

The NCBI E-utilities provide programmatic access to PubMed and other Entrez databases through a REST API. The base URL for all E-utilities is:

```
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
```

## API Key Requirements

As of December 1, 2018, NCBI enforces API key usage for E-utility calls. API keys increase rate limits from 3 requests/second to 10 requests/second. To obtain an API key, register for an NCBI account and generate a key from your account settings.

Include the API key in requests using the `&api_key` parameter:
```
esearch.fcgi?db=pubmed&term=cancer&api_key=YOUR_API_KEY
```

## Rate Limits

- **Without API key**: 3 requests per second
- **With API key**: 10 requests per second
- Always include a User-Agent header in requests

## Core E-utility Tools

### 1. ESearch - Query Databases

**Endpoint**: `esearch.fcgi`

**Purpose**: Search an Entrez database and retrieve a list of UIDs (e.g., PMIDs for PubMed)

**Required Parameters**:
- `db` - Database to search (e.g., pubmed, gene, protein)
- `term` - Search query

**Optional Parameters**:
- `retmax` - Maximum records to return (default: 20, max: 10000)
- `retstart` - Index of first record to return (default: 0)
- `usehistory=y` - Store results on history server for large result sets
- `retmode` - Return format (xml, json)
- `sort` - Sort order (relevance, pub_date, first_author, last_author, journal)
- `field` - Limit search to specific field
- `datetype` - Type of date to use for filtering (pdat for publication date)
- `mindate` - Minimum date (YYYY/MM/DD format)
- `maxdate` - Maximum date (YYYY/MM/DD format)

**Example Request**:
```
esearch.fcgi?db=pubmed&term=breast+cancer&retmax=100&retmode=json&api_key=YOUR_API_KEY
```

**Response Elements**:
- `Count` - Total number of records matching query
- `RetMax` - Number of records returned in this response
- `RetStart` - Index of first returned record
- `IdList` - List of UIDs (PMIDs)
- `WebEnv` - History server environment string (when usehistory=y)
- `QueryKey` - Query key for history server (when usehistory=y)

### 2. EFetch - Download Records

**Endpoint**: `efetch.fcgi`

**Purpose**: Retrieve full records from a database in various formats

**Required Parameters**:
- `db` - Database name
- `id` - Comma-separated list of UIDs, or use WebEnv/query_key from ESearch

**Optional Parameters**:
- `rettype` - Record type (abstract, medline, xml, uilist)
- `retmode` - Return mode (text, xml)
- `retstart` - Starting record index
- `retmax` - Maximum records per request

**Example Request**:
```
efetch.fcgi?db=pubmed&id=123456,234567&rettype=abstract&retmode=text&api_key=YOUR_API_KEY
```

**Common rettype Values for PubMed**:
- `abstract` - Abstract text
- `medline` - Full MEDLINE format
- `xml` - PubMed XML format
- `uilist` - List of UIDs only

### 3. ESummary - Retrieve Document Summaries

**Endpoint**: `esummary.fcgi`

**Purpose**: Get document summaries (DocSum) for a list of UIDs

**Required Parameters**:
- `db` - Database name
- `id` - Comma-separated UIDs or WebEnv/query_key

**Optional Parameters**:
- `retmode` - Return format (xml, json)
- `version` - DocSum version (1.0 or 2.0, default is 1.0)

**Example Request**:
```
esummary.fcgi?db=pubmed&id=123456,234567&retmode=json&version=2.0&api_key=YOUR_API_KEY
```

**DocSum Fields** (vary by database, common PubMed fields):
- Title
- Authors
- Source (journal)
- PubDate
- Volume, Issue, Pages
- DOI
- PmcRefCount (citations in PMC)

### 4. EPost - Upload UIDs

**Endpoint**: `epost.fcgi`

**Purpose**: Upload a list of UIDs to the history server for use in subsequent requests

**Required Parameters**:
- `db` - Database name
- `id` - Comma-separated list of UIDs

**Example Request**:
```
epost.fcgi?db=pubmed&id=123456,234567,345678&api_key=YOUR_API_KEY
```

**Response**:
Returns WebEnv and QueryKey for use in subsequent requests

### 5. ELink - Find Related Data

**Endpoint**: `elink.fcgi`

**Purpose**: Find related records within the same database or in different databases

**Required Parameters**:
- `dbfrom` - Source database
- `db` - Target database (can be same as dbfrom)
- `id` - UID(s) from source database

**Optional Parameters**:
- `cmd` - Link command (neighbor, neighbor_history, prlinks, llinks, etc.)
- `linkname` - Specific link type to retrieve
- `term` - Filter results with search query
- `holding` - Filter by library holdings

**Example Request**:
```
elink.fcgi?dbfrom=pubmed&db=pubmed&id=123456&cmd=neighbor&api_key=YOUR_API_KEY
```

**Common Link Commands**:
- `neighbor` - Return related records
- `neighbor_history` - Post related records to history server
- `prlinks` - Return provider URLs
- `llinks` - Return LinkOut URLs

### 6. EInfo - Database Information

**Endpoint**: `einfo.fcgi`

**Purpose**: Get information about available Entrez databases or specific database fields

**Parameters**:
- `db` - Database name (optional; omit to list all databases)
- `retmode` - Return format (xml, json)

**Example Request**:
```
einfo.fcgi?db=pubmed&retmode=json&api_key=YOUR_API_KEY
```

**Returns**:
- Database description
- Record count
- Last update date
- Available search fields with descriptions

### 7. EGQuery - Global Query

**Endpoint**: `egquery.fcgi`

**Purpose**: Search term counts across all Entrez databases

**Required Parameters**:
- `term` - Search query

**Example Request**:
```
egquery.fcgi?term=cancer&api_key=YOUR_API_KEY
```

### 8. ESpell - Spelling Suggestions

**Endpoint**: `espell.fcgi`

**Purpose**: Get spelling suggestions for queries

**Required Parameters**:
- `db` - Database name
- `term` - Search term with potential misspelling

**Example Request**:
```
espell.fcgi?db=pubmed&term=cancre&api_key=YOUR_API_KEY
```

### 9. ECitMatch - Citation Matching

**Endpoint**: `ecitmatch.cgi`

**Purpose**: Search PubMed citations using journal, year, volume, page, author information

**Request Format**: POST request with citation strings

**Citation String Format**:
```
journal|year|volume|page|author|key|
```

**Example**:
```
Science|2008|320|5880|1185|key1|
Nature|2010|463|7279|318|key2|
```

**Rate Limit**: 3 requests per second with User-Agent header required

## Best Practices

### Use History Server for Large Result Sets

For queries returning more than 500 records, use the history server:

1. **Initial Search with History**:
```
esearch.fcgi?db=pubmed&term=cancer&usehistory=y&retmode=json&api_key=YOUR_API_KEY
```

2. **Retrieve Records in Batches**:
```
efetch.fcgi?db=pubmed&query_key=1&WebEnv=MCID_12345&retstart=0&retmax=500&rettype=xml&api_key=YOUR_API_KEY
efetch.fcgi?db=pubmed&query_key=1&WebEnv=MCID_12345&retstart=500&retmax=500&rettype=xml&api_key=YOUR_API_KEY
```

### Batch Operations

Use EPost to upload large lists of UIDs before fetching:

```
# Step 1: Post UIDs
epost.fcgi?db=pubmed&id=123,456,789,...&api_key=YOUR_API_KEY

# Step 2: Fetch using WebEnv/query_key
efetch.fcgi?db=pubmed&query_key=1&WebEnv=MCID_12345&rettype=xml&api_key=YOUR_API_KEY
```

### Error Handling

Common HTTP status codes:
- `200` - Success
- `400` - Bad request (check parameters)
- `414` - URI too long (use POST or history server)
- `429` - Rate limit exceeded

### Caching

Implement local caching to:
- Reduce redundant API calls
- Stay within rate limits
- Improve response times
- Respect NCBI resources

## Response Formats

### XML (Default)

Most detailed format with full structured data. Each database has its own DTD (Document Type Definition).

### JSON

Available for most utilities with `retmode=json`. Easier to parse in modern applications.

### Text

Plain text format, useful for abstracts and simple data retrieval.

## Support and Resources

- **API Documentation**: https://www.ncbi.nlm.nih.gov/books/NBK25501/
- **Mailing List**: utilities-announce@ncbi.nlm.nih.gov
- **Support**: vog.hin.mln.ibcn@seitilitue
- **NLM Help Desk**: 1-888-FIND-NLM (1-888-346-3656)