# CribScore
> The fast API for US childcare safety data. We convert slow state licensing websites into one clean, structured API.

## API Base URL
https://api.cribscore.co/v1

## What This API Does
Returns licensed childcare facilities with CribScore safety ratings from state licensing and inspection data. **Coverage:** 50 US states + DC (51 jurisdictions) in `GET /v1/states` with `slug` for `/states/{slug}`; live Tier-1 ingestion for CA, TX, WA, FL — other jurisdictions stubbed until sources are connected.

## Endpoints
- GET /v1/facilities?zip_code={zip}&radius={miles} - Search facilities near a location
- GET /v1/facilities/compare?ids=id1,id2,... - Compare 2–5 facilities (scores, trends, 12mo violation counts from inspection dates, latest score_breakdown)
- GET /v1/facilities/{id} - Get detailed facility info
- GET /v1/facilities/{id}/inspections - Inspection history
- GET /v1/facilities/{id}/violations - Violation records
- GET /v1/facilities/{id}/score-history - Safety score over time
- GET /v1/states - List all 51 jurisdictions (state_code, state_name, slug, facility_count, …)
- GET /v1/stats - Aggregate statistics
- POST /v1/webhooks - Subscribe to facility alerts
- GET /api/health - Health check (public)

## Authentication
All /v1 endpoints require: Authorization: Bearer {api_key}

Development key (after running migrations 001–005): use plaintext `dev-test-key-cribscore` (hashed in `api_keys`).

## MCP Tools
- cribscore_search: Search facilities by zip code, child age, radius
- cribscore_facility: Get full detail for a facility by ID (includes **safety_score_breakdown** — scoring version **v1.1** with `top_penalty_drivers`, `violation_counts_by_severity`, `inspection_recency_label`, `corrected_count`, etc.)
- cribscore_safety_check: Get safety score, trend, and violations for a facility

## Scoring
- **CribScore breakdown version:** `v1.1` — self-documenting JSON for agents (`top_penalty_drivers`, `violation_counts_by_severity`, `inspection_recency_label`, `raw_score_before_factors`, …).

## CLI
pip install -e .
cribscore search --zip 78701 --radius 5 --json
cribscore serve --port 8000

## OpenAPI Spec
https://api.cribscore.co/openapi.json

## Agent / handoff documentation
See docs/AGENTS.md in this repository for architecture, test commands, env vars, and extension pitfalls.

## Rate Limits
Explorer (free): 100 calls/month (configurable per api_keys row)