The API requires either a bearer authentication token or credentials which are passed with each request.  Tokens and credentials can be obtained by contacting StateBook.  These tokens or credentials will determine which datapoints, geographies, and features that you can access, which IP addresses or URL names from which you can call the API, and and any limits on the number of API calls you can make.  

Your tokens and credentials are directly tied to your billing account.  All API calls made with your tokens or credentials will be billed to your account.  Be sure to keep these confidential and do not share them with anyone.

A bearer token, also known as an authentication token, can be passed as a parameter in a GET request or  can be provided in the bearer token header of an API call.  Credentials, meaning a user and password, can only be sent in basic authorization headers in order to insure privacy.

The DEMO Bearer Token

There is a special bearer token which can be used by everyone for demonstrations, evaluations, and testing.  This token provides access to most of the features of the API, but only for a limited set of geographies - specifically the Burlington and South Burlington, VT Metropolitan Area.  The following table shows all of the names of the regions and their slugs.

GET Requests

 For GET requests, the authentication token is passed as a parameter in the URL. In the following example, the demo authentication token is passed using the "auth" parameter.

This example will use the following parameters:

If you enter the following into your browser …

https://api.statebook.com/api/v1/getdata?auth=demo&data=dem.acs.pop.total.val&geo=city:burlington-vt

POST Requests

For POST requests, the authentication token is passed in the Authorization request header as a bearer token.  In the following example, CURL is used to issue a simple request:

POST /api/v1/getdata HTTP/1.1
Host: api.statebook.com
Content-Type: application/json
Authorization: Bearer demo
{
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
}

In the following example, CURL is used to issue the same request:

curl -X POST \
  https://api.statebook.com/api/v1/getdata \
  -H 'Authorization: Bearer demo' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
}