Skip to contents

Fetch Massachusetts school directory data

Source: R/fetch_directory.R
fetch_directory.Rd

Downloads and processes school directory data from the Massachusetts Department of Elementary and Secondary Education (DESE). Base directory data (names, addresses, phone numbers, grades, school types) comes from the MassGIS Schools data layer. Contact information (superintendent, principal, email, website) is scraped from DESE's School and District Profiles website.

Usage

fetch_directory(
  end_year = NULL,
  tidy = TRUE,
  use_cache = TRUE,
  include_contacts = TRUE
)

Arguments

end_year

Currently unused. The directory data represents current schools and is updated regularly. Included for API consistency with other fetch functions.

tidy

If TRUE (default), returns data in a standardized format with consistent column names. If FALSE, returns raw column names from MassGIS.

use_cache

If TRUE (default), uses locally cached data when available. Set to FALSE to force re-download from DESE.

include_contacts

If TRUE (default), scrapes superintendent and principal contact info from DESE profiles. Set to FALSE for faster results with just the base directory data.

Value

A tibble with school directory data. Columns include:

  • state_district_id: 8-digit district identifier (DESE code)

  • state_school_id: 8-digit school identifier (DESE code)

  • district_name: District name

  • school_name: School name

  • entity_type: One of "school", "charter", or "vocational"

  • school_type_code: MassGIS type code (ELE, MID, SEC, CHA, VOC, etc.)

  • address: Street address

  • city: City

  • state: State (always "MA")

  • zip: ZIP code

  • phone: Phone number

  • grades_served: Grade range

  • superintendent_name: District superintendent (if include_contacts=TRUE)

  • superintendent_email: Superintendent email (if include_contacts=TRUE)

  • principal_name: School principal (if include_contacts=TRUE)

  • principal_email: Principal email (if include_contacts=TRUE)

  • website: School/district website (if include_contacts=TRUE)

Details

The base directory data is downloaded from the MassGIS Schools data layer, which is published by the Massachusetts Bureau of Geographic Information and sourced from DESE directory data. Contact information is scraped from individual school and district profile pages on profiles.doe.mass.edu.

The MassGIS data covers public elementary, middle, secondary, charter, vocational/technical, and special education schools. Private schools are excluded unless they are approved special education schools.

Examples

if (FALSE) { # \dontrun{
# Get school directory data with contacts
dir_data <- fetch_directory()

# Get just base directory (faster, no web scraping)
dir_fast <- fetch_directory(include_contacts = FALSE)

# Get raw format (original MassGIS column names)
dir_raw <- fetch_directory(tidy = FALSE, include_contacts = FALSE)

# Force fresh download (ignore cache)
dir_fresh <- fetch_directory(use_cache = FALSE)

# Find all schools in Boston
library(dplyr)
boston <- dir_data |>
  filter(state_district_id == "00350000")

# Find all charter schools
charters <- dir_data |>
  filter(entity_type == "charter")
} # }