locations

Hierarchical US geographic location manager for the jheem2 project. Provides fast lookups, hierarchical queries, code aliasing, and geospatial plotting across multiple geographic resolutions.

Installation

devtools::install_github("tfojo1/locations")

main is the supported development line. Periodic GitHub pre-releases provide pin-able development snapshots; they are not CRAN or stable open-source releases. Package and bundled-data reuse terms remain unresolved, so these snapshots do not grant general permission to reuse, modify, or redistribute the package.

Location Types

Type Description Prefix Example Code Example Name
COUNTRY United States US United States
STATE US states (continental + territories) MD Maryland
COUNTY Counties (FIPS codes) 24005 Baltimore County
CBSA Core-based statistical areas C. C.12580 Baltimore-Columbia-Towson, MD
NSDUH National Survey on Drug Use regions
PHD Public health districts (AL, LA)
ZIPCODE ZIP codes (registered but not loaded) Z.

Quick Start

library(locations)

# Look up location info
get.location.type(c("MD", "24005", "C.12580"))
#>       MD    24005  C.12580
#>  "STATE" "COUNTY"   "CBSA"

get.location.name(c("MD", "24005"))
#>                   MD              24005
#>         "Maryland"   "Baltimore County"

# Get all locations of a type
states <- get.all.for.type("STATE")  # 59 states/territories

# Get counties within a state
md_counties <- get.contained.locations("MD", "COUNTY")  # 24 counties

# Get counties for multiple states at once
county_list <- get.contained.locations(c("MD", "CA"), "COUNTY", return.list = TRUE)
# Returns a named list: county_list[["MD"]], county_list[["CA"]]

# Include a county that overlaps a tract-defined region but is not wholly contained
cook_county <- get.contained.locations("IL.1", "COUNTY", include.partial = TRUE)

# Find which state a county belongs to
get.containing.locations("24005", "STATE")
#> Maryland
#>     "MD"

# Find locations that overlap (e.g., which states does a CBSA span?)
get.overlapping.locations("C.12580", "STATE")

# Check if a type fully contains another
location.type.comprises("STATE", "COUNTY")   # TRUE
location.type.comprises("STATE", "CBSA")     # FALSE (CBSAs cross state lines)

Code Validation

# Sanitize converts acceptable codes to canonical form (uppercases, resolves aliases)
sanitize(c("md", "c.12580"))
#>        md   c.12580
#>      "MD" "C.12580"

# Check if codes are valid
is.location.valid(c("MD", "FAKE123"))
#>      MD FAKE123
#>    TRUE   FALSE

# Track code and bundled-data releases independently
packageVersion("locations")
locations.data.version()

# Look up a location code by name
get.location.code("Baltimore County", "COUNTY")

Code Aliases

Some FIPS codes have changed over time. The legacy dot-named API currently recognizes these compatibility mappings:

# Old CT code resolves to new code automatically
sanitize("09001")
#> 09001
#> "09110"

Connecticut warning: the old counties and new planning regions have different boundaries, so the one-to-one legacy mappings are not valid geographic crosswalks. Do not use them to transform historical Connecticut county data. The internal temporal store now contains the authoritative 19-edge, many-to-many Census area crosswalk, exposed through crosswalk_locations(). The legacy mappings remain temporarily so existing consumers do not break.

See API_COMPATIBILITY.md for the compatibility and data correction policy and Connecticut crosswalk migration for the crosswalk's direction, measures, and removal schedule.

Temporal Location API

The additive snake-case API queries the immutable, versioned county store. It does not use legacy aliases or silently convert historic official codes to a current geography.

# The default is pinned data metadata, not today's date
locations_default_date()

# Current or historical county versions at an explicit vintage
current_counties <- get_locations("COUNTY")
counties_in_2021 <- get_locations("COUNTY", "2021-01-01")
historic_counties <- get_locations("COUNTY", status = "historical")

# Without a date, return every identity that has used this code
resolve_location("02230")

# Historic CT codes remain historic records; they are not canonicalized
resolve_location("09003", as_of = "2021-01-01")

# A real former-county to planning-region crosswalk can have many targets
hartford_land <- crosswalk_locations("09003", measure = "land_area")
hartford_land[, c("to_code", "fraction_of_from", "measure_type")]

Temporal functions return data frames with durable IDs, version IDs, code and version validity intervals, the date used to classify status, and source URLs. Crosswalk measure names are explicit. Requesting an unavailable population measure produces an error; the package never substitutes land or water area.

Legacy and temporal county results

The two interfaces intentionally answer different questions during the 0.5.x migration:

Historic Connecticut county codes are legacy aliases rather than enumerated legacy locations. The temporal API instead returns them as eight distinct historical records and exposes their real many-to-many crosswalk. Preferred names may also differ where the temporal store preserves official diacritics or a more precise historical label while the compatibility view remains unchanged.

See the 0.5.0 release-readiness audit for the development-snapshot policy and the separately deferred stable-publication governance work.

Plotting

The location.plot() function creates maps with points or filled polygons. Requires the ggmap package and a Stadia Maps API key.

# install.packages("ggmap")  # if not already installed
# Sys.setenv(STADIA_MAPS_API_KEY = "your-key-here")

# Create a data frame with a 'locations' column and value columns
plot_data <- data.frame(
  locations = get.contained.locations("MD", "COUNTY"),
  value = runif(24)
)

# Plot as filled polygons
location.plot(plot_data, color = "value", fill = "value", bb = "AUTO")

# Plot as sized points (requires locations with lat/lon data)
location.plot(plot_data, color = "value", fill = "value", size = "value", bb = "AUTO")

Runtime Registration

You can register custom location types and locations at runtime:

# Register a new type
register.types("REGION", "R.", "Region.")

# Register locations of that type
register.locations("REGION", c("R.NORTHEAST", "R.SOUTH"), c("Northeast", "South"))

# Register hierarchical relationships
register.sub.and.super.locations(
  sub.locations = c("MD", "VA"),
  super.locations = c("R.SOUTH", "R.SOUTH"),
  super.completely.encloses.sub = TRUE
)

# Query works immediately
get.contained.locations("R.SOUTH", "STATE")

Recent Changes

v0.5.0.9000 (development) - Temporal County Model

v0.4.1 (2026-08) - Correctness and Provenance

v0.4.0 (2026-06) - TGA Location Type

v0.3.1 (2026-06) - Fixes

v0.3.0 (2026-02) - Internal Modernization

v0.2.0 (2025-12) - Location Registration Fix