Facilities

Endpoints for searching, filtering, and retrieving detailed information about hospitals and healthcare facilities.

Search Facilities

GET /facilities

Search and filter hospitals and healthcare facilities. Supports filtering by state, facility type, ownership, name, and geographic location.

Parameters

Parameter Type Required Default Description
state string No — 2-letter state code
facility_type string No — e.g., short_term, critical_access, psychiatric, rehabilitation, long_term
ownership_type string No — e.g., non_profit, for_profit, government
name string No — Facility name (partial match)
zip string No — ZIP code for spatial search
lat / lng float No — Coordinates for spatial search
radius_miles float No 30 Spatial search radius
county_fips string No — 5-digit FIPS county code
limit int No 20 Results per page (max 100)
offset int No 0 Pagination offset

Example Request

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/facilities?state=KY&facility_type=short_term&limit=5"

Example Response

{
  "status": "ok",
  "data": [
    {
      "ccn": "180001",
      "facility_name": "Norton Hospital",
      "address": "200 E Chestnut St",
      "city": "Louisville",
      "state": "KY",
      "zip": "40202",
      "county_fips": "21111",
      "facility_type": "short_term",
      "ownership_type": "non_profit",
      "has_emergency": true,
      "total_beds": 583
    },
    {
      "ccn": "180130",
      "facility_name": "Baptist Health Louisville",
      "address": "4000 Kresge Way",
      "city": "Louisville",
      "state": "KY",
      "zip": "40207",
      "county_fips": "21111",
      "facility_type": "short_term",
      "ownership_type": "non_profit",
      "has_emergency": true,
      "total_beds": 519
    }
  ],
  "meta": { "total": 87, "limit": 5, "offset": 0 }
}

Get Facility Detail

GET /facilities/{ccn}

Retrieve detailed information for a single facility by its CMS Certification Number (CCN).

Path Parameters

Parameter Type Required Description
ccn string Yes CMS Certification Number (6 characters)

Example Request

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/facilities/180001"

Example Response

{
  "status": "ok",
  "data": {
    "ccn": "180001",
    "facility_name": "Norton Hospital",
    "address": "200 E Chestnut St",
    "city": "Louisville",
    "state": "KY",
    "zip": "40202",
    "county_name": "Jefferson",
    "county_fips": "21111",
    "facility_type": "short_term",
    "ownership_type": "non_profit",
    "has_emergency": true,
    "total_beds": 583,
    "latitude": 38.2527,
    "longitude": -85.7585,
    "phone": "5026298000",
    "cms_rating": 4
  }
}

Facility Prices

GET /facilities/{ccn}/prices

Retrieve a price summary for a specific facility, including negotiated rates across payers and procedures.

Path Parameters

Parameter Type Required Description
ccn string Yes CMS Certification Number (6 characters)

Query Parameters

Parameter Type Required Default Description
hcpcs_code string No — Filter to a specific HCPCS code
payer string No — Filter by payer name (partial match)
limit int No 20 Results per page (max 100)
offset int No 0 Pagination offset

Example Request

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/facilities/180001/prices?hcpcs_code=99213"

Example Response

{
  "status": "ok",
  "data": {
    "facility": {
      "ccn": "180001",
      "facility_name": "Norton Hospital"
    },
    "prices": [
      {
        "hcpcs_code": "99213",
        "short_description": "OFFICE/OUTPATIENT VISIT EST",
        "payer": "Anthem BCBS",
        "price": 142.00,
        "price_type": "negotiated"
      },
      {
        "hcpcs_code": "99213",
        "short_description": "OFFICE/OUTPATIENT VISIT EST",
        "payer": "Humana Gold",
        "price": 128.50,
        "price_type": "negotiated"
      },
      {
        "hcpcs_code": "99213",
        "short_description": "OFFICE/OUTPATIENT VISIT EST",
        "payer": "UnitedHealthcare",
        "price": 155.75,
        "price_type": "negotiated"
      }
    ]
  },
  "meta": { "total": 3, "limit": 20, "offset": 0 }
}

Error Responses

404 FACILITY_NOT_FOUND

No facility exists for the given CCN.

{
  "status": "error",
  "error": {
    "code": "FACILITY_NOT_FOUND",
    "message": "No facility found for CCN 999999"
  }
}
400 INVALID_ZIP

The provided ZIP code is not a valid 5-digit US ZIP code when using spatial search.