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

1.3 The Request Object

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

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.