API Versions

Documentation > API Program

The IPUMS API Program

The IPUMS API Program is the home for all API-related activity at IPUMS across all of our data collections. This page provides a brief overview of our API Program.

IPUMS API Community Forum

If you need help at any time in your work with the IPUMS API, please join us in the IPUMS API area of the IPUMS user forum.

Asset Types

The IPUMS API allows access to two primary types of IPUMS assets: data and metadata. IPUMS API functionality is organized into metadata and data endpoints like so:

  • Metadata - API endpoints which provide metadata about IPUMS data. These endpoints are used for data discovery and availability exploration as well as for retrieving codes, names, and other bits of information which are necessary to form requests to our data extract request endpoint.

  • Data - Endpoints which can be used to request and retrieve IPUMS data. Data endpoints are further divided into two flavors:

    • Data Extract - Endpoints which receive data requests from API users and submit them for background processing. The data is not returned right away, rather, API users monitor the status of their request, and when requests are completed data can be retrieved. This is the model which most closely resembles the website experience with our IPUMS data collections and produces the same exact kinds of extracts that website requests do (complete with codebook, syntax files, and so on).

    • Data Streaming - (Do Not Exist Yet) Endpoints which return data immediately. Most appropriate for smaller amounts of microdata or tabulated data, and for applications which support real-time data browsing.

Differences Between IPUMS Data Collections

The IPUMS data collection contains many different types of data. IPUMS data includes:

  • Microdata - Records representing individual persons and households or sets of attributes that nest under individual persons or households (e.g. activities, injuries).
  • Aggregate Data - Records representing aggregate calculations (e.g. sums, medians, averages, max, min) for a given geographic area (e.g. counties, states, census tracts).
  • Spatial Data - Rasters, vectors, point data representing spatial entities (e.g. political boundaries, locations, latitude/longitude).

Unlike our website portfolio, where each data collection has its own website, our API is used across our data collections. Although we try to stick to as many of the same names and conventions across data collections, there are some fundamental differences. For example, the microdata collections require that the API user submit a different payload for an extract request than IPUMS NHGIS, which is an aggregate & spatial data collection. This largely has to do with differences in how these collections are structured and organized.

Nevertheless, both the microdata collections and IPUMS NHGIS follow the overall design and pattern we’ve established for data extract requests. The same overall pattern can be used to create extracts from IPUMS USA, IPUMS CPS, IPUMS International or IPUMS NHGIS. The details of the request naturally are different for the two use cases, but they all use the same API endpoints - they only differ in the details of the JSON payload that specifies your extract request.

Specifying which data collection you’d like to use requires passing the appropriate collection name as a query parameter and then providing the proper extract request payload for your chosen data collection. Any data-collection-specific details the user needs to be aware of are covered in the sample workflows and in the API reference documentation.

Got Feedback?

The IPUMS API Program is fostered by the IPUMS API Program Support Team. We hang out on the IPUMS user forum’s API category. You can also email feedback to ipums+api@umn.edu and we’ll reply as soon as we can!