download_extract: Download an IPUMS data extract

View source: R/api.R

download_extractR Documentation

Download an IPUMS data extract


Download an IPUMS data extract via the IPUMS API. For an overview of ipumsr microdata API functionality, see vignette("ipums-api", package = "ipumsr").


  download_dir = getwd(),
  overwrite = FALSE,
  api_key = Sys.getenv("IPUMS_API_KEY")



One of:

  • An ipums_extract object

  • The data collection and extract number formatted as a single string of the form "collection:number"

  • The data collection and extract number formatted as a vector of the form c("collection", "number")

The extract number does not need to be zero-padded (e.g., use "usa:1" or c("usa", "1"), not "usa:00001" or c("usa", "00001")). See Examples section below for examples of each form.

For a list of codes used to refer to each collection, see ipums_data_collections().


In what folder should the downloaded files be saved? Defaults to current working directory.


Logical indicating whether to overwrite files that already exist. Defaults to FALSE.


API key associated with your user account. Defaults to the value of environment variable "IPUMS_API_KEY".


Invisibly, the path to the downloaded .xml DDI file.

See Also

Other ipums_api: add_to_extract(), define_extract_cps(), define_extract_from_json(), define_extract_usa(), extract_list_to_tbl(), extract_tbl_to_list(), get_extract_info(), get_last_extract_info(), get_recent_extracts_info, ipums_data_collections(), is_extract_ready(), remove_from_extract(), save_extract_as_json(), set_ipums_api_key(), submit_extract(), wait_for_extract()


my_extract <- define_extract_usa("Example", "us2013a", "YEAR")

## Not run: 
submitted_extract <- submit_extract(my_extract)

# Download extract by supplying an ipums_extract object:
path_to_ddi_file <- download_extract(submitted_extract)

# By supplying the data collection and extract number, as a string:
path_to_ddi_file <- download_extract("usa:1")
# Note that there is no space before or after the colon, and no zero-padding
# of the extract number.

# By supplying the data collection and extract number, as a vector:
path_to_ddi_file <- download_extract(c("usa", "1"))

## End(Not run)

ipumsr documentation built on Sept. 30, 2022, 9:05 a.m.