---
title: "Per-state density for one specialty"
method: GET
path: "/api/v1/specialties/{code}/by-state"
tags: ["Specialties"]
---

# Per-state density for one specialty

`GET /api/v1/specialties/{code}/by-state`

## Request

- Base URL: `https://fonteum.com`
- URL: `https://fonteum.com/api/v1/specialties/{code}/by-state`
- Auth: HTTP bearer

Returns 51 rows (50 states + DC) with per-field provenance.

**Optional `subspecialty` filter (§193).** When supplied, the response is recomputed against NPPES providers whose `taxonomy_codes` array includes the requested NUCC code. Counts, `per_100k`, `rank_density`, and `quartile` are recomputed from the filtered slice. The parent study's underserved threshold doesn't transfer, so filtered rows always carry `underserved: false`.

Supported `subspecialty` codes per primary specialty (built from §183 / §188 specialty-study configs — same taxonomies the underlying ingest scoped to):

- **cardiology**: single-taxonomy ingest (`207RC0000X` — Internal Medicine, Cardiovascular Disease (parent)). `?subspecialty=` either matches the parent or returns zero rows.
- **dermatology** (5 taxonomies):
    - `207N00000X` — Dermatology (parent)
    - `207ND0900X` — Dermatopathology
    - `207NI0002X` — Clinical & Laboratory Dermatological Immunology
    - `207NP0225X` — Pediatric Dermatology
    - `207NS0135X` — Procedural Dermatology / MOHS
- **gastroenterology**: single-taxonomy ingest (`207RG0100X` — Internal Medicine, Gastroenterology). `?subspecialty=` either matches the parent or returns zero rows.
- **neurology**: single-taxonomy ingest (`2084N0400X` — Psychiatry & Neurology, Neurology (parent)). `?subspecialty=` either matches the parent or returns zero rows.
- **obgyn** (3 taxonomies):
    - `207V00000X` — Obstetrics & Gynecology (parent)
    - `207VX0000X` — Obstetrics & Gynecology, Obstetrics
    - `207VG0400X` — Obstetrics & Gynecology, Gynecology
- **oncology**: single-taxonomy ingest (`207RX0202X` — Internal Medicine, Medical Oncology). `?subspecialty=` either matches the parent or returns zero rows.
- **ophthalmology**: single-taxonomy ingest (`207W00000X` — Ophthalmology (parent)). `?subspecialty=` either matches the parent or returns zero rows.
- **orthopedic**: single-taxonomy ingest (`207X00000X` — Orthopaedic Surgery (parent)). `?subspecialty=` either matches the parent or returns zero rows.
- **otolaryngology**: single-taxonomy ingest (`207Y00000X` — Otolaryngology (parent)). `?subspecialty=` either matches the parent or returns zero rows.
- **pediatrics** (20 taxonomies):
    - `208000000X` — Pediatrics (parent)
    - `2080A0000X` — Pediatrics, Adolescent Medicine
    - `2080P0006X` — Pediatrics, Developmental — Behavioral Pediatrics
    - `2080P0008X` — Pediatrics, Neurodevelopmental Disabilities
    - `2080N0001X` — Pediatrics, Neonatal-Perinatal Medicine
    - `2080P0202X` — Pediatrics, Pediatric Cardiology
    - `2080P0203X` — Pediatrics, Child Abuse Pediatrics
    - `2080P0204X` — Pediatrics, Pediatric Emergency Medicine
    - `2080P0205X` — Pediatrics, Pediatric Hematology-Oncology
    - `2080P0206X` — Pediatrics, Pediatric Endocrinology
    - `2080P0207X` — Pediatrics, Pediatric Hematology-Oncology (alt)
    - `2080P0208X` — Pediatrics, Pediatric Infectious Diseases
    - `2080P0210X` — Pediatrics, Pediatric Pulmonology
    - `2080P0214X` — Pediatrics, Pediatric Rheumatology
    - `2080P0216X` — Pediatrics, Pediatric Sports Medicine
    - `2080I0007X` — Pediatrics, Pediatric Infectious Diseases (alt)
    - `2080S0010X` — Pediatrics, Sleep Medicine
    - `2080S0012X` — Pediatrics, Sports Medicine
    - `2080T0002X` — Pediatrics, Pediatric Transplant Hepatology
    - `2080H0002X` — Pediatrics, Hospice and Palliative Medicine
