Specialties

Per-state density for one specialty

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.

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

Path parameters

codestring required

Example:dermatology

Query parameters

subspecialtystring

Example:207NS0135X

NUCC taxonomy code to filter on. Must be registered for the primary specialty (see endpoint description). Example: 207NS0135X (Procedural Dermatology / MOHS) for primary dermatology.

max_stalenessstring

Example:48h

Caller stored-snapshot age bar (moat-defense #125). A positive duration — 48h, 7d, 90m, or a bare number of hours. The maximum age any consulted stored source snapshot may have for this request; it is not an upstream-release freshness guarantee. Response carries meta.freshness_policy; absence of the parameter leaves default behaviour unchanged.

max_staleness_mode'flag' | 'reject'

What to do when a source is behind the max_staleness bar: flag (default) returns 200 with a stale flag; reject returns 409. on_stale=reject|409 is accepted as an alias.

Response

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

Example response

{
  "data": [
    {
      "state_code": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "state_name": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "active_providers": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "population_2024": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "per_100k": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "rank_density": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "quartile": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      },
      "underserved": {
        "source": "CMS NPPES NPI Registry",
        "source_url": "https://npiregistry.cms.hhs.gov/api/"
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "freshness": [
      {
        "source_id": "oig-leie"
      }
    ],
    "freshness_policy": {
      "max_staleness": "48h",
      "max_staleness_hours": 48
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.