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.MicrodataExtract`	Class for defining an extract for an IPUMS microdata collection.
`ipumspy.api.AggregateDataExtract`	Class for defining an extract request for an IPUMS aggregate data collection.

Other IPUMS Objects#

Helpful data classes for defining IPUMS Extract objects.

`ipumspy.api.Variable`	IPUMS variable object to include in a `MicrodataExtract` object.
`ipumspy.api.Sample`	IPUMS sample object to include in a `MicrodataExtract` object.
`ipumspy.api.TimeUseVariable`	IPUMS time use variable to include in a `MicrodataExtract` object.
`ipumspy.api.NhgisDataset`	IPUMS dataset object to include in an `AggregateDataExtract` object.
`ipumspy.api.IhgisDataset`	IPUMS dataset object to include in an `AggregateDataExtract` object.
`ipumspy.api.TimeSeriesTable`	IPUMS time series table object to include in an `AggregateDataExtract` object.
`ipumspy.api.Shapefile`	IPUMS shapefile object to include in an `AggregateDataExtract` 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.

IPUMS Metadata#

Use these classes and methods to request IPUMS metadata for aggregate data collections via the IPUMS API.

`ipumspy.api.metadata.NhgisDatasetMetadata`	Class to request and store metadata for an IPUMS NHGIS dataset
`ipumspy.api.metadata.IhgisDatasetMetadata`	Class to request and store metadata for an IPUMS IHGIS dataset
`ipumspy.api.metadata.NhgisDataTableMetadata`	Class to request and store metadata for an IPUMS NHGIS data table
`ipumspy.api.metadata.IhgisDataTableMetadata`	Class to request and store metadata for an IPUMS IHGIS data table
`ipumspy.api.metadata.TimeSeriesTableMetadata`	Class to request and store metadata for an IPUMS time series table.

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
`ipumspy.api.exceptions.IpumsApiRateLimitException`	Represents a request that exceeds the IPUMS API rate limit