This doc explains the two approaches offered by the CitySDK:

1. Node API. Supports any language of choice or cURL to retrieve data.

2. Client-side Javascript library. Used for client-side apps (running in the browser).

Both methods require a Census API key. If you do not have an API key, you may request one here.

1. Node API

Once you have acquired an API key, it needs to be included in the basic auth header of every request.

Authorization: Basic <your_api_key>

1.1 Example with cURL

curl --user yourApiKey: http://citysdk.commerce.gov

Note: leave the password field empty.

1.2 Endpoints

Base URL: http://citysdk.commerce.gov

Path Method Request Data Description
/ POST JSON Request object Evaluates request and returns either GeoJSON data or GeoJSON with Census data
/alias-to-variable GET Comma separated aliases. Example: ?aliases=income,population Returns a map of alias -> variable for the given parameter values
/variable-to-alias GET Comma separated variables. Example: ?variables=P0010001,P0110022 Returns a map of variable -> alias for the given parameter values

1.3 The Request Object

The request object you send using the POST method is just JSON.

Property Type Supported Values Description
lat Number Example: 34.8994 The latitude of the requested location (North). Also supported: latitude, y
lng Number Example: 62.8995 The longitude of the requested location (East). Also supported: longitude, x
zip String Example: "20902" 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 Example: "MD" The 2-letter USPS state code. It will be converted into the latitude and longitude of that state's capital.
level String "blockGroup", "tract", "county", "state", "us", "place" At what level to request the data. These are based on census geographies.
sublevel Boolean true or false See sublevel requests for more information. Defaults to false.
container String "tract", "county", "state", "place", "geometry", "geometry_within" 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 the SDK will return all tracts which fall within or touch that place's geographical boundaries. 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 {} 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 Census module's GEOtoESRI() method. The boundary can be any arbitrary closed region or regions.
api String Example: "acs5" Specifies the API to use.
year Number Example: 2010 Specifies the year of the API to use. Defaults to the most recent year.
variables Array [] 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 on the Census's developer portal or via the SDK's getACSVariableDictionary method.

1.4 Examples

Requesting GeoJSON and Census data using Python

import requests
from requests.auth import HTTPBasicAuth

apikey = "your_api_key"
request_url = "http://citysdk.commerce.gov"

request_obj = {
  'zip': '21401',
  'state': 'MD',
  'level': 'state',
  'sublevel': False,
  'api': 'acs5',
  'year': 2010,
  'variables': ['income', 'population']
}

response = requests.post(request_url, auth=HTTPBasicAuth(apikey, None), json=request_obj)

print response.json()

Result data

{
  "blockGroup": "2",
  "zip": "21401",
  "level": "state",
  "sublevel": false,
  "variables": [
    "NAME",
    "B19013_001E",
    "B01003_001E"
  ],
  "tract": "706101",
  "county": "003",
  "state": "24",
  "api": "acs5",
  "place": "01600",
  "year": 2010,
  "lat": 38.9898034,
  "lng": -76.5501227,
  "data": [
    {
      "B01003_001E": "5696423",
      "NAME": "Maryland",
      "B19013_001E": "70647"
    }
  ],
  "geographyValidForAPI": true,
  "place_name": "Annapolis city"
}

Requesting GeoJSON and Census data using cURL

curl --user yourApiKey: -X POST \
-H "Content-Type: application/json" \
-d '{"lat": 38.9047, "lng": -77.0164, "level": "state", "variables": ["income", "population"]}' \
http://citysdk.commerce.gov/

Result data

{
  "lat": 38.9047,
  "lng": -77.0164,
  "level": "state",
  "variables": [
    "NAME",
    "B19013_001E",
    "B01003_001E"
  ],
  "api": "acs5",
  "year": "2014",
  "sublevel": false,
  "state": "11",
  "county": "001",
  "tract": "004701",
  "blockGroup": "2",
  "place": "50000",
  "place_name": "Washington city",
  "geographyValidForAPI": true,
  "data": [
    {
      "NAME": "District of Columbia",
      "B19013_001E": "69235",
      "B01003_001E": "633736"
    }
  ]
}

2. Client-side Javascript library

For client-side only apps, a Javascript library is provided that is expanded by modules which call on various APIs. Each module essentially adds a new data source for scripting to consume. The core library (citysdk.js) includes some basic utility functions that return coordinates for state capitals, etc.

2.1 Add the Library

Add the script libraries to the page. You will need the CitySDK core and then any modules you wish to use. This example will use the Census Module.

<script src="https://cdn.rawgit.com/uscensusbureau/citysdk/gh-pages/static/js/citysdk/core/citysdk.js"></script>
<script src="https://cdn.rawgit.com/uscensusbureau/citysdk/gh-pages/static/js/citysdk/modules/census.citysdk.js"></script>

Note: jQuery is also a required.

2.2 Enable the Library(s)

Make sure you have a Census API key, you may request one here.

<script>
        census = new CensusModule("API-KEY"); //Create and activate an instance of the module
</script>

2.3 Create the Request

Define Location

The location can be defined by coordinates (latitude/longiture), state, zipcode, or address. Generally coordinate points are optimal and fastest.

Select Variables

The variables determine what data points are returned by the request. For census modules many of the most common variables have been aliased for easier use. You can use either the aliases or the variable names.

Choose Geographic Grouping / Level

Choose what geographic level of data desired. For example, selecting “state” along with the coordinates of Richmond, VA will return data for the state of Virginia. Optionally you can include the sublevel which will include the next unit down (in the previous example, selecting sublevel when requesting a state will also include county).

The Completed Request

<script>
    var request = {
        "level": "state",
        "state": "AK",
        "sublevel": true,
        "variables": [
            "B24124_407E",
            "age",
            "commute_time",
            "commute_time_carpool",
            "commute_time_other"
        ]
    }
</script>

2.4 Submit the Request

Make the request and use a callback to utilize the response.

<script>

    //Create a callback function to use the data returned
     var callback = function(response) {
        // Do something with the response
     };

     // Make the request
     census.geoRequest(request, callback);
     census.apiRequest(request, callback);
</script>

2.5 See It In Action

Go to Guides >> Interactive Query Builder to explore different datasets, practice making requests, map the data, or download as a CSV.