Getting Started

Get up and running with the Healthcare Oracle API in minutes.

1 Get your API key

Sign up for a free account at the pricing page. You'll receive an API key immediately after registration.

2 Make your first request

Use your API key in the X-API-Key header to search for a medical procedure:

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/procedures/search?q=mri"

3 Explore endpoints

The API provides three main endpoints:

• GET
  /lookup — Search negotiated procedure prices by location. Find what providers charge for a specific procedure within a geographic radius.
• GET
  /facilities — Search hospitals and healthcare facilities. Filter by state, type, ownership, or search by location.
• GET
  /procedures/search — Fuzzy search medical procedures by description. Find HCPCS codes without knowing the exact code.

4 Response format

All successful responses follow a consistent JSON envelope with status, data, and meta fields:

{
  "status": "ok",
  "data": { ... },
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

The meta object includes pagination info: total count of matching records, limit per page, and current offset.

5 Error handling

When a request fails, the response uses the same envelope but with status: "error" and an error object containing a machine-readable code and human-readable message:

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

Always check the status field and handle errors gracefully using the error.code for programmatic handling and error.message for user-facing display.

6 Rate limits

The Free tier allows 100 requests per minute. If you exceed this limit, the API returns an HTTP 429 Too Many Requests response.

The response includes a Retry-After header indicating how many seconds to wait before making another request. Higher rate limits are available on paid plans.