Developer API

A stable, versioned, read-only JSON API over the New River Analytics accountability and ratio-study data — the productized version of the data for researchers, the press, and proptech. Free to use with attribution.

Free & open
No key required today. Read-only public data.
Version v1
Every response carries api_version: "v1". Breaking changes ship under a new version.
Rate limit
120 requests / minute per IP. Over-limit returns HTTP 429 with Retry-After.
CORS
Browser-friendly: Access-Control-Allow-Origin: *.
Conventions

All endpoints live under a single versioned router:

GET api/v1.php?resource=<resource>&…

Every response uses the same envelope:

{
  "api_version": "v1",
  "resource":    "<resource>",
  "generated_at": null,
  "data":         …,
  "meta":         { … }   // when useful: count, license, targets, notes
}

An unknown or missing resource returns HTTP 400 with the list of valid resources. Bad params return 400; a missing record returns 404.

Resources

counties

Every WV county’s accountability scorecard row — median ratio, COD, PRD/PRB, reappraisal staleness, standards met, confidence, and current assessor.

Example
api/v1.php?resource=counties
Sample response
{
  "api_version": "v1",
  "resource": "counties",
  "generated_at": null,
  "data": [
    {
      "county": "20 - Kanawha",
      "county_code": 20,
      "current_assessor": "...",
      "n": 4213,
      "median_ratio": 0.61,
      "cod": 18.4, "cod_status": "warn",
      "prd": 1.02, "prd_status": "pass",
      "prb": -0.031, "prb_status": "pass",
      "pct_stale": 22.7, "cadence_status": "warn",
      "standards_met": 2, "standards_total": 3,
      "confidence": "high", "insufficient": false
    }
  ],
  "meta": { "count": 55, "license": "CC BY 4.0 — attribute New River Analytics." }
}
county

The full accountability record for one county: metrics, per-metric IAAO verdicts, reappraisal cadence, graded assessor eras, and authoritative term spans.

Parameters
code required County FIPS code, e.g. 20 (Kanawha), 45 (Summers).
Example
api/v1.php?resource=county&code=20
Sample response
{
  "api_version": "v1",
  "resource": "county",
  "generated_at": null,
  "data": {
    "county": "20 - Kanawha",
    "county_code": 20,
    "current_assessor": "...",
    "metrics": { "n": 4213, "median_ratio": 0.61, "cod": 18.4, "prd": 1.02, "prb": -0.031 },
    "flags": { "cod": {"status":"warn", ...}, "prd": {...}, "prb": {...}, "level": {...} },
    "standards": { "met": 2, "total": 3 },
    "cadence": { "pct_stale": 22.7, "flag": {...} },
    "eras": [ ... ], "terms": [ ... ]
  },
  "meta": { "targets": { "cod": "≤ 15 (IAAO...)", ... } }
}
assessors

Graded per-assessor eras: who held office, the years covered, sample size, and the IAAO metrics. Low-sample eras are suppressed (not published).

Example
api/v1.php?resource=assessors
Sample response
{
  "api_version": "v1",
  "resource": "assessors",
  "generated_at": null,
  "data": [
    {
      "assessor": "...", "county": "45 - Summers", "county_code": 45,
      "years": "2015–2024", "n": 612,
      "median_ratio": 0.58, "cod": 14.2, "prd": 1.01, "prb": -0.012
    }
  ],
  "meta": { "count": 80, "license": "CC BY 4.0 — attribute New River Analytics." }
}
equalization

Materialized per-county, per-class IAAO ratio study over the standard sales window: sales count, median assessment ratio, COD, PRD, PRB.

Example
api/v1.php?resource=equalization
Sample response
{
  "api_version": "v1",
  "resource": "equalization",
  "generated_at": null,
  "data": [
    {
      "county": "20 - Kanawha", "class": "R", "years": 5,
      "n_sales": 4213, "median_ratio": 0.61,
      "cod": 18.4, "prd": 1.02, "prb": -0.031,
      "median_appraised": 92000, "median_adj_sale": 150000, "target_year": 2025
    }
  ],
  "meta": { "count": 110, "license": "CC BY 4.0 — attribute New River Analytics." }
}
levy_rates

District levy (millage) rates by county and tax year for tax classes I, II, and III/IV — the rate applied to assessed value to compute a tax bill.

Example
api/v1.php?resource=levy_rates
Sample response
{
  "api_version": "v1",
  "resource": "levy_rates",
  "generated_at": null,
  "data": [
    {
      "county": "45 - Summers", "district_key": "...", "tax_year": 2025,
      "class_i": 0.2295, "class_ii": 0.4590, "class_iii_iv": 0.9180, "is_base": 1
    }
  ],
  "meta": { "count": 2200, "license": "CC BY 4.0 — attribute New River Analytics." }
}
parcel

A compact factual subset for one parcel: basics + appraised value, plus AVM value and assessment ratio when available. Owner name and mailing address are intentionally omitted — this is not a bulk-PII surface.

Parameters
pid required Alphanumeric parcel id (pid). See a Property Report URL.
Example
api/v1.php?resource=parcel&pid=
Sample response
{
  "api_version": "v1",
  "resource": "parcel",
  "generated_at": null,
  "data": {
    "pid": "...", "parcel_id_formatted": "...",
    "county": "45 - Summers", "district": "...",
    "physical_address": "...",
    "property_class_code": "R", "property_class_name": "Residential",
    "land_use": "...", "sqft": 1840, "deeded_acres": 0.5, "calculated_acres": 0.48,
    "num_buildings": 1, "flood_risk": null, "lat": 37.6, "lng": -80.9,
    "appraised_value": 92000,
    "avm_value": 148500, "assessment_ratio": 0.62
  },
  "meta": { "note": "Owner name and mailing address are intentionally omitted." }
}
API keys & higher limits

The API accepts an optional key parameter (api/v1.php?resource=…&key=…). Today it is a no-op — everything is open at the standard limit.

soon API keys for higher rate limits arrive with accounts. Existing calls keep working unchanged; a valid key will simply raise your limit.

License & related

 CC BY 4.0 Free to reuse, republish, and remix — please attribute New River Analytics and link back where practical. The API exposes aggregate accountability data and single-parcel facts only; it contains no personal information and no billed tax dollars.

Prefer files? Grab the bulk CSV datasets. To understand how the metrics are computed (COD, PRD, PRB, ratio studies, grading thresholds, confidence tiers), see the methodology.