Search APIs Overview

FHIRfly Search APIs let you find healthcare data when you don't know the exact code. Use full-text search with filters to discover drugs, providers, lab codes, and more.

Search vs. Lookup

Available Search Endpoints

Common Features

All search endpoints share these capabilities:

Text Search with Fuzzy Matching

Search queries automatically handle typos and variations:

// Finds "lisinopril" even with typo
const results = await client.ndc.search({ q: "lisnopril" });

Filters

Narrow results with type-specific filters:

const results = await client.ndc.search({
  q: "metformin",
  dosage_form: "TABLET",
  is_active: true
});

Faceted Results

Search responses include facets showing the distribution of results:

{
  "facets": {
    "dosage_form": {
      "TABLET": 186,
      "CAPSULE": 42,
      "SOLUTION": 15
    },
    "product_type": {
      "HUMAN PRESCRIPTION DRUG": 170,
      "DRUG FOR FURTHER PROCESSING": 16
    }
  },
  "items": [...],
  "total": 186
}

Use facets to build filter UIs or refine searches programmatically.

Pagination

Control result sets with limit and page:

Maximum accessible results: 10,000 (100 pages × 100 items). For larger datasets, use filters to narrow your search.

Response Shapes

Control response detail level with the shape parameter:

Response Format

All search responses follow this structure:

{
  "items": [
    { /* result 1 */ },
    { /* result 2 */ }
  ],
  "total": 186,
  "has_more": true,
  "page": 1,
  "limit": 20,
  "facets": { /* aggregations */ },
  "meta": {
    "legal": {
      "source_name": "FDA NDC Directory",
      "license": "public_domain",
      "citation": "..."
    }
  }
}

Authentication

Search APIs require the same authentication as lookup APIs:

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });
const results = await client.ndc.search({ q: "advil" });

Required Scopes

Each search endpoint requires a dedicated search scope:

Search scopes are separate from read scopes because search operations use more compute resources. New credentials include both read and search scopes by default.