IPUMS API Client SDK Libraries for R and Python
In order to help foster onboarding of API users and reduce the learning curve, we aim to provide client software development kits (SDKs) in the form of language-specific libraries that allow users to work with our API in ways that are more native to / idiomatic for their language of choice.
We are currently focused on adding API support to the existing software development kit (SDK) tools ipumsr for R and ipumspy for Python. Our goal with these client SDK tools is to enable users to interact with the IPUMS API by simply making function/method calls, abstracting away all of the http and JSON details that happen behind the scenes. You can find more details about their current API support in the sections below.
These SDKs are open source software, and we invite collaboration from IPUMS users to help us build and extend these tools to make them as useful as possible for our community, while still providing stewardship and user support as we do with all of the other components of the IPUMS data collections.
For users that do prefer to interact directly with the API using http and JSON, and for users using other languages or where collection support is not yet available in the SDKs, we also provide API workflow examples using direct RESTful HTTP calls as well as complete OpenAPI specification reference material for our API.
ipumsr is an R SDK which provides many utilities for working with IPUMS extracts. ipumsr has support for working with traditional extracts from all of the IPUMS microdata collections plus IPUMS NHGIS.
Recent versions of ipumsr have introduced the ability to interact with the IPUMS API. Currently, ipumsr can be used to construct, submit, monitor and retrieve IPUMS USA, IPUMS CPS, IPUMS International, and IPUMS NHGIS extracts via the IPUMS API using only native R code. ipumsr also allows users to query metadata for IPUMS NHGIS. In July 2023, ipumsr released version 0.6.0 which has implemented support for IPUMS API Version 2 for all supported collections.
- IPUMS API Version 2, IPUMS NHGIS, and IPUMS International are supported by ipumsr >= 0.6.0
- IPUMS API Version 1 for IPUMS USA and IPUMS CPS is supported by ipumsr < 0.6.0
ipumspy is a Python SDK which provides many utilities for working with IPUMS microdata extracts in rectangular data structure from all of the IPUMS microdata collections. ipumspy currently has no support for aggregate/spatial IPUMS data collections.
Recent versions of ipumspy have introduced the ability to interact with the IPUMS API. Currently, ipumspy can be used to construct, submit, monitor and retrieve IPUMS USA, IPUMS CPS and IPUMS International extracts via the IPUMS API using only native Python code. In April 2023, ipumspy released version 0.3.0 which has implemented support for IPUMS API Version 2 for the microdata (USA, CPS, International) collections only.
- IPUMS API Version 2 is supported by ipumspy >= 0.3.0
- IPUMS API Version 1 is supported by ipumspy < 0.3.0