Overview

StateBook provides both a REST API and a JavaScript API 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 REST API uses a standard URL to retrieve data. The simplest example is to enter a URL in a web browser, which will then display the results. This same URL can be used in applications with GET methods to retrieve data. For more complex requests, the POST method allows a JSON buffer to be sent requesting multiple datapoints, geographies, criteria, and options. Both of these methods return a standardized JSON buffer containing the requested data.

JavaScript API

The JavaScript API is a wrapper around the REST API that makes it easy to retrieve information directly within a webpage. The internal syntax for requesting and receiving data is the same as the REST API, with the only difference being how the request is made within the application.

Resultset

The JavaScript API is a wrapper around the REST API that makes it easy to retrieve information directly within a webpage. The internal syntax for requesting and receiving data is the same as the REST API, with the only difference being how the request is made within the application.

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 a set of regions that meets complex criteria.

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 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

Resultsets 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.