- **psychiatry**: single-taxonomy ingest (`2084P0800X` — Psychiatry (individual provider)). `?subspecialty=` either matches the parent or returns zero rows.
- **urology**: single-taxonomy ingest (`208800000X` — Urology (parent)). `?subspecialty=` either matches the parent or returns zero rows.

## Path parameters

- `code` string, required

## Query parameters

- `subspecialty` string
- `max_staleness` string
- `max_staleness_mode` 'flag' | 'reject'

## Response `200`

Per-state rows with provenance. When `subspecialty` is supplied, `meta.subspecialty_filter` is populated with the applied code, display name, and matched record count.

- object
  - `data` SpecialtyStateRow[]
    - `state_code` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `state_name` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `active_providers` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `population_2024` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `per_100k` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `rank_density` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `quartile` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
    - `underserved` ProvenanceField
      - `value` unknown, required
      - `source` string, required
      - `source_url` string, uri
      - `last_checked` string, date-time, required
      - `confidence_score` number
      - `attribution_text` string
      - `limitations` string
  - `meta` ResponseMeta
    - `request_id` string, required
    - `api_version` 'v1', required
    - `data_freshness` union, required: One source block or an array of source blocks. Fields keep content-change, publisher-release, artifact-snapshot, coverage, check, and observation timestamps separate; only a proved canonical content transition can make last_refreshed non-null.
      - DataFreshness
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
      - DataFreshness[]
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
    - `methodology_url` string, uri, required
    - `limitations_url` string, uri, required
    - `documentation_url` string, uri
    - `geo_scope_note` string
    - `pagination` object
      - `total` integer
      - `page` integer
      - `per_page` integer
    - `freshness` FreshnessBlock[]: Typed per-source stored-observation timing: snapshot date, configured target, and a computed age state. This measures the stored observation against Fonteum's configured target, not upstream publisher freshness. A `current` state requires a dated stored snapshot; an unconfirmable date renders `unknown`.
      - `source_id` string, required
      - `snapshot` string, date, nullable, required: Source publication date; null when unavailable (state then `unknown`).
      - `last_checked` string, date-time, required: Serve-time — the only `now` field.
      - `sla_days` integer, nullable
      - `sla_hours` integer, nullable
      - `age_hours` integer, nullable
      - `age_days` integer, nullable
      - `within_sla` boolean, nullable
      - `state` 'current' | 'degraded' | 'stale' | 'unknown', required
    - `freshness_policy` FreshnessPolicy: Present only when the request set `max_staleness`. Reports whether each consulted stored source observation met the caller's age bar; it does not assert that the upstream publisher released newer data.
      - `requested` true, required
      - `max_staleness` string, required
      - `max_staleness_hours` number, required
      - `mode` 'flag' | 'reject', required
      - `stale` boolean, required
      - `stale_sources` object[], required
        - `source_id` string
        - `state` 'current' | 'degraded' | 'stale' | 'unknown'
        - `age_hours` integer, nullable
        - `reason` 'exceeds_max_staleness' | 'freshness_unknown'
    - `attestation` TrustMark, required: Re-checkable attribution attached to v1 response metadata. The chain-head value is a 32-byte content hash, not an Ed25519 signature. Per-snapshot witness signatures use a separately scoped evidence object and never occupy this contract.
      - `attested_by` 'Fonteum', required
      - `standard` 'W3C-VC-2.0', required
      - `content_credential` 'C2PA-aligned Content Credentials for facts', required
      - `source` string, nullable, required
      - `as_of` string, nullable, required
      - `attestation_id` integer, nullable, required: Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index.
      - `chain_head_hash` string, nullable, required: Current chain-head content hash. This field is deliberately not named or represented as a signature.
      - `recheck_url` string, uri, required
      - `key_url` string, uri, required: Signing-key directory used by separately exposed chain and witness evidence.
      - `docs_url` string, uri, required

## Other responses

- `400`: Bad request — most commonly `invalid_subspecialty` when the supplied code is not registered for the primary specialty, or `invalid_max_staleness` when the freshness bar is malformed.
- `401`: Missing or invalid API key.
- `404`: Resource not found.
- `409`: A consulted stored source observation is behind the caller's `max_staleness` bar and `max_staleness_mode=reject` was set. The body still carries `data` + `meta.freshness_policy` (which observations failed and why); the read is not presented as meeting the configured age bar.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/fonteum/apis/fonteum-api.md) · [All operations](https://skmtc.dev/fonteum/apis/fonteum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fonteum/apis/fonteum-api/revisions/334e6e179d0d?raw)