Wait for extract to finish

Wait for an extract to finish by periodically checking its status via the IPUMS API and returning when the extract is ready to download. For an overview of ipumsr microdata API functionality, see vignette("ipums-api", package = "ipumsr").

wait_for_extract(
  extract,
  initial_delay_seconds = 0,
  max_delay_seconds = 300,
  timeout_seconds = 10800,
  verbose = TRUE,
  api_key = Sys.getenv("IPUMS_API_KEY")
)

Arguments

extract

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().

initial_delay_seconds

How many seconds to wait before first status check.

max_delay_seconds

Maximum seconds to wait between status checks. The function doubles the wait time after each check, but will cap the wait time at this maximum value (300 seconds, or 5 minutes, by default).

timeout_seconds

Maximum total number of seconds to continue waiting for the extract before throwing an error. Defaults to 10,800 seconds (three hours).

verbose

If TRUE, the default, messages will be printed at the beginning of each wait interval with the current wait time, each time the status of the extract is checked, and when the extract is ready to download. Setting this argument to FALSE will silence these messages.

api_key

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

Value

An ipums_extract object containing the extract definition and the URLs from which to download extract files.

See also

Other ipums_api: add_to_extract(), define_extract_cps(), define_extract_from_json(), define_extract_usa(), download_extract(), 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()

Examples

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

if (FALSE) {
submitted_extract <- submit_extract(my_extract)

# Wait for extract by supplying ipums_extract object:
downloadable_extract <- wait_for_extract(submitted_extract)

# By supplying the data collection and extract number, as a string:
downloadable_extract <- wait_for_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:
downloadable_extract <- wait_for_extract(c("usa", "1"))
}