NLM Clinical Tables Scraper (ICD-10, NPI, Conditions, Procedures, Drugs)

Fast, autocomplete-grade medical lookups across seven NLM Clinical Table Search Service datasets from a single actor — pick a table, pass search terms, get clean structured rows. No API key. No account. No proxy required.

Tables supported (one mode selector drives them all):

mode	Dataset	Example code
icd10cm	ICD-10-CM diagnoses	E11.9
npi_idv	NPI individual providers	1942278643
npi_org	NPI provider organizations	1982048666
conditions	Medical conditions	Asthma
procedures	Medical procedures	Breast biopsy
rxterms	RxTerms drugs (+ strengths/forms + RxCUIs)	Aspirin (Oral Pill)
hcpcs	HCPCS procedure/supply codes	K0001

Great for medical coding, EHR/EMR autocomplete, provider lookup / NPI enrichment, and pharmacy tools — anywhere you need instant, standards-based clinical term resolution.

---

Why use this instead of hitting the raw API?

The NLM Clinical Table Search Service is fast and free, but its responses are a trap for the unwary: every endpoint returns a positional JSON array, never an object:

[ totalCount, [codes...], hashOrNull, [[displayFieldValues...]], [extraMatrix?] ]
    idx 0       idx 1        idx 2            idx 3                    idx 4

• idx 0 — total matches available on the server
• idx 1 — the list of codes
• idx 2 — null, or (when you request extra fields via ef=) a dict of ef-name -> per-row list-of-lists
• idx 3 — the display-field matrix: one row per code, each column ordered exactly as you asked in df=
• idx 4 — optional code-system matrix

A naive response["name"] fails completely — there are no keys. You have to know precisely which df and ef you requested and re-associate every column by its numeric position. Miss the sf=code,name search-field quirk on icd10cm and a query like diabetes silently returns zero results.

This actor does all of that for you: it pins the correct df/ef/sf per table, un-pivots the positional arrays, and emits flat, named rows where every value is resolved to its real column name — a bare positional index is never emitted as a value.

---

Output

Each item is a generic clinical_record:

{
  "type": "clinical_record",
  "table": "npi_idv",
  "code": "1942278643",
  "primary_name": "SMITH, SMITH",
  "name": null,
  "full_name": "SMITH, SMITH",
  "provider_type": "Physician/Internal Medicine",
  "strengths_and_forms": null,
  "rxcuis": null,
  "address": "9912 LITTLE RD, NEW PORT RICHEY, FL 34654",
  "taxonomy": "Physician/Internal Medicine",
  "fields": {
    "NPI": "1942278643",
    "name.full": "SMITH, SMITH",
    "provider_type": "Physician/Internal Medicine",
    "addr_practice.full": "9912 LITTLE RD, NEW PORT RICHEY, FL 34654"
  },
  "query": "smith",
  "total_available": 10000,
  "url": "https://npiregistry.cms.hhs.gov/provider-view/1942278643",
  "source": "nlm-clinical-tables",
  "scraped_at": "2026-08-11T00:00:00Z"
}

• fields always maps each requested df/ef name → its value for that row.
• Common columns are promoted to top-level when present: name, full_name, provider_type, strengths_and_forms (list), rxcuis (list), address, taxonomy.
• url is a best-effort deep link where one exists (ICD-10 → icd10data, NPI → the CMS NPI Registry), else null.
• All fields are nullable.

For rxterms, strengths_and_forms and rxcuis come back as lists per drug, e.g. ["81 mg Cap", "325 mg Tab", ...] and ["252857", "308416", ...].

---

Input

Field	Type	Default	Description
mode	select	icd10cm	Which table to search (icd10cm, npi_idv, npi_org, conditions, procedures, rxterms, hcpcs).
queries	array	["diabetes","hypertension"]	Autocomplete-style search terms; each runs its own search.
maxItemsPerQuery	integer	50	Max rows per term (maps to the API's count/maxList; auto-paginated past 500).
maxItems	integer	300 (max 5000)	Hard cap on total items across all queries.

Example:

{
  "mode": "rxterms",
  "queries": ["aspirin", "ibuprofen"],
  "maxItemsPerQuery": 25,
  "maxItems": 200
}

---

Pricing

Runs are cheap: the NLM API is free and keyless, and lookups are lightweight autocomplete calls. Budget roughly ~$0.50 per 1,000 records in platform usage — most real jobs cost pennies.

---

How this differs from my other medical/clinical actors

This actor is the NLM Clinical Table Search Service — fast, autocomplete-grade terminology/registry lookups (ICD-10-CM, NPI, conditions, procedures, HCPCS, RxTerms). It is not a trials database and not a full drug-terminology graph:

• clinical-trials-scraper — searches ClinicalTrials.gov study records (interventions, phases, sponsors, eligibility, locations). Use it for research studies, not code lookups.
• rxnorm-scraper — the full RxNorm normalized drug graph (ingredients, brand/generic relationships, NDC/RxCUI crosswalks). Use it for deep drug normalization; use this actor's rxterms mode for quick clinician-facing drug-name + strength/form autocomplete.

Related actors: clinical-trials-scraper, rxnorm-scraper, ncbi-eutils-scraper, hpo-phenotype-scraper.

---

Data source & notes

Data: NLM Clinical Table Search Service (https://clinicaltables.nlm.nih.gov/api), a free public service of the U.S. National Library of Medicine. This actor is an independent tool and is not affiliated with or endorsed by the NLM. Respect the source's terms and use responsibly.