/citysdk

User-friendly javascript SDK for US Census Bureau data, including simple integrations to facilitate mash-up of other open datasets.

Primary LanguageJavaScriptOtherNOASSERTION

Stories in Ready

CitySDK

This readme is a work in progress. For an overview of the project, please visit https://uscensusbureau.github.io/citysdk

Instructions on using the CitySDK and the current modules can be found in the Examples directory.

Generated jsDocs can be found in the docs directory.

Source code can be found in the js directory.

Intro

Through our City SDK, we are aiming to provide a user-friendly "toolbox" for civic hackers to connect local and national public data. The creation of the SDK came out of the desire to make it easier to use the Census API for common tasks that our developer community asked for. We have been engaging developers around the country for the past two years and have observed how they use the API and have built the most commonly needed functionalities built on top of our API right into the SDK, saving the developer from having to do it herself.

Features

  • Never have to figure out what your FIPS code is again! Just pass in lat/longs, we handle the translation. Only have ZIP codes? No problem, we translate those too.
  • Get values and Census geographic boundaries (currently GeoJSON only: down to ‘block-group’ level) with a SINGLE CALL (whoohoo)!
  • A modular architecture which makes mashing Census data up with third-party data a snap.
  • Pull down Census Bureau geographic boundaries by sending your own custom geography in the request (currently GeoJSON support only, Terraformer.io)
  • A showcase of examples to help you get started.
  • We’ve provided a starting list of aliases for some of our most popular variables (most aliases are in the American Community Survey [ACS5])
  • More coming soon! (you may also add to our issues using the #user stories label to make feature requests)

Getting Started

CitySdk is available as an API and SDK. If you want to use the API, then read the API documentation.

To use the JavaScript SDK, you'll need to add four dependencies:

  1. JQuery
  2. ES6 Promise Polyfill
  3. Terraformer
  4. Terraformer ArcGIS Parser

Make sure the <script> tag for CitySdk is the last one.

<script src="https://www.promisejs.org/polyfills/promise-6.1.0.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script>
<script src="https://cdn-geoweb.s3.amazonaws.com/terraformer/1.0.5/terraformer.min.js"></script>
<script src="https://cdn-geoweb.s3.amazonaws.com/terraformer-arcgis-parser/1.0.4/terraformer-arcgis-parser.min.js"></script>
<script src="https://s3.amazonaws.com/citysdk/releases/0.2.0/citysdk.js"></script>

Once you have all that in place you can start using CitySdk:

<script>
    let request = {
        "zip": "21701",
        "variables": ["income", "population"],
        "level": "county",
        "sublevel": true,
        "state": "MD",
        "container": "state"
    };
    
    let data;
    
    CitySdk.request(request).then((response) => doSomethingWithData(response));
    
    function doSomethingWithData(data) {
        // Do something
    }
</script>