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.
`ipumspy.api.IpumsiExtract`	Defining an IPUMS International extract.

Other IPUMS Objects#

Helpful data classes for defining IPUMS Extract objects.

`ipumspy.api.Variable`	IPUMS variable object to include in an IPUMS extract object.
`ipumspy.api.Sample`	IPUMS sample object to include in an IPUMS extract object.

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.

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