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")
)
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()
.
How many seconds to wait before first status check.
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).
Maximum total number of seconds to continue waiting for the extract before throwing an error. Defaults to 10,800 seconds (three hours).
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 associated with your user account. Defaults to the value of environment variable "IPUMS_API_KEY".
An ipums_extract
object containing the
extract definition and the URLs from which to download extract files.
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()
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"))
}