Hierarchical US geographic location manager for the jheem2 project. Provides fast lookups, hierarchical queries, code aliasing, and geospatial plotting across multiple geographic resolutions.
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.
| 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. |
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)
# 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")
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.
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.
The two interfaces intentionally answer different questions during the 0.5.x migration:
get.all.for.type("COUNTY") retains its 3,241-record, all-vintage legacy
compatibility result;get_locations("COUNTY") returns 3,222 county equivalents current at the
pinned 2025-01-01 reference date; and30113. No current temporal county code is absent from
the legacy enumeration.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.
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")
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")
v0.5.0.9000 (development) - Temporal County Model
v0.4.1 (2026-08) - Correctness and Provenance
include.partial argumentv0.4.0 (2026-06) - TGA Location Type
TGA (Ryan White Transitional Grant Area) as a data-driven location typedata-raw/tga_definitions.csv
v0.3.1 (2026-06) - Fixes
register.relationship.between.types() now accepts lowercase type names (was the only registration function that required uppercase)packageVersion("locations") was stuck at 0.1.0)v0.3.0 (2026-02) - Internal Modernization
v0.2.0 (2025-12) - Location Registration Fix