Overview

StateBook's Atlas API is a REST interface for developers to obtain data from StateBook for use in their application or website. Developers can request as little as a single datapoint, or as much as a complete set of datapoints from multiple data sources across multiple geographic regions for multiple years.

Simple requests can be made using a standard URL string with arguments. More complex requests can be made by sending a JSON buffer with lists of datapoints, geographic regions, criteria, and options. Responses are always received as a JSON buffer containing the data, and optionally containing metadata and other useful information about the returned results. Developers can then process the JSON buffer within their webpage or application as needed.

The API requires a license and corresponding authentication token which is passed with the request. Licenses can be obtained by contacting StateBook.

Important Concepts

There are several important concepts that are essential to using the API.  These concepts represent the foundation of the API and are discussed in more detail throughout this documentation.

REST API

The Atlas API is a REST API, which is a common standard used for web-based API's.  For those not yet familiar with REST API's, there are a few key concepts:

To obtain data using a REST API, you make requests to a URL.  For Atlas, the URL is http://api.statebook.com.  This URL supports both GET requests and POST requests. 

In a GET request, the URL has parameters that describe the data to be returned.  The parameters can identify the datapoint(s) to be returned, the geographies to be accessed, and the time periods to be retrieved.  Since GET requests rely on everything being in the URL, GET requests are appropriate for just one or two datapoints with little criteria. 

In a more-powerful POST request, a JSON buffer is passed that describes the data to be returned.  POST requests can be as complex as needed, specifying a wide variety of datapoints and criteria in a single call.

Data is always returned in a response, which is a JSON buffer containing the data in a structured form.  A single response can contain as little as a single datapoint or as much as many datapoints for many geographies and many time periods.  

Geographies

Data is typically organized around one or more geographies. A geography can be a region, such as a state, county, metropolitan area, city, or even a block group. A geography can also be a custom area, such as a radius search around a specific location, a drive time isochrone around an address, a standard GeoJSON buffer representing a custom geography, or a specific list of regions to be treated as one whole region.

Datapoint

A datapoint is a specific element of data returned from the API, such as a number, a percentage, a string, or other value. Each datapoint is individually named and can be requested, described, and formatted as needed. Datapoints can also be requested in groups, such as requesting all datapoints related to total population.

Collection

A collection is a group of datapoints which occur multiple times, such as all airports in a county, or all occupations and their employment statistics. Collections may be nested, such as universities in a region and then their degrees broken out by major.

Criteria

Criteria determine which geographic regions are returned. This can be a single region, multiple regions, or custom regions.

Scope

The scope for datapoints and collections affects the depth of data returned by the API, such as expanding or restricting the number of years of data or limiting collections to specific sets of occupation or industry codes. Criteria and scope are similar; criteria determine the geographic regions that are to be returned and scope determines the depth of data to be returned.

Ordering

Collections can be ordered by specific datapoints so that they are presented in the desired order. This can also be coupled with the ability to return only the top n items.

Summarization

Results can be partially or completely aggregated, such as aggregating datapoints from multiple geography regions into one combined region, aggregating census block groups datapoints for a drivetime isochrone, or aggregating point level datapoints within a geographic region.

Options

Options allow you to control the behavior of the API. There are options to control whether additional metadata and other useful information is returned along with the data. There are also options to control whether data is formatted into strings or returned in a raw format.