Introduction
The njschooldata package provides a simple interface for
accessing New Jersey Department of Education (NJ DOE) school data in R.
The NJ DOE publishes raw data files covering enrollment, assessments,
graduation rates, and more - but these files use inconsistent formats
across years, making longitudinal analysis challenging.
This package solves that problem by:
- Automatically downloading data from NJ DOE servers
- Parsing various file formats (fixed-width, Excel, CSV)
- Standardizing column names across years
- Providing both wide and tidy data formats
Installation
Install the package from GitHub:
# Using remotes (recommended)
remotes::install_github("almartin82/njschooldata")
# Or using devtools
devtools::install_github("almartin82/njschooldata")Load the package:
library(njschooldata)
library(dplyr) # for data manipulation examplesUnderstanding NJ Education Data
The end_year Convention
All functions use end_year to specify the school year.
This refers to the spring semester year:
| School Year |
end_year Value |
|---|---|
| 2023-24 | 2024 |
| 2022-23 | 2023 |
| 2019-20 | 2020 |
CDS Codes
New Jersey uses a County-District-School (CDS) identifier system:
- county_id: 2-digit county code (e.g., “13” = Essex County)
- district_id: 4-digit district code
- school_id: 3-digit school code (“999” indicates a district-level aggregate)
# A complete CDS code example:
# County 13 (Essex), District 3570 (Newark), School 050 (specific school)Quick Start: Enrollment Data
Fetching Basic Enrollment
# Get 2024 enrollment data (2023-24 school year)
enr_2024 <- fetch_enr(2024)
# View the structure
glimpse(enr_2024)
#> Rows: 54,009
#> Columns: 44
#> $ end_year <dbl> 2024, 2024, 2024, 2024, 2024, 2024, 2024, …
#> $ cds_code <chr> "010010999", "010010999", "010010999", "01…
#> $ county_id <chr> "01", "01", "01", "01", "01", "01", "01", …
#> $ county_name <chr> "Atlantic", "Atlantic", "Atlantic", "Atlan…
#> $ district_id <chr> "0010", "0010", "0010", "0010", "0010", "0…
#> $ district_name <chr> "Absecon Public Schools District", "Abseco…
#> $ school_id <chr> "999", "999", "999", "999", "999", "999", …
#> $ school_name <chr> "District Total", "District Total", "Distr…
#> $ program_code <chr> "PH", "PF", "KH", "KF", "01", "02", "03", …
#> $ program_name <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ male <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ female <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ white <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ black <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ hispanic <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ asian <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ native_american <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ pacific_islander <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ multiracial <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ row_total <dbl> 0, 123, 0, 77, 89, 69, 85, 91, 73, 113, 10…
#> $ free_lunch <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ grade_level <chr> "PK", "PK", "K", "K", "01", "02", "03", "0…
#> $ military <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ free_lunch_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ military_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary_value_source <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ free_lunch_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ military_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ nces_dist <chr> "3400660", "3400660", "3400660", "3400660"…
#> $ nces_sch <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
# Check dimensions
dim(enr_2024) # Rows and columns
#> [1] 54009 44Wide vs. Tidy Format
The tidy parameter transforms data for easier
analysis:
# Wide format (default) - one row per school, many demographic columns
enr_wide <- fetch_enr(2024, tidy = FALSE)
# Tidy format - one row per school-subgroup combination
enr_tidy <- fetch_enr(2024, tidy = TRUE)The tidy format is better for: - Comparing subgroups within schools - Longitudinal analysis across years - Filtering to specific demographics
Assessment Data
NJSLA / PARCC (2015-present)
Use fetch_parcc() for both NJSLA (2019+) and PARCC
(2015-2018) data:
# Get 2024 Grade 4 Math results
math_g4_2024 <- fetch_parcc(
end_year = 2024,
grade_or_subj = 4,
subj = "math"
)
# Get 2024 Grade 8 ELA results
ela_g8_2024 <- fetch_parcc(
end_year = 2024,
grade_or_subj = 8,
subj = "ela"
)
# Get Algebra 1 results (high school)
alg1_2024 <- fetch_parcc(
end_year = 2024,
grade_or_subj = "ALG1",
subj = "math"
)Note: 2020 assessments were cancelled due to COVID-19.
Available Grade Levels
| Subject | PARCC (2015-2018) | NJSLA (2019+) |
|---|---|---|
| ELA | Grades 3-11 | Grades 3-10 |
| Math | Grades 3-8 | Grades 3-8 |
| Math Courses | ALG1, GEO, ALG2 | ALG1, GEO, ALG2 |
Legacy Assessments (2004-2014)
For historical data, use fetch_old_nj_assess():
# Get 2010 Grade 5 NJASK results
njask_2010 <- fetch_old_nj_assess(
end_year = 2010,
grade = 5,
tidy = TRUE
)Graduation Data
Graduation Rates
# Get 4-year graduation rates for 2024
grad_rate_2024 <- fetch_grad_rate(
end_year = 2024,
methodology = "4 year"
)
# Get 5-year graduation rates (available 2012-2019)
grad_rate_5yr <- fetch_grad_rate(
end_year = 2019,
methodology = "5 year"
)Graduation Counts
# Get graduation counts
grad_count_2024 <- fetch_grad_count(end_year = 2024)School and District Directories
Get metadata about schools and districts:
# Current NJ education directory: entities (districts + schools) and
# personnel roles (superintendents, principals, etc.), directory-contract/v1
directory <- fetch_directory()
schools <- directory$entities[directory$entities$entity_type == "school", ]
districts <- directory$entities[directory$entities$entity_type == "district", ]
# Source status (the NJDOE Homeroom endpoints sit behind bot protection that
# blocks some automated clients; when challenged, source_status reports
# "source_unavailable" rather than silently returning empty data as if it
# were a real zero)
directory$meta$source_status
#> [1] "ok"
# Existing callers can use the compatibility data-frame front doors
# get_school_directory() and get_district_directory(). They make separate live
# requests, so this vignette does not call them again after fetch_directory().
# View available columns
names(schools)
#> [1] "state" "entity_type" "entity_subtype"
#> [4] "district_id" "school_id" "district_name"
#> [7] "school_name" "nces_district_id" "nces_school_id"
#> [10] "parent_district_id" "county_name" "grades_served"
#> [13] "address" "city" "zip"
#> [16] "phone" "website" "status"
#> [19] "is_charter"Data Coverage Summary
| Data Type | Function | Years Available |
|---|---|---|
| Enrollment | fetch_enr() |
1999-2026 |
| NJSLA/PARCC | fetch_parcc() |
2015-2019, 2022-2025 |
| NJASK | fetch_old_nj_assess() |
2004-2014 |
| Four-year Graduation Rates | fetch_grad_rate() |
2011-2025 |
| Graduation Counts | fetch_grad_count() |
2012-2025 tidy; raw sources begin in 1998 |
Common Subgroups
When working with tidy data, you’ll encounter these subgroup codes:
Other Demographics
-
male,female -
free_lunch,reduced_lunch,free_reduced_lunch -
lep(English learners) migranttotal_enrollment
Note: Special education data is available via
fetch_sped(), not through enrollment subgroups.
Tips and Best Practices
1. Use Session Caching
The package includes built-in session caching to avoid re-downloading:
# Use session cache (avoids re-downloading within same session)
enr_2024 <- fetch_enr(2024, tidy = TRUE, use_cache = TRUE)
# Or save to disk for reuse across sessions
saveRDS(enr_2024, "data/enr_2024.rds")
enr_2024 <- readRDS("data/enr_2024.rds")
# Check cache status
njsd_cache_info()3. Multi-Year Analysis
Use purrr::map_df() for combining multiple years:
Next Steps
- See
vignette("nj-enrollment-insights")for 15 data stories with visualizations - See
vignette("spr-dictionary")for School Performance Report data - Visit the package website for full documentation
Getting Help
- File issues: https://github.com/almartin82/njschooldata/issues
- Email: almartin@gmail.com
sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
#> [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
#> [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
#> [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] purrr_1.2.2 dplyr_1.2.1 njschooldata_0.11.0
#>
#> loaded via a namespace (and not attached):
#> [1] rappdirs_0.3.4 sass_0.5.0 generics_0.1.4 tidyr_1.3.2
#> [5] stringi_1.8.9 hms_1.1.4 digest_0.6.39 magrittr_2.0.5
#> [9] evaluate_1.0.5 timechange_0.4.0 fastmap_1.2.0 cellranger_1.1.0
#> [13] jsonlite_2.0.0 httr_1.4.9 codetools_0.2-20 textshaping_1.1.0
#> [17] jquerylib_0.1.4 cli_3.6.6 crayon_1.5.3 rlang_1.3.0
#> [21] bit64_4.8.6 withr_3.0.3 cachem_1.1.0 yaml_2.3.12
#> [25] otel_0.3.0 parallel_4.6.2 tools_4.6.2 tzdb_0.5.0
#> [29] curl_8.1.0 vctrs_0.7.3 R6_2.6.1 lifecycle_1.0.5
#> [33] lubridate_1.9.5 snakecase_0.11.1 stringr_1.6.0 bit_4.6.0
#> [37] fs_2.1.0 vroom_1.7.1 ragg_1.5.2 janitor_2.2.1
#> [41] pkgconfig_2.0.3 desc_1.4.3 pkgdown_2.2.1 pillar_1.11.1
#> [45] bslib_0.12.0 glue_1.8.1 systemfonts_1.3.3 xfun_0.62
#> [49] tibble_3.3.1 tidyselect_1.2.1 knitr_1.52 htmltools_0.5.9
#> [53] rmarkdown_2.32 readr_2.2.0 compiler_4.6.2 readxl_1.6.0