Workflows & Code
This section walks through some common tasks users might want to achieve with the IPUMS API.
Workflow 1: Create and Retrieve a Data Extract
The primary use case for the IPUMS API is to programmatically create and retrieve data extracts. In this workflow, we’ll show you how to use the API to create and retrieve a data extract.
Overview
The steps to complete this workflow are as follows:
-
Construct a valid JSON-formatted request
Construct a valid extract request in JSON format using IPUMS metadata. This information can largely be obtained by browsing the IPUMS websites, but our API also provides all the necessary endpoints to do this programmatically for IPUMS NHGIS, with similar support for microdata collection metadata access via API on our upcoming roadmap.
-
Submit the data extract request to the API
Once you have your extract request payload, you will submit it to the API by POSTing your JSON-formatted request to the API. A successful request will return a response that includes the extract number, which will be needed for later steps.
-
Monitor the extract request’s progress
Once the extract request is submitted, you can use the API to get a list of your extract requests. Searching that list for the extract with the number that was assigned in the previous step will allow you to check its status to see if it has completed.
-
Retrieve your extract
Once completed, the response will include download links for the extract’s files (the type and number of files may vary depending on the kind of extract you requested). You can then visit those URLs programmatically and get a file stream in response.
Implementing this Workflow
Code samples for implementing this workflow are available in the Explore Metadata and Create Extracts sections of this documentation.
In addition, Python and R users who are interested in working with our microdata collections via API are encouraged to use the Python and R client library SDKs.