5-minute quickstart

Your first API call in under 60 seconds.

Sign up, grab your API key, make a request. Free tier — 10,000 requests/day, no credit card. Same code path works from bash, Python, JavaScript, or any HTTP client.

STEP 1

Grab a free API key

Sign up at /signup. Takes 30 seconds. Free tier gives you 10,000 requests/day, all endpoints unlocked, full historical data, no credit card required.

Get an API key →

STEP 2

Make your first request

Pick your poison. All three examples fetch 5 California hospitals and their star ratings.

curl Python JavaScript

$ curl -H "X-API-Key: sk_live_your_key_here" \
    "https://api.healthcaredata.io/hospitals?state=CA&limit=5"

# Returns JSON with 5 California hospitals + star ratings,
# HCAHPS scores, HVBP payment adjustments, geocoordinates,
# and system affiliation.

import requests

API_KEY = "sk_live_your_key_here"
BASE = "https://api.healthcaredata.io"

resp = requests.get(
    f"{BASE}/hospitals",
    params={"state": "CA", "limit": 5},
    headers={"X-API-Key": API_KEY},
)
resp.raise_for_status()

for h in resp.json()["results"]:
    print(h["name"], "·", h.get("overall_rating"), "stars")

const API_KEY = "sk_live_your_key_here";
const BASE = "https://api.healthcaredata.io";

const resp = await fetch(
  ${BASE}"/hospitals?state=CA&limit=5",
  { headers: { "X-API-Key": API_KEY } }
);
const data = await resp.json();

for (const h of data.results) {
  console.log(h.name, "·", h.overall_rating, "stars");
}

Where does the API key go? Always in the X-API-Key header. Never in the URL, never in a query param — request logs and referrers would leak it.

STEP 3

Popular starting points

Six endpoints that cover 90% of first integrations. See /docs for all 210+.

GET

/hospitals?state=CA

Search hospitals by state, name, city, or CCN. Star ratings + HCAHPS + HVBP included.

GET

/npi/{npi}

Cross-source provider profile: NPPES + Open Payments + Part D + Utilization + OIG in one call.

GET

/exclusions/check/{npi}

Federal exclusion screening. Required-by-law monthly check for any healthcare employer.

GET

/nursing-homes?state=NY&limit=20

Search 17K+ nursing homes with star ratings, staffing, penalties, quality measures.

GET

/benchmarks/hcahps/percentile

National + state + peer-group HCAHPS percentiles — the analytics differentiator.

GET

/market-intelligence/service-area/{ccn}

Hospital market share by ZIP, patient flow patterns, competitive overlap.

STEP 4

Handle rate limits + errors

Every response includes rate-limit headers. When you hit your daily cap, you get a 429 with a reset timestamp. No surprise overage charges — we never bill you for usage you didn't sign up for.

$ curl -i -H "X-API-Key: $KEY" https://api.healthcaredata.io/hospitals

HTTP/2 200
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
Content-Type: application/json
...

Rate limit hit? Response is 429 Too Many Requests with the reset time in the body. Upgrade at /pricing or wait until 00:00 UTC for the counter to reset.

What's next?

Grab a working code sample in your language, dig into the full API reference, or explore the transparency surfaces:

Copy-paste code samples → API Reference Data Catalog Accuracy Benchmark