Turquoise APIturquoise.health ↗
Search healthcare procedure prices and provider quality ratings by ZIP code. 2 endpoints cover service lookup and cost comparison across US providers.
What is the Turquoise API?
The Turquoise Health API provides two endpoints for searching and comparing medical procedure costs across US healthcare providers. list_services returns a catalog of available procedure codes, while search_care accepts a service code and ZIP code to return paginated provider results with price, price relativity, distance, and care quality ratings — letting developers build cost-comparison tools without maintaining their own healthcare pricing data.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/5475c330-c28c-4681-8bcf-1db4b28e3167/list_services' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace turquoise-health-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Turquoise Health SDK — compare procedure prices across providers."""
from parse_apis.turquoise_health_care_price_search_api import TurquoiseHealth, Sort, ServiceNotFound
client = TurquoiseHealth()
# List available medical procedures to find valid service codes.
for svc in client.services.list(limit=5):
print(svc.code, svc.text)
# Search for affordable colonoscopy providers near NYC, sorted by price.
for provider in client.providers.search(
service="GA002", location="10001", sort_by=Sort.PRICE_ASC, limit=3
):
print(provider.name, provider.price, provider.distance_miles, "mi")
# Drill into the cheapest MRI provider by taking the first result.
cheapest = client.providers.search(
service="RA005", location="90210", distance="25", limit=1
).first()
if cheapest:
print(cheapest.name, cheapest.price_amount, cheapest.price_relativity)
# Handle a bad service code gracefully with typed error.
try:
client.providers.search(service="INVALID", location="10001", limit=1).first()
except ServiceNotFound as exc:
print(f"Service not found: {exc.service}")
print("exercised: services.list / providers.search with Sort enum / ServiceNotFound error")
List all available medical service/procedure packages with their codes. Each service has a short alphanumeric code (e.g. 'GA002') and a human-readable procedure name. These codes are the required input for search_care. The full catalog is returned in a single response with no pagination.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer - number of available services",
"services": "array of objects, each with 'code' (string service code) and 'text' (string procedure name)"
},
"sample": {
"data": {
"total": 33,
"services": [
{
"code": "GA002",
"text": "Colonoscopy"
},
{
"code": "RA005",
"text": "MRI without Contrast"
},
{
"code": "RA000",
"text": "X-Ray"
}
]
},
"status": "success"
}
}About the Turquoise API
What the API Covers
The Turquoise Health API surfaces healthcare price transparency data across two endpoints. list_services returns the full catalog of searchable procedures — each entry includes a code string (used as the service parameter downstream) and a text label like "Colonoscopy" or "MRI without Contrast". This is the lookup table you call once to populate a procedure selector in your application.
Searching for Provider Prices
search_care is the core endpoint. Required inputs are service (a code from list_services, e.g. GA002) and location (a 5-digit US ZIP code). Optional parameters include distance (radius in miles), min_price and max_price (dollar filters), sort_by (price-asc or price-desc), and page for pagination. Results come back 20 per page; total_pages and total_results let you walk through the full result set.
Provider Response Fields
Each item in the providers array includes name, type (facility category), location, distance_miles, price, price_amount, price_qualifier (which clarifies the pricing basis), price_relativity (how the price compares to area averages), and care_quality rating. The combination of price and quality fields is what makes the data useful for side-by-side provider comparison rather than just raw cost lookup.
Coverage and Scope
Coverage is US-only and ZIP-code-scoped. The procedure catalog is fixed to the codes returned by list_services — not every CPT code is available, so calling list_services first to confirm coverage for your target procedures is the right approach before building dependent workflows.
The Turquoise API is a managed, monitored endpoint for turquoise.health — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when turquoise.health changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official turquoise.health API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a procedure cost estimator that lets users enter a ZIP code and procedure type and see ranked provider prices
- Filter providers by
max_priceto surface options within a patient's estimated budget - Compare
price_relativityscores across providers to identify below-average-cost facilities in a region - Incorporate
care_qualityratings alongside price data to weight provider recommendations - Paginate through
search_careresults to aggregate full regional pricing datasets for a given procedure code - Populate a procedure selector UI using
list_servicescodes and human-readabletextlabels - Analyze price variance by running
search_carewithsort_by=price-descvsprice-ascacross multiple ZIP codes
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Turquoise Health offer an official developer API?+
What does `price_qualifier` mean in the `search_care` response?+
price_qualifier clarifies the basis of the reported price — for example, whether it reflects a negotiated rate, a cash price, or a chargemaster rate. It is important to read this field alongside price_amount because the same dollar figure can mean different things depending on the qualifier.Does the API support searching by provider name or filtering by provider type?+
search_care filters by service code, ZIP code, distance, and price range. Provider name and type are available in the response for each result, but they cannot be used as input filters. You can fork this API on Parse and revise it to add a provider-name or facility-type filter endpoint.How does pagination work in `search_care`?+
total_results, total_pages, and results_on_page so you can determine how many pages exist and iterate through them using the page parameter.Does the API cover procedures outside the `list_services` catalog, such as arbitrary CPT codes?+
list_services are searchable via search_care. If a CPT code you need is not in that catalog, results will not be available for it. You can fork this API on Parse and revise it to extend coverage to additional procedure codes or code systems.