REST API Interface

These objects are used to interact with the IPUMS REST API from Python.

Core API Interface

ipumspy.api.IpumsApiClient

Class for creating and retrieving IPUMS extracts via API

Extract Wrappers

Different IPUMS collections may have slightly different query parameters. Thus, to pull from a particular collection, you will need to use a particular extract class.

ipumspy.api.BaseExtract

A wrapper around an IPUMS extract.

ipumspy.api.OtherExtract

A generic extract object for working with collections that are not yet officially supported by this API library

ipumspy.api.UsaExtract

Defining an IPUMS USA extract.

ipumspy.api.CpsExtract

Defining an IPUMS CPS extract.

Importing or Exporting Extract Definitions

There are two convenience methods to transform ipumspy extract objects to dictionary objects and from dictonary objects to ipumspy extract objects.

ipumspy.api.extract_from_dict

Convert an extract that is currently specified as a dictionary (usually from a file) into a BaseExtract object.

ipumspy.api.extract_to_dict

Convert an extract object to a dictionary (usually to write to a file).

ipumspy.api.extract.save_extract_as_json

Convenience method to save an IPUMS extract definition to a json file.

ipumspy.api.extract.define_extract_from_json

Convenience method to convert an IPUMS extract definition or definitions stored in a json file into a BaseExtract object.

ipumspy.api.extract.define_extract_from_ddi

Create a BaseExtract object from a parsed DDI codebook.

Exceptions

Several different exceptions may be raised when interacting with the IPUMS API.

ipumspy.api.exceptions.IpumsApiException

ipumspy.api.exceptions.TransientIpumsApiException

ipumspy.api.exceptions.IpumsExtractNotReady

Represents the case that your extract is not yet ready

ipumspy.api.exceptions.IpumsTimeoutException

Represents when waiting for the IPUMS API times out

ipumspy.api.exceptions.IpumsAPIAuthenticationError

Represents attempted unauthorized API access

ipumspy.api.exceptions.BadIpumsApiRequest

Represents an error in the api request json, such as invalid sample id or var name

ipumspy.api.exceptions.IpumsExtractNotSubmitted

Represents the case when an extract needs to be submitted before the operation can be performed