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