# US Hospitals API
> Search and filter more than 5,400 Medicare-certified hospitals across the United States and territories: filter by state, city, free-text name, hospital type (acute care, critical access, psychiatric, childrens, veterans and more), ownership category, whether the hospital offers emergency services, and the CMS overall star rating. Look up any hospital by its CMS facility id, and read metadata listing every state with its hospital count plus the available types and ownership categories for building filter UIs. Each record returns the facility id, name, full address, county, phone number, type, ownership, emergency-services flag and overall rating. Built on the official CMS Hospital General Information dataset. Every endpoint accepts input via the query string or the request body and returns lean JSON. Pure server-side data (no third-party upstream), so responses are instant and always available. Ideal for healthcare directories, patient-facing apps, insurance and care-navigation tools, and research.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/hospitals-api/..."
```

## Pricing
- **Free** (Free) — 22,000 calls/Mo, 3 req/s
- **Basic** ($7/Mo) — 300,000 calls/Mo, 12 req/s
- **Pro** ($20/Mo) — 2,200,000 calls/Mo, 45 req/s
- **Mega** ($54/Mo) — 9,000,000 calls/Mo, 130 req/s

## Endpoints

### Hospitals

#### `GET /v1/hospital` — Single hospital by CMS facility id

**Parameters:**
- `id` (query, required, string) — CMS facility id Example: `050441`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hospitals-api/v1/hospital?id=050441"
```

**Response:**
```json
{
    "data": {
        "id": "050441",
        "zip": "94305",
        "city": "STANFORD",
        "name": "STANFORD HEALTH CARE",
        "type": "Acute Care Hospitals",
        "phone": "(650) 723-4000",
        "state": "CA",
        "county": "SANTA CLARA",
        "address": "300 PASTEUR DRIVE",
        "ownership": "Voluntary non-profit - Private",
        "overall_rating": 5,
        "emergency_services": true
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:26.442Z",
        "request_id": "7e441492-3532-41b1-8195-465afe64337b"
    },
    "status": "ok",
    "message": "Hospital retrieved",
    "success": true
}
```

#### `GET /v1/meta` — States, types & ownership facets

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hospitals-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "rated": 3182,
        "total": 5432,
        "types": [
            "Acute Care - Department of Defense",
            "Acute Care - Veterans Administration",
            "Acute Care Hospitals",
            "Childrens",
            "Critical Access Hospitals",
            "Long-term",
            "Psychiatric",
            "Rural Emergency Hospital"
        ],
        "states": [
            {
                "state": "AK",
                "hospitals": 25
            },
            {
                "state": "AL",
                "hospitals": 100
            },
            {
                "state": "AR",
                "hospitals": 91
            },
            {
                "state": "AS",
                "hospitals": 1
            },
            {
                "state": "AZ",
                "hospitals": 107
            },
            {
                "state": "CA",
                "hospitals": 378
            },
            {
                "state": "CO",
                "hospitals": 97
            },
            {
                "state": "CT",
                "hospitals": 36
            },
            {
                "state": "DC",
                "hospitals": 10
            },
            {
                "state": "DE",
                "hospitals": 13
            },
            {
                "state": "FL",
                "hospitals": 221
            },
            {
                "state": "GA",
                "hospitals": 149

…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search & filter hospitals

**Parameters:**
- `state` (query, optional, string) — 2-letter state code Example: `CA`
- `city` (query, optional, string) — City Example: `san diego`
- `q` (query, optional, string) — Name/free text Example: `mayo`
- `type` (query, optional, string) — acute|critical access|psychiatric|... Example: `acute`
- `ownership` (query, optional, string) — Ownership category Example: `voluntary`
- `min_rating` (query, optional, string) — Min CMS star rating 1..5 Example: `4`
- `emergency` (query, optional, string) — Emergency services true/false Example: `true`
- `limit` (query, optional, string) — 1..100 (default 20) Example: `20`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hospitals-api/v1/search?state=CA&city=san+diego&q=mayo&type=acute&ownership=voluntary&min_rating=4&emergency=true&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 0,
        "limit": 20,
        "total": 0,
        "offset": 0,
        "filters": {
            "q": "mayo",
            "city": "san diego",
            "type": "acute",
            "state": "CA",
            "emergency": true,
            "ownership": "voluntary",
            "min_rating": 4
        },
        "results": []
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:26.566Z",
        "request_id": "21bd03a0-1b1b-47af-95e3-8cc86b8aa6ea"
    },
    "status": "ok",
    "message": "Search completed",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/hospitals-api
OpenAPI spec: https://www.oanor.com/api/hospitals-api/openapi.json