Developers Guide
JavaScript headers
The StateBook API will require inclusion of CSS and JS files in the <head> section of a webpage.
<link href="https://api.statebook.com/api/v1/css/jquery/jquery-ui.css" rel="stylesheet"> <link href="https://api.statebook.com/api/v1/css/statebook-display.css" rel="stylesheet"> <script src="https://api.statebook.com/api/v1/js/jquery/jquery.js"></script> <script src="https://api.statebook.com/api/v1/js/jquery/jquery-ui.js"></script> <script src="https://api.statebook.com/api/v1/js/highcharts.js"></script> <script src="https://api.statebook.com/api/v1/js/statebook.js"></script> <script src="https://api.statebook.com/api/v1/js/statebook-display.js"></script>
Note to WordPress developers: For most WordPress themes, these changes should be inserted into the header.php file for the theme so that they can properly reside within the <head> section of the webpage.
JavaScript functions
Statebook.displayData()
The displayData
function is the primary JavaScript function to display StateBook data on the website.
Statebook.displayData (configuration)
configuration
The configuration for the data to be displayed based on the specification in Configuration Specifications below.
Examples
The following example shows a dashboard for all topics with all of the default settings:
Statebook.displayData({ authentication: 'eyJhbGciOiJIUzI1NiI...', container: 'x' });
The following example shows a componentPack for all topics with all of the default settings:
Statebook.displayData({ authentication: 'eyJhbGciOiJIUzI1NiI...', container: 'x', templates: ['componentPack'] });
The following example shows an individual chart for a specific topic, geographic area, and year:
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
Topic
|
Chart
|
Component
Pack
|
Dashboard
|
---|---|---|---|
all |
X | X | |
demographics |
X | X | |
demographics.ageRanges |
X | X | X |
demographics.raceAndEthnicity |
X | X | X |
education |
X | X | |
education.attainment |
X | X | |
education.attainment.age25Plus |
X | X | X |
education.higherEducation |
X | X | |
education.higherEducation.degrees |
X | X | |
education.higherEducation.degrees.associates |
X | X | X |
education.higherEducation.degrees.bachelors |
X | X | X |
education.higherEducation.degrees.masters |
X | X | X |
education.higherEducation.degrees.phd |
X | X | X |
education.higherEducation.degrees.doctor |
X | X | X |
education.higherEducation.awards |
X | X | |
education.higherEducation.awards.lessThanOneYear |
X | X | X |
education.higherEducation.awards.oneToLessThanTwoYears |
X | X | X |
education.higherEducation.awards.twoToLessThanFourYears |
X | X | X |
households |
X | X | |
households.income |
X | X | X |
workforce |
X | X | |
workforce.employment |
X | X | |
workforce.employment.fullTimeYearRoundWorkers |
X | X | X |
workforce.occupations |
X | X | |
workforce.occupations.employment |
X | X | X |
workforce.occupations.locationQuotient |
X | X | X |
workforce.occupations.jobsPerThousand |
X | X | X |
industries |
X | X | |
industries.byNAICS |
X | X | |
industries.byNAICS.employment |
X | X | X |
industries.byNAICS.annualPayroll |
X | X | X |
industries.byNAICS.establishmentCount |
X | X | X |
transportation |
X | X | |
transportation.commute |
X | X | |
transportation.commute.commuteByMode |
X | X | X |
transportation.commute.commuteByTravelTimeToWork |
X | X | X |
housing |
X | X | |
housing.housingCostsAsPercentOfHHI |
X | X | X |
housing.rentAsPercentOfHHI |
X | X | X |
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:
Token
|
Description
|
---|---|
{subject} | The subject of the component, roughly correlated with the topic. |
{geography} | The geography used in the component. |
{period} | The time period for the data in the component. |
{attribution} | The attribution for the data. |
{itemDescription} | The description of the item within benchmark and drilldown components. |
{itemCode} | The item code within benchmark and drilldown components. |
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.
Comments
0 comments
Article is closed for comments.