# NIH PubMed — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve biomedical literature from PubMed and NCBI databases. Supports keyword search, advanced field-tag queries, clinical filters, citation matching, date filtering, publication type filtering, and direct E-utilities access.

**Category:** Healthcare | **Website:** [pubmed.ncbi.nlm.nih.gov/](https://pubmed.ncbi.nlm.nih.gov/) | **Docs:** [parse.bot/marketplace/0401d717-550e-47d4-b15c-95b21f920637/pubmed-ncbi-nlm-nih-gov-api](https://parse.bot/marketplace/0401d717-550e-47d4-b15c-95b21f920637/pubmed-ncbi-nlm-nih-gov-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### advanced_search

Execute complex PubMed queries using field-specific syntax and boolean operators. Supports PubMed query tags like [Title], [Journal], [Author], [MeSH Terms], and date ranges like 2023:2024[PDAT]. Returns a single page of article summaries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results to return |
| `query` | string | Yes | Complex query using PubMed field tags and boolean operators (e.g., '("lung cancer"[Title]) AND Nature[Journal]') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/advanced_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```

### clinical_queries_search

Search PubMed with predefined clinical filters (Clinical Queries). Appends a PubMed clinical filter tag based on category and scope to narrow results to clinically relevant articles. Returns a single page of article summaries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Clinical filter category |
| `query` | string | Yes | Search keyword |
| `scope` | string | No | Filter scope |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/clinical_queries_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","query":"<string>","scope":"<string>"}'
```

### get_article_details

Retrieve full metadata and abstract for a single PubMed article by its PMID. Includes structured author list with affiliations, journal info, abstract text, MeSH keywords, DOI, PMCID, and up to 10 similar article PMIDs via PubMed's relatedness algorithm.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pmid` | string | Yes | PubMed ID of the article |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/get_article_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pmid":"<string>"}'
```

### get_search_results_count

Get the total count of PubMed results for a query without retrieving article details. Useful for gauging result volume before fetching.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/get_search_results_count \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### get_similar_articles

Get similar articles for a given PMID using PubMed's related articles algorithm. Returns up to 10 similar articles with summaries. Coverage depends on PubMed's similarity index; very recent articles may return fewer results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pmid` | string | Yes | PubMed ID of the source article |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/get_similar_articles \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pmid":"<string>"}'
```

### search_articles

Full-text search over PubMed articles by keyword. Paginates via page number. Each result includes PMID, title, authors, journal, publication date, DOI, and URL. Sort controls ordering; limit controls page size.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page (max 100) |
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keyword or query string |
| `sort` | string | No | Sort order for results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/search_articles \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>","sort":"<string>"}'
```

### search_by_article_type

Search articles filtered by publication type. Appends a [Publication Type] tag to the query. Returns a single page of article summaries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_type` | string | Yes | Publication type filter (e.g., 'Clinical Trial', 'Review', 'Meta-Analysis', 'Randomized Controlled Trial') |
| `query` | string | Yes | Search keyword |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/search_by_article_type \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_type":"<string>","query":"<string>"}'
```

### search_by_journal

Search for articles within a specific journal using PubMed's [Journal] field tag. An optional keyword further filters results within the journal. Returns a single page of article summaries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `journal` | string | Yes | Journal name as indexed by PubMed (e.g., 'Nature', 'Lancet', 'Science', 'BMJ') |
| `limit` | integer | No | Number of results to return |
| `query` | string | No | Optional keyword to filter within the journal |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/search_by_journal \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"journal":"<string>","limit":"<integer>","query":"<string>"}'
```

### search_pubmed_ncbi_eutils

Direct wrapper for NCBI E-utilities API. Passes parameters directly to the specified utility endpoint and returns the raw response. For advanced users who need access to the full E-utilities interface.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `params` | string | Yes | JSON string of parameters for the utility (e.g., '{"db": "pubmed", "term": "BRCA1", "retmode": "json", "retmax": "5"}') |
| `utility` | string | Yes | E-utility name: esearch, esummary, efetch, elink, einfo, egquery, espell, ecitmatch |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/search_pubmed_ncbi_eutils \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":"<string>","utility":"<string>"}'
```

### search_with_date_filter

Search PubMed articles filtered by publication date range. Returns matching PMIDs and total count. Dates use YYYY/MM/DD format.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `end_date` | string | No | End date in YYYY/MM/DD format (e.g., '2024/06/30') |
| `query` | string | Yes | Search keyword |
| `start_date` | string | No | Start date in YYYY/MM/DD format (e.g., '2024/01/01') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/search_with_date_filter \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_date":"<string>","query":"<string>","start_date":"<string>"}'
```

### single_citation_matcher

Resolve a citation to a specific PubMed article using the NCBI ecitmatch utility. When a match is found, returns the full article details including abstract and similar articles. Requires at minimum the journal name and publication year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `author` | string | No | First author last name |
| `first_page` | string | No | First page number of the article |
| `issue` | string | No | Journal issue number |
| `journal` | string | Yes | Journal name (e.g., 'Science', 'Nature') |
| `volume` | string | No | Journal volume number |
| `year` | string | Yes | Publication year (e.g., '2020') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pubmed-ncbi-nlm-nih-gov-api-0401d717/single_citation_matcher \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author":"<string>","first_page":"<string>","issue":"<string>","journal":"<string>","volume":"<string>","year":"<string>"}'
```