Spatial Data Download and Utility Functions

A suite of conversion scripts to create internally standardized spatial polygons data frames. Utility scripts use these data sets to return values such as country, state, timezone, watershed, etc. associated with a set of longitude/latitude pairs. (They also make cool maps.)

CRAN_Status_Badge Downloads

A suite of conversion scripts to create internally standardized spatial
polygons dataframes. Utility scripts use these datasets to return values such
as country, state, timezone, watershed, etc. associated with a set of 
longitude/latitude pairs. (They also make cool maps.)


The MazamaSpatialUtils package was created by MazamaScience to regularize our work with spatial data. The sp, rgdal and maptools packages have made it much easier to work with spatial data found in shapefiles. Many sources of shapefile data are available and can be used to make beautfiul maps in R. Unfortunately, the data attached to these datasets, even when fairly complete, often lacks standardized identifiers such as the ISO 3166-1 alpha-2 encodings for countries. Maddeningly, even when these ISO codes are used, the dataframe column in which they are stored does not have a standardized name. It may be called ISO or ISO2 or alpha or COUNTRY or any of a dozen other names we have seen.

While many mapping packages provide ‘natural’ naming of countries, those who wish to develop operational, GIS-like systems need something that is both standardized and language-independent. The ISO 3166-1 alpha-2 encodings have emerged as the defacto standard for this sort of work. In similar fashion, ISO 3166-2 alpha-2 encodings are aviailable for the next administrative level down – state/province/oblast, etc.. For timezones, the defacto standard is the set of Olson timezones used in all UNIX systems.

The main goal of this package is to create an internally standardized set of spatial data that we can use in various projects. Along with three built-in datasets, this package provides ‘convert~’ functions for other spatial datasets that we currently use. These convert functions all follow the same recipe:

  • download spatial data in shapefile format into a standard directory
  • convert shapefile data into a sp SpatialPolygonsDataFrame
  • modify the dataframe in the @data slot so that it adheres to package internal standards

Other datasets can be added following the same procedure.

The ‘package internal standards’ are very simple. Every spatial dataset will have at least one of the following, consistently named colums of data:

  • polygonID – unique identifier associated with each polygon
  • countryCode – ISO 3166-1 alpha-2
  • stateCode – ISO 3166-2 alpha-2
  • timezone – Olson timezone

If another column contains this data, that column must be renamed or duplicated with the internally standardized name. This simple level of consistency makes it posisble to generate maps for any data that is ISO encoded. It also makes it possible to create functions that return the country, state or timezone associated with a set of locations.


This package is designed to be used with R (>= 3.1.0) and RStudio so make sure you have those installed first.

Users will want to install the devtools package to have access to latest versions of some packages that are not yet available on CRAN.

The following packages should be installed with devtools by typing the following at the RStudio console:

devtools::install_github('mazamascience/MazamaSpatialUtils', build_vignettes=TRUE)


Pre-generated .RData versions of the following standardized shapefiles are available at

 * 2.1M	EEZCountries.RData
 *  15M	NaturalEarthAdm1.RData
 *  61M	OSMTimezones.RData
 * 3.0M	OSMTimezones_05.RData
 * 3.6M	TMWorldBorders.RData
 *  48M	TerrestrialEcoregions.RData
 * 3.5M	TerrestrialEcoregions_05.RData
 * 7.5M	USCensus115thCongress.RData
 * 2.2M	USCensusCounties.RData
 * 3.4M	USCensusStates.RData
 * 1.2M	USIndianLands.RData
 * 768M	WBDHU10.RData
 * 1.4G	WBDHU12.RData
 *  38M	WBDHU2.RData
 * 424K	WBDHU2_01.RData
 * 840K	WBDHU2_02.RData
 * 107M	WBDHU4.RData
 * 1.1M	WBDHU4_01.RData
 * 2.2M	WBDHU4_02.RData
 * 136M	WBDHU6.RData
 * 1.4M	WBDHU6_01.RData
 * 2.8M	WBDHU6_02.RData
 * 294M	WBDHU8.RData
 *  17M	WorldTimezones.RData


The package vigentte 'Introduction to MazamaSpatialUtils' has numerous examples.

This project is supported by Mazama Science.


Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.5.4 by Jonathan Callahan, 4 months ago

Browse source code at

Authors: Jonathan Callahan [aut, cre] , Ruby Fore [aut] , Will Leahy [aut] , Helen Miller [aut] , Henry Nguyen [aut] , Robin Winstanley [aut] , Alice Yang [aut]

Documentation:   PDF Manual  

GPL-2 license

Imports dplyr, lubridate, rgdal, rgeos, rmapshaper, rvest, stringr, utils, xml2

Depends on sp

Suggests knitr, maps, markdown, readr, testthat

Depended on by PWFSLSmoke.

See at CRAN