IPUMS API Client Libraries
In order to help foster onboarding of API users and reduce the learning curve, we aim to provide client libraries that allow users to work with our APIs in ways that are more native to / idiomatic for their language of choice. For our first client libraries we are focusing on the languages Python (ipumspy) and R (ipumsr). Our goal with these client tools is to enable users to interact with IPUMS APIs by simply making function/method calls, abstracting away all of the http and JSON details that happen behind the scenes.
In addition, we intend to develop these modules as open source software, inviting 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, we will also provide API workflow examples using curl, as well as complete OpenAPI specification reference material for our APIs.
ipumsr was first released in 2017. It launched with support for unpacking “traditional” IPUMS microdata and aggregate data extracts into R data structures, and provided a number of convenience functions for working with the data once unpacked. In 2021 we added support for the IPUMS Data Extract API for USA and CPS to ipumsr. Now ipumsr can be used to construct, submit, monitor and retrieve USA and CPS extracts using native R code. In the future we hope to add support for interacting with the IPUMS NHGIS API as well.
ipumspy was developed and released in conjunction with the launch of the IPUMS Data Extract API for USA, and now also supports IPUMS CPS. Like ipumsr, it can be used to construct, submit, monitor and retrieve IPUMS USA and CPS extracts via the IPUMS Data Extract API using only native Python code.
It currently is a microdata-only client library, as it does not yet have any support for working with IPUMS NHGIS extracts, neither via the traditional extract route nor via the IPUMS NHGIS API.