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:

1. 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 APIs also provide all the necessary endpoints to do this programmatically.

1. 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.

2. 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.

3. 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 Creating Extracts sections of this documentation.