The API primarily consists of sending a request and obtaining a response.

The request buffer

The structure of the request buffer consists of three main sections – the requested data, any criteria, and any applicable options. The data section contains the list of the datapoints to be returned, plus information about collections and scope of data. The criteria section determines which specific geographies should be returned.  The options section controls how the data is formatted or whether additional diagnostic information is returned.

These are demonstrated in the following example:

var request = {
  "data": {
    ... 
  },
  "criteria": {
    ... 
  }
  "options": {
    ... 
  }
};

The response buffer

The structure of the response buffer consists of two main sections – the requested resultset and status. If an error occurs, an error section will also be present describing the error. There are other optional sections that provide more metadata and diagnostic information, but they are not provided unless requested. The resultset section consists of geographies (if applicable) and data. The status section provides diagnostic information for the API call.

These are demonstrated in the following example:

var response = {
  "resultset": {
    "geography": ... 
    "data": [
      ... 
    ]
  },

  "status": {
    ... 
  }
};

An example

The following example shows the request and response buffers from a complete API call and demonstrates this structure:

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val",
      "dem.acs.pop.total.ayc",
      "dem.acs.pop.total.aycp"
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "period": "2017",
        "source": "acs5",
        "value": 42453
      },
      {
        "datapoint": "dem.acs.pop.total.ayc",
        "period": "2017",
        "source": "acs5",
        "value": 31
      },
      {
        "datapoint": "dem.acs.pop.total.aycp",
        "period": "2017",
        "source": "acs5",
        "value": 0.0007
      }
    ]
  },
  "status": {
    "id": "cbbc4a05-f894-4b5d-9cdf-3839b7fe25bd",
    "timestamp": "2019-01-22T20:17:29.902480Z",
    "version": "1.0.0",
    "license": "The data returned from this StateBook Data API call is 
                restricted and may only be used in accordance with the 
                terms of a current and valid StateBook Data API license. 
                Any other use is strictly prohibited."
  }
};