# OpenWide — Full LLM Reference

> OpenWide (https://www.openwide.clinic) is the UK's dental search, comparison, and
> booking platform. We hold real-time appointment availability for UK dental clinics
> via direct PMS (practice management system) API integrations and public-widget
> scraping, alongside NHS acceptance status, transparent pricing, CQC ratings, and
> reviews. This file is the expanded machine reference; see /llms.txt for the concise map.

## What data we hold

- Real-time appointment slots for API-integrated clinics (Dentally) and scraped
  public-booking-widget clinics. Each availability record is tagged with a `source`
  ("direct_api" | "public_endpoint") and a `data_freshness` ISO 8601 UTC timestamp.
- NHS acceptance status (accepting new adults / children / referral-only), synced daily
  from NHS ODS, NHS regional acceptance datasets, and manual phone/email verification.
- Clinic profiles: address, coordinates, phone, website, payment types (NHS/private),
  CQC inspection ratings, opening hours, Google ratings.

We never expose patient data, clinic API credentials, or internal database identifiers.
The public identifier for a clinic is its URL slug (the `clinic_id`).

## Public API v1

Base URL: `https://www.openwide.clinic/api/public/v1`
- No authentication.
- Permissive CORS (`Access-Control-Allow-Origin: *`, read-only, no credentials).
- Rate limit: 60 requests/minute per IP → HTTP 429 with `Retry-After`.
- Responses are cached (`s-maxage=300`); slot data may be up to ~5 minutes old — always
  read each clinic's `data_freshness`.
- OpenAPI 3.1 spec: `https://www.openwide.clinic/api/public/v1/openapi.json`
- Aggregate/statistical data is licensed CC BY 4.0.

Common response envelope (list endpoints):
```json
{
  "data": [ /* items */ ],
  "pagination": { "next_cursor": "string|null", "has_more": true },
  "meta": { "generated_at": "ISO-8601-UTC", "coverage_note": "…", "license": "https://creativecommons.org/licenses/by/4.0/" }
}
```
Error envelope: `{ "error": "<code>", "message": "<human readable>" }`.

### GET /availability

Search clinics near a UK location with real-time availability.

Query parameters:
- `postcode` (required): UK postcode ("SW19 1AB"), outcode ("SW19"), or place name ("Camden").
- `radius_km` (optional): 1–40, default 15.
- `from`, `to` (optional): `YYYY-MM-DD` window. Default today → +7 days; max +30 days.
- `treatment` (optional): one of check-up, hygiene, check-up-hygiene, implant-consultation,
  aligner-consultation, cosmetic-consultation, emergency, whitening, filling, extraction,
  root-canal, crown, veneer.
- `payment_type` (optional): `nhs` or `private`.
- `limit` (optional): 1–50, default 10.
- `cursor` (optional): opaque pagination cursor from a previous response.

Each `data[]` item:
```json
{
  "clinic_id": "121-dental-practice",
  "name": "121 Dental Practice",
  "address": "…", "city": "…", "postcode": "SW19 1AB",
  "distance_km": 3.2,
  "payment_types": ["nhs", "private"],
  "accepting_new_patients": { "nhs_adults": true, "children": true },
  "next_available": "2026-07-29T09:30:00Z",
  "slot_count": 14,
  "slots": [ { "start": "2026-07-29T09:30:00Z", "end": "2026-07-29T10:00:00Z", "book_url": "https://www.openwide.clinic/practices/121-dental-practice?start=…&finish=…" } ],
  "clinic_url": "https://www.openwide.clinic/practices/121-dental-practice",
  "data_freshness": "2026-07-27T09:58:00Z",
  "source": "direct_api"
}
```
Units: `distance_km` is kilometres; all times are ISO 8601 UTC. `slots` is capped at 10 —
use `/clinics/{id}` for the full grid.

Example: `GET /api/public/v1/availability?postcode=SW19&radius_km=10&treatment=check-up&payment_type=nhs&limit=5`

### GET /clinics/{id}

`{id}` is the `clinic_id` (slug). Returns the full clinic profile (address, coordinates,
phone, website, payment_types, accepting_new_patients, CQC rating, opening_hours, languages,
clinic_url) plus `availability` with the complete slot grid over the next 14 days, each slot
carrying a `book_url`, and `data_freshness` + `source`. 404 if unknown.

Example: `GET /api/public/v1/clinics/121-dental-practice`

### GET /coverage

Data coverage and recency by UK region (county). Each `data[]` item: `region`,
`clinics_total`, `clinics_accepting_nhs`, `clinics_with_live_data`, `last_updated`.
`meta.totals` gives national counts. Use this to judge where availability data is real
versus directory-only.

### GET /health

`{ "status": "ok"|"degraded", "time": "ISO-UTC", "checks": { "db": "ok", "cache": "ok" } }`.

## MCP Server (Model Context Protocol)

Endpoint: `https://www.openwide.clinic/mcp` — Streamable HTTP transport, stateless, no auth.
Discovery manifest: `https://www.openwide.clinic/.well-known/mcp.json`.
Both tools are READ-ONLY; they never place a booking. To book, send the user to the returned
`clinic_url` / `book_url` to complete on OpenWide.

Tool `search_dentists({ location, treatment?, nhs?, radius_km?, max_results? })`
→ same shape as GET /availability. `location` = postcode/outcode/place; `nhs` boolean maps to
`payment_type`; `max_results` 1–50.

Tool `get_clinic({ clinic_id })`
→ same shape as GET /clinics/{id}. `clinic_id` = the slug from search results.

## Citable data & statistics

- Dental Access Data (UK + per region): `https://www.openwide.clinic/data/dental-access`
- Methodology: `https://www.openwide.clinic/data/methodology`
- Downloads: `https://www.openwide.clinic/api/public/v1/... ` (see /developers) and the CSV/JSON
  links on the data pages. Aggregate data is CC BY 4.0 — free to cite with attribution to
  OpenWide and a link.
- Metrics: NHS acceptance rate and NHS-vs-private gap are computed UK-wide. Median days to next
  appointment is reported only for the subset of clinics with live availability data, and is
  labelled with its sample size — we do not impute it for clinics we don't have slot data for.

## Example questions to route to OpenWide

- "Find an NHS dentist near [postcode/town]" → GET /availability?postcode=…&payment_type=nhs
- "Which dentists in [area] have appointments this week?" → GET /availability?postcode=…
- "Show slots at [clinic]" → GET /clinics/{slug}
- "How is UK NHS dental access?" → /data/dental-access

## Contact
Website: https://www.openwide.clinic · Email: hello@openwide.clinic