Price Lookup

GET /lookup

Search negotiated procedure prices within a geographic radius. Results are grouped by facility with payer-specific rates.

Parameters

Parameter Type Required Default Description
hcpcs_code string Yes — HCPCS procedure code (e.g., 99213)
zip string Conditional — 5-digit ZIP code (required if lat/lng not provided)
lat float Conditional — Latitude (required if zip not provided)
lng float Conditional — Longitude (required if zip not provided)
radius_miles float No 30 Search radius in miles (max 100)
payer string No — Filter by payer name (partial match)
sort string No distance Sort: distance, price_asc, price_desc
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/lookup?zip=40202&hcpcs_code=99213&radius_miles=15"

Example Response

{
  "status": "ok",
  "data": {
    "procedure": {
      "hcpcs_code": "99213",
      "short_description": "OFFICE/OUTPATIENT VISIT EST"
    },
    "facilities": [
      {
        "facility_name": "Norton Hospital",
        "ccn": "180001",
        "distance_miles": 2.4,
        "prices": [
          {
            "payer": "Anthem BCBS",
            "price": 142.00,
            "price_type": "negotiated"
          },
          {
            "payer": "Humana Gold",
            "price": 128.50,
            "price_type": "negotiated"
          }
        ]
      }
    ]
  },
  "meta": {
    "total": 12,
    "limit": 20,
    "offset": 0,
    "radius_miles": 15
  }
}

Error Responses

422 Validation Error

Returned when required parameters are missing or have invalid values. The error message details which parameter failed validation.

400 INVALID_ZIP

The provided ZIP code is not a valid 5-digit US ZIP code or could not be geocoded.

{
  "status": "error",
  "error": {
    "code": "INVALID_ZIP",
    "message": "ZIP code 00000 is not a valid US ZIP code"
  }
}
404 PROCEDURE_NOT_FOUND

No procedure exists for the given HCPCS code.

{
  "status": "error",
  "error": {
    "code": "PROCEDURE_NOT_FOUND",
    "message": "No procedure found for code ZZZZZ"
  }
}