naep_scores
Retrieve NAEP test scores to analyze U.S. student achievement by subject, grade, state, and demographic group.
Instructions
Get NAEP test scores (Nation's Report Card) — the gold standard for measuring U.S. student achievement. Returns average scale scores by subject, grade, state, and demographic group.
Subjects: 'reading', 'math', 'science', 'writing', 'civics', 'history', 'geography', 'economics', 'tel', 'music' Grades: 4, 8, 12 (math: 4,8 only; economics/tel/music: 8 or 12 only) Variables: 'TOTAL' (all students), 'SDRACE' (race), 'GENDER', 'SLUNCH3' (school lunch/poverty), 'PARED' (parent education) Jurisdiction: 'NP' (national public), or state codes ('CA', 'TX', 'NY', 'MS')
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | Subject: 'reading', 'math', 'science', 'writing', 'civics', 'history', 'geography', 'economics', 'tel', 'music'. Aliases: 'mathematics', 'ela', 'us history', 'social studies', 'econ', 'technology' | |
| grade | Yes | Grade: 4, 8, or 12. Math: 4,8 only. Economics/TEL/Music: grade 8 or 12 only. | |
| variable | No | 'TOTAL' (default), 'SDRACE' (race), 'GENDER', 'SLUNCH3' (poverty), 'PARED' (parent ed), 'IEP' (disability), 'LEP' (English learners). Crosstab: 'SDRACE+GENDER' | |
| jurisdiction | No | 'NP' (national public, default), or state/district codes: 'CA', 'TX', 'XN' (NYC), 'XC' (Chicago). Comma-separate for multiple. | |
| year | No | Assessment year: '2022', '2019', '2017'. Default: most recent. Use 'Current' for latest. Append R2 for non-accommodated: '2019R2'. | |
| stat_type | No | Statistic type: 'MN:MN' (Average scale score (mean)), 'RP:RP' (Row percent), 'ALC:BB' (% Below Basic (cumulative)), 'ALC:AB' (% At or Above Basic (cumulative)), 'ALC:AP' (% At or Above Proficient (cumulative)), 'ALC:AD' (% At Advanced (cumulative)), 'ALD:BA' (% At Basic (discrete)), 'ALD:PR' (% At Proficient (discrete)), ... (15 total) | |
| subscale | No | Override the default composite subscale. E.g. math: 'MRPS1' (numbers), 'MRPS3' (geometry). See reference for all codes. | |
| categoryindex | No | Filter specific categories. E.g. for SDRACE: '1' (White), '2' (Black), '3' (Hispanic). For crosstab: '1+1,1+2' (White/Male, White/Female) |