Get Started with the IPUMS API
To use the IPUMS API, you’ll need three things:
- An IPUMS user account
- A valid registration for the data collection whose data you want to access (currently NHGIS, USA and CPS data are available)
- An API key
We’ve tried to make the IPUMS API conform to standards and user expectations for a RESTful API. The API consists of endpoints with which users can interact using HTTP GET and POST requests. JSON is the payload format for requests and responses.
IPUMS Account and Data Collection Registration
If you don’t have an IPUMS account, or if your IPUMS account is not registered to access the IPUMS data collection you wish to use with the API, go to that data collection’s website - IPUMS NHGIS for example - and click the Login link to create an IPUMS account or add a data collection registration to your existing account.
Getting an API Key
IPUMS users can obtain an API key by visiting https://account.ipums.org/api_keys.
These keys do not expire but are rate limited to 100 requests per minute.
Please protect your key exactly as you would your IPUMS account credentials. IPUMS API usage is governed by the same terms that govern IPUMS website usage.
Authentication
The API key will need to be included with every request to the API. This is done by setting a request header:
Authorization: <YOUR API KEY GOES HERE>
Each language and library has its own method for setting request headers. You can see examples in our sample workflow walkthroughs.
Next Steps
New API users may wish to start with the sample workflow walkthroughs.
Alternately, the API reference documentation is also available.