By Renae Rodgers
Have you heard the news?! The IPUMS Extract API now supports microdata! For users who have been clamoring for this feature for some time, feel free to skip to the final section for resources to get started. For our users who haven’t been awaiting this announcement with bated breath, and who may be saying to themselves, “ok…great…but…”
This blog post will give a brief introduction to APIs, give some examples of ways to use the IPUMS Extract API in your workflow, and share some more in-depth resources.
What is an API?
API stands for Application Programming Interface. An API is an intermediate layer between a user and a server that allows the user to interact programmatically with another program or a service. First, the user’s program talks to the API – this is known as making an API call or a request. The API, in turn, talks to the server, translating the user’s request into something the server can understand. The server returns the requested information to the API, and the API then returns that information to the user. For example, Google Maps has an API that allows developers to request and retrieve information from Google Maps from within their applications, without needing to go through a web interface.
At this point you may be thinking, “great, now I have a general idea of what an API is, but I am not a software developer so… thanks anyway.”
The IPUMS Extract API opens up many possibilities for easing collaboration, and creating efficient workflows with only a few simple lines of code. Please read on!
What can you do with the IPUMS Extract API?
The IPUMS Extract API makes it possible for users to make extracts without clicking their way through the IPUMS website. IPUMS maintains client libraries for R and Python to make it easy for users to make IPUMS extract requests directly from their code! The possibility of making extracts from within your code offers three potential improvements to workflows involving IPUMS data.
1. Easy to update extracts to include newly available samples
Updating analyses to include the most recently available data is a breeze using the IPUMS Extract API! For example, if you’re the kind of person that has IPUMS CPS release weeks marked on your calendar (I know I am), you only need to add the latest CPS month to your list of samples to request and re-run your code to see the latest developments!
2. Even quicker addition of forgotten variables
For those of us living the “revision of (revision of (revision of” life, making an IPUMS extract via the Extract API makes adding that one crucial variable we forgot as easy as adding that variable to a list and re-running our code!
3. Smoother collaboration using IPUMS data
If your collaborator is a registered IPUMS user and you both use the same software for crunching your numbers, your collaborator can reproduce your extract by running your code! Alternatively, your collaborator can run their own analyses on an identical extract by using an extract definition you provide to them. Watch for upcoming blog posts about sharing extracts using the IPUMS Extract API!
Some resources to help you on your IPUMS Extract API journey
To get started using the IPUMS Extract API to make IPUMS microdata extracts, make sure you have an account with the IPUMS data collection of interest and have generated an API key. More information about API keys is available on the IPUMS Developer Portal Getting Started page.
IPUMS maintains R and Python client libraries to make requesting and downloading extracts via the Extract API easy. The ability to make extract requests to the IPUMS Extract API is now included in ipumsr. The ipumspy python library makes it easy to make microdata extract requests to the IPUMS Extract API, download your extract, and read it into pandas. Huge thanks to Kevin Wilson at The Policy Lab at Brown University for getting that project off the ground! Example workflows using each of these packages is also available on the IPUMS Developer Portal.
Have a question about the API? Check out the IPUMS API section of the user forum!
Hopefully you can’t wait to get started integrating the IPUMS Extract API into your microdata workflows! Before you dive in, please note that our Extract API is still in beta and not all IPUMS data collections and data extract features are supported at this stage. The IPUMS Developer Portal contains a list of IPUMS collections available via API and a list of supported and unsupported features for each.
Use It For Good!
