Get Started with IPUMS APIs

To use IPUMS APIs, you’ll need three things:

  1. An IPUMS user account that has been enabled for our beta API program
  2. A valid registration for the product whose data you want to access (currently NHGIS data are available - USA coming soon)
  3. 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 Product Registration

If you don’t have an IPUMS account, or if your IPUMS account is not registered to access the IPUMS product you wish to use with the API, go to that product’s website - IPUMS NHGIS for example - and click the Login link to create an IPUMS account or add a product registration to your existing account.

Enabling an IPUMS Account for the API Beta Program

During the early days of our beta program, participation is by invitation only. Please send a request to ipums+api@umn.edu with the subject “Join API Beta Program” and we’ll do our best to get back to you as soon as we can.

Getting an API Key

Once an IPUMS user account has been enabled for the API Beta Program, users can obtain an API key by visiting https://account.ipums.org/api_keys.

These beta program keys are set to expire in a year and 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 / 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.