Statebook.displayData({
  authentication: 'eyJhbGciOiJIUzI1NiI...',
  container: 'x',
  templates: ['chart'],
  components: [{
    type: 'chart',
    topic: 'demographics.ageRanges',
    style: 'singleYear',
    filters: {
      geographies: ['cbsa:albany-schenectady-troy-ny-metro-area'],
      periods: ['2016'],
      sources: ['acs5']
    }
  }]
});

Configuration Specifications

The following specification describes all of the options available for configuring charts, component packs, and dashboards.

configuration: {

  // -----------------------------------------------------------------------------
  // Required elements
  // -----------------------------------------------------------------------------
  authentication: ' ',  // An authentication token permitting access to StateBook
                        // data. Contact StateBook to obtain a token. The token,
                        // "demo" can be used to access data from the 
                        /// Burlington-South Burlington, VT Metro Area
                              
  container: ' ',       // The div ID within webpage for displaying results.
                        // Note that the div should be declared before the
                        // JavaScript API call.

  // -----------------------------------------------------------------------------
  // Optional elements.Only needed to override the default settings.
  // -----------------------------------------------------------------------------

  templates: [' '],     // Array of preconfigured templates (currently 1)
                        // See section below for currently supported templates.
                        // Defaults to dashboard.

  controls: [' '],      // Pulldown/textbox controls to manage components
                        // Choices: geographies, topics, styles, periods, items
                        // Defaults to all appropriate controls.
   
  topics: [' '],        // Array of topics to be available in display. 
                        // See section below for available topics. 
                        // Defaults to all available topics.

  styles: [' '],        // Array of component styles to be available in display.
                        // See section below for available styles.
                        // Defaults to all available styles.

  filters: {},          // Filters to restrict the available data. Defaults to 
                        // See expanded definition below. 
                        // Defaults to all data for this authentication token.

  options: {},          // Options to control appearance/behavior of display. 
                        // See expanded definition below.
                        // Defaults to standard settings for each component.

  components: [{}],     // An array of individually configured components.
                        // See expanded definition below.
                        // Defaults to all available components
},
  
filters: {
  geographies: [' '],   // An array of geographies (ie. website slugs). Defaults
                        // to all geographies for this authentication code.

  periods: [' '],


  sources: [' '],

  relatedGeographies: true, // Include smaller geographies in addition to the
                            // named geographies.  Defaults to true.

  initialGeography: ' ',// Display the named geography when first loaded.
                        // Defaults to the primary geography.

  items: [' '],         // An array of data items (benchmark charts only)
                        // Defaults vary based on the specific template.
},
  
options: {
  height: 0,            // Height of display in pixels.
                        // Defaults to the size of the provided containing div

  width: 0,             // Width of display in pixels.
                        // Defaults to the size of the provided containing div

  title: ' ',           // Title above components w/optional replacement tokens
                        // See section below for available replacement tokens
                        // Defaults to the standard title

  subtitle: ' ',        // Subtitle above components w/optional replacement tokens
                        // See section below for available replacement tokens
                        // Defaults to the standard subtitle
                         
  margin: 0,            // The margin used between components, in pixels.
                        // The default margin varies based on specific template

  border: true,         // The border surrounding component. True/false/pixels
                        // The default border varies based on specific template

  numColumns: 1,        // The number of columns of components used in template.
                        // ComponentPack limited to 1; dashboard defaults to 2.
                         
  colors: ['#xxxxxx'],  // An array of hex codes for default chart series colors.
                        // When all named colors are used, colors are recycled
 
  xAxisMax: 0,          // Maximum number of bars or columns in the X axis
                        // Defaults vary based on template, topic, and style
},
  
component: {
    type: ' ',            // The type of component to be displayed.
                          // See section below for available component types.
                          // Required
 
    topic: ' ',           // The topic to be displayed in this component.
                          // See section below for available topics.
 
    style: ' ',           // The style of component to be displayed.
                          // See section below for available styles
 
    options: {},          // Options to control the display. 
                          // See expanded definition above.
 
    filters: {},          // Filters to determine specific geographies, period, 
                          // or items.  See expanded definition above.
                            
},
    

Templates

The following templates are currently available.  Please check back regularly as this list will expand regularly.

• dashboard
• componentPack
• chart

Topics

Styles

Note that not all styles of charts are available for all topics due to the availability of the underlying data.

• singleYear
• fiveYearHistory
• averageYearlyChange
• benchmark

Title and Subtitle Replacement Tokens

The title and subtitle can be customized to meet your specific needs. You can use certain replacement tokens to include information such as the year, the geography, etc.  The following replacement tokens are supported:

Additionally, multi-line titles and subtitles can be specified using the <br> token to represent the linefeed.  Other HTML syntax may work but is not officially supported.

Example

title: '{subject} for {period}',
subtitle: '{itemCode} - {itemDescription} {geography}',

Component Types

At present, the only component type is ‘chart’.

Sources

The choices for sources apply to the US Census ACS data, determining whether ACS 1-Year or 5-Year data is used:

• acs1
• acs5

Sample Web Pages

Several working examples of charts, component packs, and dashboards can be found at http://www.statebookdemos.com. These web pages are purposefully as simple as possible so they are easy to read when asking the browser to view the source code.

Licensing and User Authentication

Use of the API requires an authentication token to be passed in each call.  These tokens can be obtain by contacting StateBook.  The API token grants access to the following:

• Use from specific website domain names.
• Use for specific geographies.

For demonstration and development purposes, the authentication token "demo" can be used.  This provides access to all of the data available for the Burlington-South Burlington, VT Metro Area.  The example below shows this token being used:

Statebook.displayData({
  authentication: 'demo',
  container: 'x'
});

The use of this API is subject to the Terms of Service shown on the StateBook website (https://www.statebook.com/terms).

A Note on Backward Compatibility

The API specification in this document may change over time.  Certain parts of the specification are likely to be especially stable while other parts of the specification will be more prone to change.  This should be considered when developing a website using the API.

The JavaScript function, Statebook.displayData(), is likely to remain stable, as are the basic choices for controlling the layout of the charts and graphs.  The specific charts and component packs that are available will change over time as new data becomes available and as existing data becomes unavailable.  StateBook will endeavor to notify users when topics or other aspects of the specification change so that developers have a chance to accommodate the change.