Datapoints are individual pieces of information that can be requested using the API. Two examples of a datapoints are the total population and the average yearly change of population over the past five years. Both of those datapoint refer to the same topic - total population; however, they are different values and thus they are two separate datapoints.

A datapoint identifies what data you want, but it does not identify where or when. To make a complete request for a datapoint, you will also need to provide information on both geographies and time periods.

Individual Datapoints

The naming convention for datapoints organizes them into a logical hierarchy. For example, the datapoint for total population is dem.acs.pop.total.val. This translates as Demographics->US Census ACS ->Population->Total->Value. This is distinct from dem.acs.pop.total.ayc, which translates as Demographics->US Census ACS->Population->Total->Average Yearly Change. This hierarchy makes is easy to find the appropriate datapoint, and it also accommodates the fact that there may be different sources for each datapoint.

There are over 1,000 unique datapoints available in the API. When factoring in the many geographies and time periods for each datapoints, this produces millions of possible pieces of data that can be returned. A complete list of datapoints can be located at [URL to be determined].

When requesting multiple datapoints using the API, use one of two approaches. For the REST API, you can separate datapoints using commas, as shown in the following example. This URL will request two datapoints, rather than just one:

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

Similarly, if the POST method of the REST API or the JavaScript API is used, the request and response buffers would be as follows:

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val",
      "dem.acs.pop.total.ayc"
    ]
  },
  "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
      }
    ]
  }
};

Datatypes

All datapoints have a datatype. Generally, all datapoints are either a number, a percentage, or a string. Here are the datatypes that are supported in the API:

Formats

All numeric datapoints can be returned in their raw format or using a default character format. The raw format for an integer value of 12345 would be 12345; however, the default character format would be 12,345. Default formats may also include special characters, such as dollar signs, percent signs, degree signs, etc. The default character format for each datapoint can be found in this table of datapoints: [URL to be determined].

At present, it is not possible to override the default character format. If the default character format does not meet the application’s requirements, retrieve the raw format and then reformat it in the application as needed.

Datapoints and Geographic Context

A series of datapoints are not guaranteed to refer to the same geographic context. For example, a request could be made for the population for a city, plus the corresponding state tax rank. The geographic context of the population will be the city, but the geographic context of the state tax rank must be the state since the data is not available at the city level. The API will reflect this change of geographic context with geography elements, as shown in the following example.

A change in geographic context is indicated by using the geography keyword at different sections of the response buffer, as shown in this example. The requested geography is the city of Burlington, Vermont; however, the state tax ranks are for the entire state of Vermont.

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val",
      "econ.tax.str.ovrl"
    ]
  },
  "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": "econ.tax.str.ovrl",
        "period": "2019",
        "geography": "state:vermont",
        "value": 41
      }
    ]
  }
};