Public data, with the context intact

URLs and source snapshots

Replace the identifier in /data/v1/schools/NCES_ID.json or /data/v1/schools/NCES_ID.md using an entry from the catalog. Area URLs use /data/v1/areas/KIND/SLUG.json, where KIND is cities, counties or districts. These are public static GET resources; no authentication or query parameters are required.

Stable URLs serve the current published snapshot. The schema version describes the contract, not the assessment year. Ranking and context checksums identify the source inputs. Save those checksums with your analysis and cache files between releases. The rankings generation timestamp does not describe later context or page edits.

Assessment summaries cover FY 2023–2025. For bulk analysis, use the CSV datasets and their descriptions. For release news, see updates or the RSS feed.

Interpretation and citation

identifiers

NCES school IDs are strings. Preserve leading zeros; do not convert to numbers.

percentages

Percentages and percentiles use the 0–100 scale, not fractions. Achievement scores are standardized scores, not percentages or ACT composite scores.

missing

null means unavailable. Do not substitute zero or infer suppressed values. A missing bound is not an exact zero.

rank

Rank and percentile refer to eligible schools statewide, not the current city, category or comparison. Only eligible=true and a non-null rank establish a ranked school.

partial score

Ineligible schools can retain a partial computed score. It is not a valid rank or proof of ranking eligibility; consult ineligibility_reason.

periods

Assessment summaries use the stated three-year window. NCES enrollment is a separate snapshot. Context metrics each have their own period. Do not divide tested counts by enrollment to estimate participation.

admissions

school_type and admissions_bucket are classifications. Only context.admissions records describe review status and date. Normal does not guarantee unrestricted enrollment or available places.

sources

context metric and annual-assessment source_id values join to sources[].id. ADE and NCES source attribution for the main ranking and directory is on source_ledger_url. Results do not imply official endorsement.

citation

Cite school.profile_url or area.canonical_url, include the assessment period or metric period, and link methodology_url when describing rank. Retain limitations and eligibility context.

refresh

Version 1 describes the file schema. Stable URLs serve the published build snapshot and may change with a validated release. Compare rankings_sha256 and context_sha256 to identify exact source snapshots; they are not hashes of individual files.

reuse

Project documentation and derived data are provided for inspection. Original sources retain their publishers' terms. No new blanket reuse license is asserted; see the site's terms and source ledger.

Example citation format: “School name, statewide Achievement rank among eligible schools, assessment window FY [start]–[end], AZSchoolRankings.com,” followed by the canonical profile and methodology links. Cite a completion metric's own cohort or fiscal year instead of substituting the ranking year.

Field dictionary

schema_version

Integer contract version; currently 1.

site_url

Canonical site origin.

data_year

Last fiscal year of the assessment window; not a universal source or publication year.

assessment_period

Fiscal-year window for three-year assessment summaries.

nces_enrollment_period

Period of school.enrollment.

snapshot_generated_at

Generation time of the rankings snapshot, not a claim about the last edit of this page or the context data.

rankings_sha256

SHA256 of the exact source rankings.json bytes.

context_sha256

SHA256 of the exact source profile-context.json bytes.

statewide_ranked_school_count

Count of eligible ranked schools in the statewide snapshot.

methodology_url

Human-readable ranking contract.

source_ledger_url

Human-readable source provenance, verification and coverage.

documentation_url

Public endpoint and field documentation.

dictionary_url

Catalog link to the machine-readable field dictionary.

school

Single-school record in school files. Area files use schools[], with the same summary shape.

school.nces_id

String identifier, preserved exactly from the directory.

school.name

Published school name; names need not be unique statewide.

school.profile_url / json_url / markdown_url

Canonical citation page and corresponding single-school representations.

school.district / district_id

Published district name and identifier, each nullable.

school.location

address, city, county and zip are nullable strings; lat/lng are nullable coordinates in decimal degrees. Locations do not establish enrollment boundaries.

school.school_type

district, charter, magnet, online or alternative; some operators span multiple classifications.

school.admissions_bucket

normal, selective_admissions, online or alternative. This is independent of school_type.

school.selective_admissions

Published boolean context flag; not an Achievement input.

school.website_url

Nullable public school website URL from the directory.

school.enrollment

Nullable campus student count in the stated NCES period; may include lower grades.

school.achievement

score, percentile and rank are nullable numbers; eligible is boolean; ineligibility_reason is a nullable string; volatility_flag is a reserved boolean (disabled in v1). No scores are recomputed by this export.

school.assessments

act_ela, act_math and azsci: each object or null. Objects contain nullable students_tested_3yr, pct_passing_3yr, and pct_level_1_3yr through pct_level_4_3yr. Percentage summaries use the methodology's available-year aggregation and missing-count rules.

context.annual_assessments

Rows with fiscal year, subject (act_ela/act_math/azsci), nullable students_tested and pct_passing, and source_id. These are reported annual data, not reconstructed from three-year summaries.

context.metrics

Rows with metric, nullable value, unit (percent/students/grade), period, status, source_id, nullable accountability_model and optional reported_bound. Current metrics include graduation_4yr, graduation_5yr, dropout and enrollment; af_grade and open_enrollment are reserved and remain unpublished until verified.

context.metrics.status

final, provisional, revised, not_rated, suppressed or missing. Preserve it alongside the value.

context.metrics.reported_bound

<2 or >98, or null/absent. A bound accompanies a null exact value; never replace it with a midpoint or endpoint.

context.admissions

status (reviewed/source_on_file/unreviewed), nullable reviewed_on and source_url, and an evidence note. A reviewed date is not a promise that the policy is still unchanged.

sources

Applicable source references: id, title, url, retrieved_on, sha256, verified, sample_school_ids and verification_note.

area

kind (cities/counties/districts), slug, name and canonical_url. The grouping_note explains geographical limits.

schools

Area summary rows or catalog entries. Catalog entries contain nces_id, name, profile_url, json_url and markdown_url only.

areas

Catalog entries with kind, slug, name, canonical_url and json_url.