Skip to content
CribScore
Skip to content
CribScore Docs

API Reference

Data Dictionary

Definitions for the public CribScore fields that power search, facility detail, state coverage, trust, freshness, and source provenance.

Facility identity fields#

Facility records use stable identifiers plus state-agency names and addresses. `id` is the CribScore canonical facility identifier for detail, compare, evidence, and fit flows. Display names come from source records and may preserve agency casing.

  • `id`: canonical CribScore facility identifier used in `/facility/{id}` and `/v1/facilities/{id}`.
  • `name`: source-derived facility name, normalized only for whitespace and display safety.
  • `state_code`: two-letter jurisdiction code used for coverage and trust joins.
  • `address`, `city`, `zip_code`: location fields from state or baseline source material.

Score and readiness fields#

Scores and readiness fields are derived from source completeness, freshness, facility-level evidence, and state-level materialization checks. A state cannot be treated as launch-ready when scored facility coverage is zero or agency rows are still unmaterialized.

  • `safety_score`: normalized 0-100 facility score when enough source evidence exists.
  • `decision_grade`: decision-readiness tier used by API and trust surfaces.
  • `launch_readiness`: state-level readiness label shown on coverage and trust pages.
  • `scored_facility_count`: count used to prevent empty launch-ready states.

Freshness and provenance fields#

CribScore exposes source provenance and update timing so products and agents can explain when data was last seen and where it came from. Prefer these fields over undocumented scrape timestamps or UI-only labels.

  • `source_url`: human-auditable source link when the source publishes one.
  • `source_updated_at`: timestamp reported or inferred from the source record.
  • `last_seen_at`: last CribScore observation time for the record or jurisdiction.
  • `freshness_days`: age in days used by coverage and trust degradation rules.

Trust fields#

Trust fields summarize whether the jurisdiction is suitable for production decisions. They combine source uptime, freshness, materialization, scored coverage, and critical-field completeness into one explainable contract.

  • `trust_tier`: jurisdiction quality tier used by trust and agent pre-flight checks.
  • `critical_field_completeness`: percent of required fields present across launch-critical records.
  • `source_uptime_7d`: seven-day source availability used to flag stale or broken sources.
  • `unmaterialized_state_agency_pct`: percent of state-agency rows that have not been materialized into public records.

Recommended joins#

Build public and agent workflows from canonical joins instead of stitching pages manually. Facility search gives current IDs, facility detail gives evidence and provenance, states give coverage, and trust jurisdictions give readiness semantics.

  • Search to detail: `/v1/facilities?zip_code=...` -> `/v1/facilities/{id}`.
  • State coverage to trust: `/v1/states` joined by `state_code` with `/v1/trust/jurisdictions`.
  • Browser parity: `/states/{slug}` and `/trust` should agree with the API readiness fields.

Endpoint reference#

GET/v1/facilities

Search facilities and inspect identity, score, source, and pagination fields.

NameTypeRequiredDefaultDescription
zip_codestringoptional—Five-digit ZIP code.
citystringoptional—City search term.
limitintegeroptional201-100.
Requestbash
curl -sS "https://api.cribscore.co/v1/facilities?zip_code=90003&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
Responsejson
{
  "data": [
    {
      "id": "fac_01HZ8X9K2D7N3M5P0AYR4FTC2W",
      "name": "Sunrise Learning Center",
      "state_code": "CA",
      "facility_type": "center",
      "license_status": "active",
      "safety_score": 87,
      "source_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/details/198000123"
    }
  ],
  "meta": { "limit": 5, "offset": 0, "total": 41 }
}
GET/v1/states

Read state coverage, launch readiness, and route-coherent state fields.

NameTypeRequiredDefaultDescription
limitintegeroptional501-100.
Requestbash
curl -sS "https://api.cribscore.co/v1/states?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
Responsejson
{ "data": [{ "state_code": "CA", "slug": "california", "launch_readiness": "degraded" }], "meta": { "limit": 50 } }
GET/v1/trust/jurisdictions

Read jurisdiction trust fields used by public trust and agent pre-flight checks.

NameTypeRequiredDefaultDescription
limitintegeroptional251-500.
Requestbash
curl -sS "https://api.cribscore.co/v1/trust/jurisdictions?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
Responsejson
{ "data": [{ "state_code": "TX", "trust_tier": "launch_ready", "scored_facility_count": 1200 }], "meta": { "limit": 25 } }

Related#