CitySDK API Node Wrapper

A node package based on the public API Library via http://uscensusbureau.github.io/citysdk/

This fork adds:

• 2015 data
• 1990, and 2010 decennial data
• caching and performance improvements for FIPS/area resolution
• better error handling/recovery from bad census server responses (they mix json and strings in responses, and sometimes their server is down altogether)

Super simple to use

The Node CitySDK Wrapper is designed to be the simplest way possible to make calls to the Census CitySDK API from a node-based project

Changes to the original CitySDK

• Removal of jquery library (uses npm request module instead of $.ajax calls, replaces $.grep with _.filter(), replaces $.inArray with native .indexOf(), uses V8 Engine's native JSON.parse() etc)
• Replaced externally terraformer.io library with its corresponding node package https://github.com/Esri/Terraformer
• Restructed for server based operation instead of client-side (ie. made appropriate changes for instances of window.[])

Getting Started

Install via NPM

npm install git://github.com/chadhuber/citysdk-node.git

Inside your Node.js project

var census = require('citysdk')(YOUR_CENSUS_API_KEY);

nb. Request your Census API Key at http://api.census.gov/data/key_signup.html

Types of Requests

There are two basic types of requests, apiRequest() which retrieves data based on the location and variables you request and geoRequest() which will respond with the data in GEOJSON format including the bounding box coordinates data for creating maps

Request Format

Both requests have the same basic format:

census.apiRequest(request, callback);

census.geoRequest(request, callback);

Arguments

• request - The request object, see more on this below
• callback(response) - A callback which is called when the request is completed with response object

Request Object

Location Options

To specify a location, you must use lat and lng, or zip, or state. At least one of these must be specified.

• lat [int] - The latitude of the requested location (North). Also supported: latitude, y
• lng [int] - The longitude of the requested location (East). Also supported: longitude, x
• zip [string] - The 5-digit zip code of the location. Note that USPS zip code areas do not align precisely with Census geographies, so when high accuracy is required it is recommended to use latitude and longitude. Specified as a string because certain zip codes begin with zeroes.
• state [string] - The 2-letter USPS state code. It will be converted into the latitude and longitude of that state's capital.

Level Options

• level [string] - At what level to request the data. These are based on census geographies. Supported options are: blockGroup, tract, county, state, us, and place. Note that the place tag currently only supports incorporated places.
• sublevel [boolean] - Optional Whether or not to return based upon sublevels (Defaults to false)
• container [string] - Optional GeoJSON request only - Specifies a level which serves as a boundary for a GeoJSON request. For instance, if your level is tract and your container is set as place with sublevel enabled, it will return all tracts which fall within or touch that place's geographical boundaries. Supported options are: tract, county, state, place, geometry, and geometry_within. Note that for the geometry and geometry within tags you must specify the containerGeometry. geometry will return any entities that intersect the given geometry (including if they intersect but extend beyond the perimeter) whereas geometry_within will only return entities that are entirely contained within the containerGeometry specified.
• containerGeometry [object] - Optional GeoJSON request only - Specifies the bounding geometry for a GeoJSON request. The format of this data should be ArcGIS ESRI JSON. You can convert GeoJSON into ESRI using the GEOtoESRI() function. The boundary can be any arbitrary closed region or regions.

Data Options

• api [string] - Optional Specifies the API to use. Supported options are: acs1, acs3, and acs5. (Defaults to acs5)
• year [int] Optional - Specifies the year of the API to use. Supported years per API vary, please see the acsyears object of the Census module for details (Defaults to 2014).
• variables [array] Optional - An array of strings specifying which variables to query. One can specify an aliased variable (see variable aliases) or a specific ACS variable code (e.g. B01003_001E). If this array is not specified, the SDK will simply geocode the location into Census FIPS codes. A list of all ACS variables is available via the getACSVariableDictionary() function.

Request Examples

A simple apiRequest()

// latitude and longitude of Mark Twain's childhood home

var request = {
  "lat": 39.710438,
  "lng": -91.356049,
  "level": "blockGroup",
  "variables": [
      "income",
      "population"
  ]
};

census.apiRequest(request, function(response) {
  console.log(response);
});

This request will have the following response

{ 
  "lat": 39.710438,
  "lng": -91.356049,
  "level": "blockGroup",
  "sublevel": false,
  "variables": [ "income", "population" ],
  "year": 2013,
  "api": "acs5",
  "state": "29",
  "county": "127",
  "tract": "960800",
  "blockGroup": "1",
  "place": "30214",
  "place_name": "Hannibal city",
  "data": [{ 
    "income": "28864",
    "population": "601"
  }] 
}

Variable Aliases

These are simply the most interesting variables, use the function getACSVariableDictionary() for a complete listing (or see https://gist.github.com/chadhuber/e03d4a13e79700a40447 for its output as of 10/11/15)

nb. This documentation is largely based off of the docs available at http://uscensusbureau.github.io/citysdk/guides/censusModule.html

Note: zipcode data is based on http://federalgovernmentzipcodes.us/