Are you interested in obtaining NAEP results in a machine-readable format? Do you create your own data visualizations or use tools for data analytics? 

The instructions below will help you to directly query the NAEP Data Service API to acquire JSON of the same results available in the NAEP Data Explorer.

Data service timeouts may occur when calls require too much time to complete. To avoid this, break up your calls into small manageable parts instead of large individual calls that span across multiple years. Data service results are not intended to be stored in spreadsheets or databases because these results may change over time and consequently may reflect inaccurate data.

If you would like to report an issue or provide a suggestion for improving this API, please contact us.

Table of Contents

The Basics

Location/Path 

https://www.nationsreportcard.gov/DataService/GetAdhocData.aspx

Response Format 

{"status":200,"result":[<1st result>, <2nd result>, …]}

  • If the request returns a successful response, status is 200.
  • A successful response will have a result that is an array.
  • Depending on the request, the result array may have more than 1 element.
Gaps
  • Gaps in the return are the score or percentage differences in NAEP results between different student groups, jurisdictions, or assessment years.
  • Gaps in the return can also mean differences in other previously calculated differences as mentioned above.

Back to Top

Request Types and Their Returns

Overview

  • Main URL – nationsreportcard.gov
  • Query String Parameters
    • Type – what kind of data to return
    • Subject – e.g., mathematics or reading
    • Grade – e.g., grades 4, 8, and 12
    • Subscale – For example, in addition to the composite mathematics scale (MRPCM), NAEP mathematics has five subscales, which are MRPS1: Numbers and Operations, MRPS2: Mathematics Measurement, MRPS3: Mathematics Geometry, MRPS4: Mathematics Data Analysis, Statistics, and Probability, MRPS: Mathematics Algebra and Functions.
    • Variable – student demographic groups (e.g., GENDER) or survey question variable or index.
    • ComparisonValues – allow you to choose specific variable categories (e.g., for GENDER, 1 is male and 2 is female)
    • Jurisdiction – national, state, and district 
    • Stattype – different type of statistical estimates (e.g. mean or percentages)
    • Year
    • StackType
      • Values
        • ColThenRow (default)
        • RowThenCol
      • Determines the order of returns
      • ColThenRow will group the returns based on the first variable (e.g. for SDRACE+GENDER, the return will be group by white+male, white+female, black+male, black+male …
      • RowThenCol will group the returns based on the second variable (e.g. for SDRACE+GENDER, the return will be group by white+male, black+male, hispanic+male, asian+male …
  • There are many data points. Each data point also contains the query information. For example, if you select 2 years, 1 jurisdiction, TOTAL (all students) and a composite scale, you will get 2 data points.  Each data point contains information indicating the year that the data point represents.
  • Please see the section Parameter Values below for more details for all parameters.
  • Significance indicates if the focal value is significantly higher or lower, or not significantly different than the target value.

Examples of Request Types and Their Returns

Basic data requests and returns

  • type – data
  • Important return: value – the statistic you are looking for.
 
  • type – data
  • StackType
    • ColThenRow (default)
    • RowThenCol
  • Must have 2 variables (here is SDRACE and GENDER)
  • Important return : varValue – the category value within each student group  (e.g., for GENDER, male is 1, female is 2)

Significance gap across years

  • type – sigacrossyear
  • Used to return whether there is a significant difference in values between two or more years. The example shown here will return the comparison results between assessment years 2013 and 2015 in the average mathematics scores for public school students in the nation (NP).
  • Must have more than one year, separated by commas
  • Important returns 
    • focalValue – value for focal year
    • targetValue – value for target year
    • gap – difference between focalValue and targetValue

Significance gap across jurisdictions

  • Type – sigacrossjuris
  • Must have more than 1 jurisdiction, separated by commas
  • Important returns 
    • focalValue – value for a focal jurisdiction
    • targetValue – value for a target jurisdiction
    • gap – difference between focalValue and targetValue

Significance gap across variable

  • Type – sigacrossvalue
  • Variable must be a non “TOTAL” value (e.g., GENDER in the example here)
  • Important returns
    • focalValue – value for variable focal category value (e.g. Male)
    • targetValue – value for variable target category value (e.g. Female)
    • gap – difference between focalValue and targetValue

Significance gap across variable (with crosstab)

  • Type – sigacrossvalue
  • A crosstab will allow you to compare the relationship between two variables. You can examine the significance gap between specific demographic groups (e.g., (e.g., White/Male versus White/Female, White/Male versus Black/Male, etc.)
  • If the ComparisonValues parameter is not set, all variable categories from each variable will be compared to each other.
  • If the ComparisonValues parameter is set, you can return just the specific demographic groups you are interested in.
  • You may even choose up to three variables when performing crosstabs.

Gap between year and jurisdiction

 
  • Type – gaponyearacrossjuris
  • Must have 2 years
  • Important returns
    • Innerdiff1 – difference between stattype values between 2 years for focal jurisdiction
    • Innerdiff2 – difference between stattype values between 2 years for target jurisdiction
    • Gap – difference between innerdiff1 and innerdiff2

Significance of gap of two variable category values across years

  • Type – gaponvaracrossyear
  • Must have 2 or more years
  • Must have a non “TOTAL” variable with 2 or more category values (e.g. GENDER, SDRACE)
  • Important returns
    • Innerdiff1 – difference of stattype values between variable values (e.g., between male and female students) for focal year 
    • Innerdiff2 – difference of stattype values between variable values for target year
    • Gap – difference between innerdiff1 and innerdiff2

Significance of gap of two variable category values across jurisdictions

  • Type – gaponvaracrossjuris
  • Must have 2 or more jurisdictions 
  • Must have a non “TOTAL” variable with 2 or more category values
  • Important returns
    • Innerdiff1 – difference of stattype values between variable category values (e.g., between male and female students) for focal jurisdiction
    • Innerdiff2 – difference of stattype values between variable category values for target jurisdiction
    • Gap – difference between innerdiff1 and innerdiff2

Significance of gap of two variable category values and two years across jurisdictions

  • Type – gaponvarandyearacrossjuris
  • Must have 2 or more jurisdictions
  • Must have 2 or more years
  • Must have a non “TOTAL” variable with 2 or more category values
  • Important returns
    • innerdiff1 – difference of stattype values between variable category values (e.g., between male and female students) in focal jurisdiction for focal year.
    • innerdiff2 – difference of stattype values between variable category values (e.g., between male and female students) in focal jurisdiction for target year.
    • innerdiff3 – difference of stattype values between variable category values (e.g., between male and female students) in target jurisdiction for focal year.
    • innerdiff4 – difference of stattype values between variable category values (e.g., between male and female students) in target jurisdiction for target year.
    • yeardiff1 – difference between innerdiff1 and innerdiff2
    • yeardiff2 – difference between innerdiff3 and innerdiff4
    • Gap – difference between yeardif1 and yeardiff2

Back to Top

Parameter Values

Subject and Subscale

  • Civics
    • CIVRP – Civics scale
  • Economics
    • ERPCM – Composite scale
    • ERPS1 – Market scale
    • ERPS2 – National scale
    • ERPS3 – International scale
  • Geography
    • GRPCM – Composite scale
    • GRPS1 – Space and place scale
    • GRPS2 – Environment and society scale
    • GRPS3 – Spatial dynamics scale
  • Mathematics 1990R2
    • MRPCM – Composite scale
    • MRPS1 – Number properties and operations scale
    • MRPS2 – Measurement scale
    • MRPS3 – Geometry scale
    • MRPS4 – Data analysis, statistics, and probability scale
    • MRPS5 – Algebra scale
    • Mathematics 2005R3
    • MWPCM – Composite Scale
    • MWPS1 – Number properties and operations scale
    • MWPS2 – Measurement and geometry scale
    • MWPS3 – Data analysis, statistics, and probability scale
    • MWPS4 – Algebra scale
  • Music
    • MUSRP – Music scale
  • Reading
    • RRPCM – Composite scale
    • RRPS1 – Literary experience
    • RRPS2 – Gain information scale
    • RRPS3 – Perform a task scale
    • RRPS4 – Gain and use information scale
  • Science 1990R2
    • SRPCM – Composite scale
    • SRPS1 – Physical science scale
    • SRPS2 – Earth science scale
    • SRPS3 – Life science scale
    • Science 2005R3
    • SRPUV – Overall science scale
  • TEL
    • TRPUN – Overall scale
    • TRPP1 – Communicating and collaborating practice scale
    • TRPP2 – Developing solutions and Achieving goals practice scale
    • TRPP3 – Understanding Technological Principles practice scale
  • History
    • HRPCM – Composite scale
    • HRPS1 – Democracy Scale
    • HRPS2 – Cultures scale
    • HRPS3 – Technology scale
    • HRPS4 – World role scale
  • Visual Arts
    • VISRP – Visual arts scale
  • Vocabulary
    • VOCRP – Meaning vocabulary scale
  • Writing
    • WRIRP – Writing scale

Jurisdiction

  • NT – National
  • NP – National public
  • NR – National private
  • NL – Large city
  • AL – Alabama
  • AK – Alaska
  • AZ – Arizona
  • AR – Arkansas
  • CA – California
  • CO – Colorado
  • CT – Connecticut
  • DE – Delaware
  • DC – District of Columbia
  • DS – DoDEA
  • FL – Florida
  • GA – Georgia
  • HI – Hawaii
  • ID – Idaho
  • IL – Illinois
  • IN – Indiana
  • IA – Iowa
  • KS – Kansas
  • KY – Kentucky
  • LA – Louisiana
  • ME – Maine
  • MD – Maryland
  • MA – Massachusetts
  • MI – Michigan
  • MN – Minnesota
  • MS – Mississippi
  • MO – Missouri
  • MT – Montana
  • NE – Nebraska
  • NV – Nevada
  • NH – New Hampshire
  • NJ – New Jersey
  • NM – New Mexico
  • NY – New York
  • NC – North Carolina
  • ND – North Dakota
  • OH – Ohio
  • OK – Oklahoma
  • OR – Oregon
  • PA – Pennsylvania
  • RI – Rhode Island
  • SC – South Carolina
  • SD – South Dakota
  • TN – Tennessee
  • TX – Texas
  • UT – Utah
  • VT – Vermont
  • VA – Virginia
  • WA – Washington
  • WV – West Virginia
  • WI – Wisconsin
  • WY – Wyoming
  • DD – DoDEA/DDESS
  • DO – DoDEA/DoDDS
  • XQ – Albuquerque
  • XA – Atlanta
  • XU – Austin
  • XM – Baltimore City
  • XB – Boston
  • XT – Charlotte
  • XC – Chicago
  • XX – Clark County (NV)
  • XV – Cleveland
  • XS – Dallas
  • XY – Denver
  • XR – Detroit
  • XW – District of Columbia (DCPS)
  • XE – Duval County (FL)
  • XZ – Fort Worth (TX)
  • XF – Fresno
  • XG – Guilford County (NC)
  • XO – Hillsborough County (FL)
  • XH – Houston
  • XJ – Jefferson County (KY)
  • XL – Los Angeles
  • XI – Miami-Dade
  • XK – Milwaukee
  • XN – New York City
  • XP – Philadelphia
  • XD – San Diego
  • YA – Shelby County (TN)
  • AS – American Samoa
  • GU – Guam
  • PR – Puerto Rico
  • VI – Virgin Islands

Grade/Cohort

  • Use either grade or cohort, newer calls only take cohort
  • Grade
    • 4
    • 8
    • 12
  • Cohort
    • 1 = Grade 4 or Age 9
    • 2 = Grade 8 or Age 13
    • 3 = Grade 12 or Age 17

Year

  • R2  e.g., 1990R2 (R2 stands for accommodations not permitted sample)
  • R3  e.g., 2016R3 (R3 stands for accommodations permitted sample)
  • If R2 or R3 is not indicated, default is R3
  • Base, Current, and Prior are keywords
    • Base – first assessment year
    • Current – most recent assessment year
    • Prior – second most recent assessment year

StatType

  • MN:MN – Mean
  • RP:RP – row percent
  • ALD:BA – Discrete achievement level – At Basic
  • ALD:PR – Discrete achievement level – At Proficient
  • ALD:AD – Discrete achievement level – At Advanced
  • ALC:BB – Cumulative achievement level  - Below Basic
  • ALC:AB – Cumulative achievement level – At or above Basic
  • ALC:AP – Cumulative achievement level – At or above Proficient
  • ALC:AD – Cumulative achievement level – At Advanced
  • SD:SD – Standard deviations
  • PC:P1 – 10th percentile
  • PC:P2 – 25th percentile
  • PC:P5 – 50th percentile
  • PC:P7 – 75th percentile
  • PC:P9 – 90th percentile  

Categoryindex

  • Not required, If omitted all the values are returned
  • For example, for SDRACE, White = 1, Black = 2, Hispanic = 3
  • For example, for GENDER+SDRACE, 1+3 returns male Hispanic, 2+2 returns female Black, encode as 1%2B3,2%2B2

Variable

  • Student demographic groups or survey question variable or index.
  • Commonly used variables
    • TOTAL – All students
    • SDRACE – Race/ethnicity used to report trends
    • SRACE10 – Race/ethnicity using 2011 guidelines
    • GENDER – Gender
    • SLUNCH3 – National School Lunch Program eligibility
    • PARED – Parental education level
    • SCHTYPE – Public or nonpublic school
    • CHRTRPT – School identified as charter
    • UTOL4 – School location
    • CENSREG – Region of the country
    • IEP – Disability status of student, including those with 504 plan
    • LEP – Status as English language learner
  • NAEP Variable List API
  • In addition to learning about the available variables using the API, details about the variable code used in the query string can be found in the NAEP Data Explorer. In the “Select Variables” section, a pull- down menu containing the variable code appears when you click details, circled below by gold oval.
Image from the Nation's Report Card NAEP Data Explorer (NDE) web page showing student variable selection screen. This interface allows users to switch between major reporting groups and student factors. The selected variable has its attributes shown which include student group, category, and all years data is available. There are two examples highlighted with a gold oval. One highlights the TOTAL of All Students and the other highlights SDRACE for Race/ethnicity used to report trends, school-reported category.

Back to Top

Assessment Year and Subject Combinations


Back to Top


Error Codes

The error code is a numeric value that is the sum of multiple error flags. Each number is the sum of a unique set of error codes. For example, an error code of 33 would signify error flags with numeric values of 1 and 32 and indicate the error flags, "Reporting Standard Not Met" and "Non-qualified independent variable". Priority means if multiple error flags are present, an error flag with priority 1 takes precedence over an error flag with priority 2.
 
Numeric ValueActual Bit NumberDescriptionSymbol Shown StatSymbol Shown SEPriority
11
Reporting Standard Not Met (NDE)‡†No Priority
4
3
High CV‡†
No Priority
8
4
Non-accommodated Sample
Stat is shown
SE is shown
No Priority
165
Exclusion List‡†
1
326Non-qualified independent Variable‡†1
647No Data—
†1
1288
Rounds to Zero#
†2
2569SE Not ApplicableNo Symbol
†
No Priority
51210
Race Note Type 1NOTE - Stat is shownNOTE No Priority 
204812Response Rate Below 85%Statistic is shown with !SE is shown
No Priority
409613
Response Rate Below 50% But > 0%‡†1
1638415SignificanceStatistics shown with star in chartsSE is shownNo Priority
3276816Zero Percent Response Rate—
†1
13107218Jurisdiction NoteNOTE - Stat is shownNOTE - Stat is shownNo Priority
419430423Race Note Type 2NOTE - Stat is shownNo Symbol
No Priority
8388608
24Race Note Type 3NOTE - Stat is shownNo SymbolNo Priority
16777216
25IEP NoteNOTE - Stat is shownNo SymbolNo Priority
3355443226IEP2009 NoteNOTE - Stat is shownNo SymbolNo Priority
6710886427DoDEA Note
NOTE - Stat is shownNo SymbolNo Priority
13421772828Dallas NoteNOTE - Stat is shownNo SymbolNo Priority
26843545629Skipped Variables NoteNOTE - Stat is shownNo SymbolNo Priority

An error flag indicated as producing NOTE text means that in the NAEP Data Explorer tool, a note would appear below the tabular result for the selected variable. EXAMPLE: A report produced in the NAEP Data Explorer using the SDRACE variable would produce an API Result with the numeric error value 512 indicated (error bit 10) triggered for each statistic returned. The error code table says "NOTE – Stat is shown". This means that the statistic is displayed in the results table as requested, but that a note applies to the result relating to the variable SDRACE. When more than one note text applies, the various statements will be stitched together as sentences in a paragraph following the word NOTE. This logic is defined as part of the NAEP statistical reporting standards set forth by NCES. The easiest way to see how notes work together is to perform some queries in the NAEP Data Explorer that trigger note conditions, such as SDRACE for Washington DC (combines the race note number 512 with the jurisdiction note 131072).
 
Numeric ValueActual Bit NumberNote Text
51210Black includes African American, Hispanic includes Latino, and Pacific Islander includes Native Hawaiian. Race categories exclude Hispanic origin. Prior to 2011, students in the "Two or More Races" category were categorized as "unclassified."
13107218DCPS = District of Columbia Public Schools.
419430423Black includes African American, and Hispanic includes Latino. Race categories exclude Hispanic origin.
838860824Black includes African American, Hispanic includes Latino, and Pacific Islander includes Native Hawaiian. Race categories exclude Hispanic origin.
1677721625IEP NOTE: The category "students with disabilities" includes students identified as having either an Individualized Education Program (IEP) or protection under Section 504 of the Rehabilitation Act of 1973.
3355443226IEP2009 NOTE: The category "students with disabilities" includes students identified as having an Individualized Education Program (IEP) but excludes those identified under Section 504 of the Rehabilitation Act of 1973.
6710886427DoDEA NOTE: DoDEA = Department of Defense Education Activity. Some apparent differences between estimates may not be statistically significant.
13421772828Dallas NOTE: The 2017 assessed sample for Dallas in grade 4 reading was not representative of the target population for two major reporting groups: Hispanic and English language learner students. Assessed samples in Dallas for other grades and subjects in 2017 were unaffected.
26843545629Some respondents did not receive this question based on their response to a previous question in the survey, and those respondents are included in the "missing" category.


Back to Top