Get Started with IPUMS APIs
To use IPUMS APIs, you’ll need three things:
- An IPUMS user account
- A valid registration for the data collection whose data you want to access (currently NHGIS data are available - USA coming soon)
- An API key
We’ve tried to make IPUMS APIs conform to standards and user expectations for a RESTful API. The APIs consist 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.
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.
New API users may wish to start with the sample workflow walkthroughs.
Alternately, the API reference documentation is also available.