CitySDK

https://uscensusbureau.github.io/citysdk/
Admin
CitySDK is a JavaScript library that simplifies access to US Census Bureau data through streamlined...
Tokens:21,590
Snippets:212
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete Mapbox GL JS setup with CitySDK integration

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

This comprehensive example initializes a Mapbox map, adds a vector tile source and fill layer, queries CitySDK data, binds it to the map using `setFeatureState`, styles the layer with a choropleth, and adds interactive popups.

```javascript
map.on("load", () => {
  //setup source and layer
  map.addSource("counties", {
    type: "vector",
    tiles: ["https://gis.data.census.gov/arcgis/rest/services/Hosted/VT_2019_050_00_PY_D1/VectorTileServer/tile/{z}/{y}/{x}.pbf"],
    promoteId: "GEOID" // promote field to be used as a foreign key
  })

  map.addLayer({
    id: "counties-fill",
    type: "fill",
    source: "counties",
    "source-layer": "County",
    paint: {
      "fill-opacity": 0.8,
      "fill-color": "grey"
    }
  });

  //query using citysdk
  census(
    {
      vintage: 2019,
      geoHierarchy: {
        county: "*"
      },
      sourcePath: ["acs", "acs5"],
      values: ["NAME", "B08134_001E", "B08134_011E"]
    },
    (error, response) => {
      //bind data to source layer
      response.forEach((row) => {
        const GEOID = row.state + row.county
        map.setFeatureState({
          source: "counties",
          sourceLayer: "County",
          //promote field to be used as the primary key
          id: GEOID
        }, {
          //promote fields to be styled or interacted with
          name: row.NAME,
          car_truck_van_count: row.B08134_011E,
          total : row.B08134_001E,
          value: row.B08134_011E / row.B08134_001E
        })
      })

      //update paint to display choropleth
      map.setPaintProperty("counties-fill", "fill-color", [
        "interpolate",
        ["linear"],
        ["feature-state", "value"],
        0.3,
        "#fef0d9",
        0.6,
        "#fdcc8a",
        0.8,
        "#fc8d59",
        0.9,
        "#e34a33",
        1,
        "#b30000"
      ]);

      map.on("click", "counties-fill", e => {
        const features = map.queryRenderedFeatures(e.point, { layers: ["counties-fill"] });

        if (features.length > 0) {
          const { state, properties } = features[0]

          const percent = `${(state.value * 100).toFixed(2)}%`

          new mapboxgl.Popup()
            .setLngLat(e.lngLat)
            .setHTML(`Percent of people in <strong>${state.name}</strong> that travel to work using a car/truck/van: ${percent}`)
            .addTo(map);
        }
      });
    })
});

```

--------------------------------

### Node.js Quick Start with CitySDK

Source: https://uscensusbureau.github.io/citysdk

Shows how to install and use CitySDK in a Node.js application to fetch ACS5 2017 population data for California counties.

```javascript
import census from "citysdk"

//get the ACS5 2017 population for all counties in the California
census(
  {
    vintage: '2017',
    geoHierarchy: {
      state: "06",
      county: '*',
    },
    sourcePath: ['acs','acs5'],
    values: ['B00001_001E'],
  },
  (err, res) => console.log(res) // [{"B00001_001E": 889,"state": "06","county": "049"}, ...
```

--------------------------------

### CitySDK Query Examples with Various Arguments

Source: https://uscensusbureau.github.io/citysdk/docs

A collection of examples demonstrating different ways to configure CitySDK queries, including specifying vintage, geographic hierarchies with coordinates, source paths, values, and predicates for filtering.

```json
// Call the WMS only
{
  "vintage": 2014,
  "geoHierarchy": { "state": { "lat": 28.2639, "lng": -80.7214 }, "county": '*' }
}

```

```json
// Getting the stats for a single county filtering out any county with population under 100,000
{
  "vintage": 2016,
  "geoHierarchy": { "county": { "lat": 28.2639, "lng": -80.7214 } },
  "sourcePath": [ "acs", "acs5" ],
  "values": [ "B01001_001E" ]
  "predicates": { "B00001_001E": "0:100000" },
}

```

```json
// strings are valid as vintages as well
{
  "vintage": "2015",
  "geoHierarchy": { "county": { "lat": 28.2639, "lng": -80.7214 } },
  "sourcePath": [ "cbp" ],
  "values": [ "ESTAB" ]
}

```

```json
// Just geojson for all the counties within a state located by a given coordinate
{
  "vintage": 2014,
  "geoHierarchy": { "state": { "lat": 28.2639, "lng": -80.7214 }, "county": "*" },
  "geoResolution": "500k"
}

```

```json
// For large request expect to have to increase `node --max-old-space-size=4096`
{
  "vintage": 2016,
  "sourcePath": [ "acs", "acs5" ],
  "values": [ "B25001_001E" ],
  "geoHierarchy": { "zip-code-tabulation-area": "*" },
  "geoResolution": "500k"
}

```

--------------------------------

### Install CitySDK via NPM

Source: https://uscensusbureau.github.io/citysdk/guides/intro/1

Use NPM to install the CitySDK package for use in your project.

```bash
npm install citysdk
```

--------------------------------

### Browser Quick Start with CitySDK

Source: https://uscensusbureau.github.io/citysdk

Demonstrates how to include CitySDK in an HTML file and make a basic data request for US 2017 data.

```html
<script src="./citysdk.js"></script>
<script>
//Web developers in the US 2017
census(
  {
  vintage: '2017',
  geoHierarchy: {
    us: '*',
  },
  sourcePath: ['acs','acs5',],
  values: ['B24121_065E'],
  }
  (err, res) => console.log(res) // [{"B24121_065E": 62792,"us": "1"}]
)
</script>
```

--------------------------------

### Example Census Data Query

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

This object shows an example query structure for fetching time-series international trade data by NAICS code.

```javascript
//Example query for Jan 2013, the earliest month for this datset
{
    vintage: "timeseries",
    sourcePath: ["intltrade", "exports", "naics"],
    values: ["AIR_WGT_MO", "CNT_WGT_MO", "VES_WGT_MO"],
    predicates: { time: "2013-01", NAICS: "111" },
}
```

--------------------------------

### Import CitySDK in JavaScript

Source: https://uscensusbureau.github.io/citysdk/guides/intro/1

Import the CitySDK library into your JavaScript files after installing it via NPM.

```javascript
import census from "citysdk"
```

--------------------------------

### Geocoding Example: Request a single geographic area by coordinate

Source: https://uscensusbureau.github.io/citysdk/docs

This example demonstrates how to use the `citysdk` function to geocode a specific geographic area using latitude and longitude coordinates. The function automatically determines the appropriate GEOID based on the provided coordinates and the `geoHierarchy`.

```APIDOC
## Geocoding (latitude/longitude -> FIPS code)

### Example: Request a single geographic area by coordinate
RETURN TYPE: `JSON`
You may pass a `{"lat" : <float>, "lng" : <float>}` object as the first and _only_ value for the `geoHierarchy` key:
```javascript
import census from 'citysdk'

census(
    {
        vintage: 2015, // required
        geoHierarchy: {
            // required
            county: {
                lat: 28.2639,
                lng: -80.7214,
            },
        },
    },
    (err, res) => console.log(res)
)

// result -> {"vintage":"2015","geoHierarchy":{"state":"12","county":"009"}}

```

Notice how the function prepends an additional geographic component (`"state" : "12"`) to the options object. In order to fully qualify the geographic area (GEOID) associated with the county, the state is needed. In this example the fully qualified GEOID would be `12009` with the first two digits (`12`) qualifying the state and `009` qualifying the county within that state. This appropriate geographic hierarchy creation is handled by the function for you.
```

--------------------------------

### Setup Map with D3.js and GeoJSON

Source: https://uscensusbureau.github.io/citysdk/examples/d3-map

This snippet sets up the basic SVG, projection, and fetches data to generate a map. It requires D3.js and CitySDK. The data is processed to create a color scale based on specific values, and then used to fill map paths.

```javascript
const width = 800,
  height = 600;
const map = d3
  .select("svg")
  .attr("width", width)
  .attr("height", height);

const projection = d3
  .geoAlbersUsa()
  .scale(width)
  .translate([width / 2, height / 2]);
const path = d3.geoPath(projection);

censusPromise({
  vintage: 2019,
  geoHierarchy: {
    county: "*"
  },
  sourcePath: ["acs", "acs5"],
  values: ["B17001_001E", "B17001_002E"],
  geoResolution: "20m"
}).then(data => {
  const extent = d3.extent(
    data.features.map(
      d => d.properties["B17001_002E"] / d.properties["B17001_001E"]
    )
  );
  const colorScale = d3
    .scaleQuantile()
    .domain(extent)
    .range(d3.schemeBlues[7]);

  map
    .append("g")
    .selectAll("path")
    .data(data.features)
    .enter()
    .append("path")
    .attr("d", path)
    .attr("fill", d => {
      return colorScale(
        d.properties["B17001_002E"] / d.properties["B17001_001E"]
      );
    });
});
```

--------------------------------

### Query All US Counties with Vintage 2017

Source: https://uscensusbureau.github.io/citysdk/docs

This example demonstrates querying for all counties in the US for the 2017 vintage. Be aware that for vintage 2017, counties are stored at the national level, so this query may return all US counties.

```javascript
census(
    {
        vintage: '2017',
        geoHierarchy: {
            state: '51',
            county: '*',
        },
        geoResolution: '500k', // required
    },
    (err, res) => console.log(res)
)

```

--------------------------------

### Complete CitySDK Query and Example Result

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

A fully constructed CitySDK query object for population data and a sample of the expected JSON result format.

```json
{
    "sourcePath" : ["acs","acs1","profile"],  // source (survey, ACS 1-year profile estimate)
    "vintage" : 2017,               // source (year, 2017)
    "values" : ["NAME","DP05_0001E","DP05_0002E", "DP05_0003E"],     // metric (column for total count, male, and female popluation)
    "geoHierarchy" : {              // geographic entity (grouped by state)
      "state" : "*"
    }
}

//result
[{
    "NAME": "Alabama",
    "DP05_0001E": 4874747,
    "DP05_0002E": 2359896,
    "DP05_0003E": 2514851,
    "state": "01"
  },
  {
    "NAME": "Alaska",
    "DP05_0001E": 739795,
    "DP05_0002E": 385776,
    "DP05_0003E": 354019,
    "state": "02"
},
  ...
}]

```

--------------------------------

### SVG Element Setup

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Add an SVG element with the ID 'chart' to your HTML body where the line chart will be rendered.

```html
<svg id="chart"></svg>
```

--------------------------------

### Setup SVG Canvas and Axes

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Initializes the SVG element for the chart and appends group elements for the x and y axes. This provides the base structure for rendering the chart.

```javascript
//setup svg
const svg = d3
  .select("#chart")
  .attr("width", width + margin.left + margin.right)
  .attr("height", height + margin.top + margin.bottom)
  .append("g")
  .attr("transform", "translate(" + margin.left + "," + margin.top + ")");

//setup x and y axis
svg
  .append("g")
  .attr("class", "x axis")
  .attr("transform", "translate(0," + height + ")")
  .call(d3.axisBottom(xScale));

svg
  .append("g")
  .attr("class", "y axis")
  .call(d3.axisLeft(yScale));
```

--------------------------------

### Get All Counties Data

Source: https://uscensusbureau.github.io/citysdk/examples

Fetches data for all counties using specified vintage, geoHierarchy, sourcePath, and values. Requires a statsKey and geoResolution.

```javascript
census({
  vintage: "2017",
  geoHierarchy: {
    county: "*"
  },
  sourcePath: ["acs", "acs5"],
  values: ["B19083_001E"], // GINI index
  statsKey: "<your key here>",
  geoResolution: "500k"
});

```

--------------------------------

### CitySDK Query with Specific Metrics

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

An example of a CitySDK query object populated with specific source, vintage, and metric values, including 'NAME' for geographic identification.

```json
{
    "sourcePath" : ["acs","acs1","profile"],
    "vintage" : 2017,
    "values" : ["NAME","DP05_0001E","DP05_0002E", "DP05_0003E"], // metric (column for total count, male, and female popluation)
}

```

--------------------------------

### Example CitySDK Query for Exports Data

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Demonstrates a sample query structure for retrieving monthly U.S. exports data by state and NAICS code using the CitySDK. This query specifies vintage, data source, values, and filtering predicates.

```json
{
    "vintage": "timeseries",
    "sourcePath": [
        "intltrade",
        "exports",
        "statenaics"
    ],
    "values": ["AIR_WGT_MO","CNT_WGT_MO","VES_WGT_MO"],
    "predicates":
    {
        "time": "2015-03",
        "NAICS": "212",
        "STATE": "MD"
    }
}
```

--------------------------------

### Setup Chart Margins and Dimensions

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Defines the margin, width, and height for the D3.js chart, utilizing the window's dimensions.

```javascript
const margin = { top: 50, right: 50, bottom: 50, left: 100 },
  width = window.innerWidth - margin.left - margin.right, // Use the window's width
  height = window.innerHeight - margin.top - margin.bottom; // Use the window's height
```

--------------------------------

### Retrieve All ZCTAs with GINI Index (ACS)

Source: https://uscensusbureau.github.io/citysdk/docs

This example demonstrates fetching the GINI index for all Zip Code Tabulation Areas (ZCTAs). Due to the large size of this request, it is recommended to run this on Node.js with increased memory allocation (`node --max-old-space-size=4096`) and consider pre-processing data for static serving.

```javascript
census({
    vintage: '2017',
    geoHierarchy: {
        'zip-code-tabulation-area': '*',
    },
    sourcePath: ['acs', 'acs5'],
    values: ['B19083_001E'], // GINI index
    statsKey: '<your key here>',
    geoResolution: '500k',
})

```

--------------------------------

### Query counties within a zipcode (demonstrates hierarchy error)

Source: https://uscensusbureau.github.io/citysdk/guides/intro/3

This example attempts to query for counties within a specific zipcode. It demonstrates an error due to an unsupported geography hierarchy, as counties do not perfectly nest within zipcodes.

```json
{
	"geoHierarchy": {
		"zip code tabulation area": 10010,
		"county": "*"
	},
	 "values" : ["B00001_001E"],
	 "vintage" : 2017,
	"sourcePath" : ["acs","acs5"]
}
```

--------------------------------

### Get 'values' by ID (with key)

Source: https://uscensusbureau.github.io/citysdk/docs

Retrieves specific data values for a given geographic hierarchy and source path. Requires a statsKey for more than 500 calls per day.

```APIDOC
## Get 'values' by ID (with key)

### Description
Retrieves specific data values for a given geographic hierarchy and source path. Requires a statsKey for more than 500 calls per day.

### Method
`census()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **vintage** (integer) - Required - The vintage year for the data.
- **geoHierarchy** (object) - Required - Defines the geographic scope.
  - **county** (object) - Required - Contains latitude and longitude.
    - **lat** (number) - Required
    - **lng** (number) - Required
- **sourcePath** (array of strings) - Required - Specifies the data source (e.g., ['cbp']).
- **values** (array of strings) - Required - The specific data fields to retrieve (e.g., ['ESTAB']).
- **statsKey** (string) - Optional - API key for increased call limits.

### Request Example
```javascript
census(
    {
        vintage: 2015, 
        geoHierarchy: {
            county: {
                lat: 28.2639,
                lng: -80.7214,
            },
        },
        sourcePath: ['cbp'], 
        values: ['ESTAB'], 
        statsKey: '<your key here>', 
    },
    (err, res) => console.log(res)
)
```

### Response
#### Success Response (200)
- **ESTAB** (integer) - Number of establishments.
- **state** (string) - State FIPS code.
- **county** (string) - County FIPS code.

#### Response Example
```json
[{"ESTAB":13648,"state":"12","county":"009"}]
```
```

--------------------------------

### Get Timeseries Data

Source: https://uscensusbureau.github.io/citysdk/docs

Retrieve timeseries data for statistics only; mapping is unsupported. Often relies on the `predicates` option for filtering by time or category.

```javascript
census(
    {
        vintage: 'timeseries', // required
        geoHierarchy: {
            // required
            us: '*',
        },
        sourcePath: ['asm', 'industry'], // required
        values: ['EMP', 'NAICS_TTL', 'GEO_TTL'],
        predicates: { time: '2016', NAICS: '31-33' },
    },
    (err, res) => console.log(res)
)

/* result:
[{"EMP": 11112764, 
  "NAICS_TTL": "Manufacturing", 
  "GEO_TTL": "United States", 
  "time": "2016", 
  "NAICS": "31-33", 
  "us":"1"}]
*/
```

--------------------------------

### Get Values by ID with Key

Source: https://uscensusbureau.github.io/citysdk/docs

Retrieve specific statistical values for a given geographic hierarchy and vintage. Requires a `statsKey` for more than 500 calls per day.

```javascript
census(
    {
        vintage: 2015, // required
        geoHierarchy: {
            // required
            county: {
                lat: 28.2639,
                lng: -80.7214,
            },
        },
        sourcePath: ['cbp'], // required
        values: ['ESTAB'], // required
        statsKey: '<your key here>', // required for > 500 calls per day
    },
    (err, res) => console.log(res)
)

// result -> [{"ESTAB":13648,"state":"12","county":"009"}]
```

--------------------------------

### Get 'timeseries' data (Statistics Only)

Source: https://uscensusbureau.github.io/citysdk/docs

Retrieves timeseries data for statistics only. Mapping timeseries data is unsupported. Many timeseries products rely heavily on the 'predicates' option.

```APIDOC
## Timeseries data (Statistics Only)

### Description
Retrieves timeseries data for statistics only. Mapping timeseries data is unsupported. Many timeseries products rely heavily on the 'predicates' option.

### Method
`census()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **vintage** (string) - Required - Set to 'timeseries'.
- **geoHierarchy** (object) - Required - Defines the geographic scope.
  - **us** (string) - Required - Wildcard '*' for United States.
- **sourcePath** (array of strings) - Required - Specifies the data source (e.g., ['asm', 'industry']).
- **values** (array of strings) - Required - The specific data fields to retrieve (e.g., ['EMP', 'NAICS_TTL', 'GEO_TTL']).
- **predicates** (object) - Optional - Criteria for filtering data.
  - **time** (string) - Example predicate for the year (e.g., '2016').
  - **NAICS** (string) - Example predicate for industry code (e.g., '31-33').

### Request Example
```javascript
census(
    {
        vintage: 'timeseries', 
        geoHierarchy: {
            us: '*', 
        },
        sourcePath: ['asm', 'industry'], 
        values: ['EMP', 'NAICS_TTL', 'GEO_TTL'],
        predicates: { time: '2016', NAICS: '31-33' },
    },
    (err, res) => console.log(res)
)
```

### Response
#### Success Response (200)
- **EMP** (integer) - Employment count.
- **NAICS_TTL** (string) - Industry title.
- **GEO_TTL** (string) - Geographic title.
- **time** (string) - Year of the data.
- **NAICS** (string) - NAICS code.
- **us** (string) - Geographic identifier.

#### Response Example
```json
[{"EMP": 11112764, 
  "NAICS_TTL": "Manufacturing", 
  "GEO_TTL": "United States", 
  "time": "2016", 
  "NAICS": "31-33", 
  "us":"1"}]
```
```

--------------------------------

### Initialize Leaflet Map

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet-choropleth

Set up the Leaflet map instance, center it on a specific location, and add a tile layer for the base map.

```javascript
var map = L.map("map").setView([28.466944, -82.498148], 7);

L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

```

--------------------------------

### Import Libraries and Styles

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Include Mapbox GL JS, its CSS, and CitySDK.js in the head of your HTML document. You can download citysdk.js or build it using browserify.

```html
<script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.2.0/mapbox-gl.js"></script>
<link
  href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.2.0/mapbox-gl.css"
  rel="stylesheet"
/>
<script src="./citysdk.js"></script>

```

--------------------------------

### Initialize Mapbox Map

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Initialize the Mapbox map in a script tag after the map div. Replace '<your access token here>' with your actual Mapbox access token.

```javascript
mapboxgl.accessToken = "<your access token here>";
var map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v11",
  center: { lat: 37.0902, lng: -95.7129 },
  zoom: 3
});

```

--------------------------------

### Import Libraries and Styles

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Include these script tags in the head of your HTML to import D3.js and CitySDK.js.

```html
<script src="https://d3js.org/d3.v5.min.js"></script>
<script src="/citysdk/assets/citysdk.js"></script>
```

--------------------------------

### Initialize Leaflet Map

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet

Initialize a Leaflet map on the 'map' div, set its center and zoom level, and add OpenStreetMap as a tile layer.

```javascript
var map = L.map('map').setView([31.6623, -99.0306], 6);

L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

```

--------------------------------

### Get specific tract ID using latitude and longitude

Source: https://uscensusbureau.github.io/citysdk/guides/intro/3

This snippet retrieves only the geographic hierarchy details for a specific tract using latitude and longitude, without requesting specific data values. It's useful for identifying the exact tract associated with a coordinate.

```json
{
   "vintage" : 2017,
    "geoHierarchy": {
	"tract": {
	   "lat": 39.736667,
	    "lng": -104.989179
	}
   }
}
```

--------------------------------

### Add Vector Tiles Source and Layer

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

On map load, add a vector tile source for counties and a fill layer. The 'promoteId' is set to 'GEOID' to link with CitySDK query results.

```javascript
map.on("load", function() {
  map.addSource("counties", {
    type: "vector",
    tiles: ["https://gis.data.census.gov/arcgis/rest/services/Hosted/VT_2019_050_00_PY_D1/VectorTileServer/tile/{z}/{y}/{x}.pbf"],
    promoteId: "GEOID" // promote field to be used as a foreign key
  })

  map.addLayer({
    id: "counties-fill",
    type: "fill",
    source: "counties",
    "source-layer": "County",
    paint: {
      "fill-opacity": 0.8,
      "fill-color": "grey"
    }
  });
});

```

--------------------------------

### Query Structure Template

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

A template for constructing a CitySDK query, showing placeholders for source, vintage, metrics, and geographic hierarchy.

```json
{
  "sourcePath" : [""] // source (survey)
  "vintage" : // source (year)
  "values" : [],   // metric (columns)
  "geoHierarchy" : {  // geographic entity (grouped by state)
    "state" : "*"
    }
}

```

--------------------------------

### Constructing a CitySDK Query

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

Define the source, vintage, desired metrics, and geographic hierarchy for your data request. The 'sourcePath' specifies the survey and estimate type, 'vintage' is the year, 'values' are the specific data columns, and 'geoHierarchy' defines the geographic level.

```json
{
  "sourcePath" : ["acs","acs1","subject"], // source (survey, ACS 1-year subject estimate)
  "vintage" : 2017,                         // source (year, 2017)
  "values" : ["NAME","S2801_C01_001E","S2801_C01_002E" ], // metric (column for total households, one or more types of computing devices)
  "geoHierarchy" : {  // geographic entity (grouped by state)
    "state" : "*"
  }
}
```

--------------------------------

### Source and Vintage Extraction from URL

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

Demonstrates how to extract the 'sourcePath' and 'vintage' from a Census API URL to populate the query object.

```json
{
    "sourcePath" : ["acs","acs1","profile"],  // source (survey, ACS 1-year profile estimate)
    "vintage" : 2017,               // source (year, 2017)
}

```

--------------------------------

### Map Container and Styling

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet

Define a div element with an ID 'map' and apply CSS to set its height and width for the map display.

```html
<style>
  #map {
    height: 600px;
    width: 600px;
  }
</style>
<div id="map"></div>

```

--------------------------------

### Include CitySDK via Script Tag

Source: https://uscensusbureau.github.io/citysdk/guides/intro/1

Add this script tag to your HTML's head section to include the CitySDK library directly.

```html
<script src="./citysdk.js"></script>
```

--------------------------------

### Load GeoJSON County Data with Interactive Popups

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Loads county data as GeoJSON and adds it to the map as a fill layer. Includes an event listener for clicks to display a popup with county name and GINI value.

```javascript
map.on("load", function() {
  census(
    {
      vintage: 2017,
      geoHierarchy: {
        county: "*"
      },
      geoResolution: "5m",
      sourcePath: ["acs", "acs5"],
      values: ["NAME", "B19083_001E"]
    },
    function(error, response) {
      map.addLayer({
        id: "counties",
        type: "fill",
        source: {
          type: "geojson",
          data: response
        },
        paint: {
          "fill-opacity": 0.8,
          "fill-color": [
            "interpolate",
            ["linear"],
            ["get", "B19083_001E"],
            0.2,
            "#ffffb2",
            0.4,
            "#fecc5c",
            0.6,
            "#fd8d3c",
            0.8,
            "#f03b20",
            1,
            "#bd0026"
          ]
        }
      });

      map.on("click", "counties", function(e) {
        var coordinates = e.lngLat;
        //look up GINI value
        var properties = e.features[0].properties;

        new mapboxgl.Popup()
          .setLngLat(coordinates)
          .setHTML(
            "GINI value for " + properties.NAME + ": " + properties.B19083_001E
          )
          .addTo(map);
      });
    }
  );
});

```

--------------------------------

### Basic Query Structure for CitySDK

Source: https://uscensusbureau.github.io/citysdk/guides/intro/2

This object defines the core parameters for a CitySDK query, including the data source, vintage (year), desired metrics (values), and geographic hierarchy.

```json
{
    "sourcePath" : ["acs","acs1"],  // source (survey, ACS 1-year estimate)
    "vintage" : 2017,               // source (year, 2017)
    "values" : ["B00001_001E"],     // metric (column for population count)
    "geoHierarchy" : {              // geographic entity (grouped by state)
      "state" : "*"
    }
}

```

--------------------------------

### CitySDK Query Execution

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Execute a CitySDK query with a callback function to handle the response. The callback receives error and response objects.

```javascript
census(
  {
    sourcePath: ["acs", "acs1", "subject"],
    vintage: 2017,
    values: ["NAME", "S2504_C01_027E", "S2504_C01_001E"],
    geoHierarchy: {
      state: "36",
      county: "*"
    }
  },
  function(error, response) {
    console.log(response);
  }
);
```

--------------------------------

### CitySDK v2.3 ESM Import vs. v2.2 CommonJS Require

Source: https://uscensusbureau.github.io/citysdk/docs

Demonstrates the change in import syntax from CommonJS (require) in versions prior to 2.3.0 to ESM (import) in version 2.3.0 and above.

```javascript
// 2.2.x or below
const census = require('citysdk')
// 2.3.x or above
import census from 'citysdk'

```

--------------------------------

### Map Container and Styles

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Define a div with the id 'map' in the body to serve as the map container and apply basic styles to ensure it fills the page.

```html
<style>
  body {
    margin: 0;
    padding: 0;
  }
  #map {
    position: absolute;
    top: 0;
    bottom: 0;
    width: 100%;
  }
</style>
<div id="map"></div>

```

--------------------------------

### Retrieve All Counties with GINI Index (ACS)

Source: https://uscensusbureau.github.io/citysdk/docs

This snippet shows how to fetch the GINI index for all counties using the ACS 5-year estimates. It specifies the source path and the desired statistic.

```javascript
census({
    vintage: '2017',
    geoHierarchy: {
        county: '*',
    },
    sourcePath: ['acs', 'acs5'],
    values: ['B19083_001E'], // GINI index
    statsKey: '<your key here>',
    geoResolution: '500k',
})

```

--------------------------------

### GeoJSON Output Configuration

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Configure CitySDK to return data in GeoJSON format by specifying the geoResolution. This is useful for mapping data.

```json
{
  "sourcePath" : ["acs","acs1","subject"],
  "vintage" : 2017,
  "values" : ["NAME","S2504_C01_027E","S2504_C01_001E"],
	"geoHierarchy": {
	    "state": "36",
	    "county": "*"
	},
	"geoResolution": "20m"
}
```

--------------------------------

### CitySDK Query Construction

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Construct a CitySDK query to retrieve specific data values for a given vintage and geographic hierarchy. Includes 'NAME' for descriptive county names.

```json
{
  "sourcePath" : ["acs","acs1","subject"],
  "vintage" : 2017,
  "values" : ["NAME","S2504_C01_027E","S2504_C01_001E"],
	"geoHierarchy": {
	    "state": "36",
	    "county": "*"
	}
}
```

--------------------------------

### citysdk Function Usage

Source: https://uscensusbureau.github.io/citysdk/docs

The CitySDK library exports a single function that takes an options object and a callback function. The options object configures the data request, and the callback handles the response or errors.

```APIDOC
## The `citysdk` Function

CitySDK exports a single function, which takes two arguments:
  * The first is an options object with a set of key/value pair parameters (See “Parameters” below)
  * The second is a conventional (error, response) node-style callback, which will be called upon completion of the `census` function and applied to the response
```

--------------------------------

### Saving Cartographic GeoJSON locally

Source: https://uscensusbureau.github.io/citysdk/docs

Demonstrates how to retrieve Cartographic Boundary files translated into GeoJSON and save them locally using Node.js's `fs` module.

```APIDOC
## Cartographic GeoJSON

### Description
Retrieves Cartographic Boundary files translated into GeoJSON. Requires specifying `geoResolution`.

### Method
`census()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **vintage** (integer) - Required - The vintage year for the data.
- **geoHierarchy** (object) - Required - Defines the geographic scope.
  - **'metropolitan statistical area/micropolitan statistical area'** (string) - Required - Geographic area type (wildcard '*' can be used).
- **geoResolution** (string) - Required - The resolution of the GeoJSON ('500k', '5m', or '20m').

### Request Example
```javascript
import fs from "fs"

census(
    {
        vintage: 2017,
        geoHierarchy: {
            'metropolitan statistical area/micropolitan statistical area': '*',
        },
        geoResolution: '500k', 
    },
    (err, res) => {
        fs.writeFile('./directory/filename.json', JSON.stringify(res), () => console.log('done'))
    }
)
```

### Response
#### Success Response (200)
- Returns GeoJSON data as a string.

#### Response Example
(GeoJSON string saved to a file)
```

--------------------------------

### Import Libraries and Styles for Leaflet

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet

Include Leaflet CSS and JavaScript files, along with the CitySDK library, in the head of your HTML document.

```html
<link
  rel="stylesheet"
  href="https://unpkg.com/leaflet@1.5.1/dist/leaflet.css"
/>
<script src="https://unpkg.com/leaflet@1.5.1/dist/leaflet.js"></script>
<script src="./citysdk.js"></script>

```

--------------------------------

### GeoHierarchy Configuration (Latitude/Longitude)

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Configure the geographic hierarchy to query data for all counties using a state's latitude and longitude as the base.

```json
{
    "state": {
        "lat":  42.650272,
        "lng":  -73.758381
    },
    "county": "*"
}
```

--------------------------------

### Calculate Percentage of Households with Vehicles

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Process the CitySDK query response to calculate the percentage of households with one or more vehicles available. Assumes response contains 'S2504_C01_001E' (total occupied units) and 'S2504_C01_027E' (units with no vehicle available).

```javascript
function(error, response){
	console.log(response)

	const percentage_households_w_vehicles = response.map(function(county){
		const total_households = county["S2504_C01_001E"];
		const households_wo_vehicles = county["S2504_C01_027E"];

		//subtract to get the total households with vehicles (one or more)
		const households_w_vehicles =    total_households - households_wo_vehicles;

		//get percentage
		const percentage_households_w_vehicles = households_w_vehicles / total_households;

		//return object
		return {
			"percent" : percentage_households_w_vehicles,
			"name" :  county['NAME']
		}
	})

console.log(percentage_households_w_vehicles)
// [
//	{percent: 0.8498759505090863, name: "Albany County, New York"},
//	{percent: 0.41177217575919917, name: "Bronx County, New York"},
//	{percent: 0.8561523586585924, name: "Broome County, New York"},
//	{percent: 0.8784301606922126, name: "Cattaraugus County, New York"},
//...
//]
})
```

--------------------------------

### Render Data to DOM

Source: https://uscensusbureau.github.io/citysdk/guides/intro/4

Dynamically render processed data to the DOM by creating an HTML list of county names and their calculated percentages, sorted by percentage.

```html
<body>
  <div id="container"></div>
</body>
```

```javascript
...
function(error, response){
	...

	//get DOM element
	const container = document.getElementById('container');

	//sort counties by percentages
	const counties_sorted = percentage_households_w_vehicles.sort(function(a,b){
		return a.percent - b.percent;
	});

	//generate list
	const counties_list = counties_sorted.map(function(county){
		return `<li><b>${county.name}</b> : ${county.percent}</li>`
	}).join('')

	//set the innerHTML to the generated list
	container.innerHTML = `<ul>${counties_list}</ul>`;
}
```

--------------------------------

### Add popups on feature click

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Implement click event listeners on a fill layer to query rendered features. Display a Mapbox GL JS popup with details extracted from the feature's state and properties.

```javascript
map.on("click", "counties-fill", e => {
  const features = map.queryRenderedFeatures(e.point, { layers: ["counties-fill"] });

  if (features.length > 0) {
    const { state, properties } = features[0]

    const percent = `${(state.value * 100).toFixed(2)}%`

    new mapboxgl.Popup()
      .setLngLat(e.lngLat)
      .setHTML(`Percent of people in <strong>${state.name}</strong> that travel to work using a car/truck/van: ${percent}`)
      .addTo(map);
  }
});
```

--------------------------------

### Configure D3.js Scales and Date Parsing

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Sets up time and linear scales for the chart axes, including parsing date strings and determining data extents. Use this for mapping data values to pixel coordinates.

```javascript
const dateFormat = d3.timeParse("%Y-%m");
const xScale = d3
  .scaleTime()
  .domain(d3.extent(data, d => dateFormat(d.time)))
  .range([0, width]);
const yScale = d3
  .scaleLinear()
  .domain([
    d3.min(data, d => d3.min([d.AIR_WGT_MO, d.CNT_WGT_MO, d.VES_WGT_MO])),
    d3.max(data, d => d3.max([d.AIR_WGT_MO, d.CNT_WGT_MO, d.VES_WGT_MO]))
  ])
  .range([height, 0]);
```

--------------------------------

### Style vector tiles using feature state

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Apply a choropleth style to a fill layer by interpolating colors based on a 'value' from the feature state. This allows for visual representation of data distribution.

```javascript
map.setPaintProperty("counties-fill", "fill-color", [
  "interpolate",
  ["linear"],
  ["feature-state", "value"],
  0.3,
  "#fef0d9",
  0.6,
  "#fdcc8a",
  0.8,
  "#fc8d59",
  0.9,
  "#e34a33",
  1,
  "#b30000"
]);
```

--------------------------------

### Query Census Data with CitySDK

Source: https://uscensusbureau.github.io/citysdk/examples/mapbox-choropleth

Use the CitySDK to query for specific variables (e.g., B08134_001E, B08134_011E) for a given vintage and geographic hierarchy. The response is logged to the console.

```javascript
census(
  {
    vintage: 2019,
    geoHierarchy: {
      county: "*"
    },
    sourcePath: ["acs", "acs5"],
    values: ["NAME", "B08134_001E", "B08134_011E"]
  },
  (error, response) => {
    console.log(response);
  }
);

```

--------------------------------

### Query All Times with Promise.all

Source: https://uscensusbureau.github.io/citysdk/examples/d3-line-chart

Generates an array of census promises for each time period and uses Promise.all to fetch data concurrently. It extracts the first element from each response.

```javascript
const timesQueries = times.map(time => {
  return censusPromise({
    vintage: "timeseries",
    sourcePath: ["intltrade", "exports", "naics"],
    values: ["AIR_WGT_MO", "CNT_WGT_MO", "VES_WGT_MO"],
    predicates: { time: time, NAICS: "111" },
    statsKey: "3c04140849164b373c8b1da7d7cc8123ef71b7ab"
  }).then(response => response[0]); //get first array
});
Promise.all(timesQueries).then(responses => {
  console.log(responses);
  //[
  //    {AIR_WGT_MO: 8972541, CNT_WGT_MO: 1138572445, VES_WGT_MO: 12638056922, time: "2015-01", NAICS: 111},
  //    {AIR_WGT_MO: 8672703, CNT_WGT_MO: 1238855849, VES_WGT_MO: 11479577166, time: "2015-02", NAICS: 111},
  //...
  //]
});
```

--------------------------------

### Query Demographic Data with CitySDK

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet-choropleth

Use the CitySDK `census` function to fetch geographic data and population estimates for counties. The response is passed to a callback function.

```javascript
census(
  {
    vintage: 2019,
    geoHierarchy: {
      state: {
        lat: 28.466944,
        lng: -82.498148
      },
      county: "*"
    },
    geoResolution: "5m",
    sourcePath: ["acs", "acs5", "subject"],
    // Total!!Estimate!!Total population : S0102_C01_001E
    // 60 years and over!!Estimate!!Total population : S0102_C02_001E
    values: ["S0102_C01_001E", "S0102_C02_001E"]
  },
  function(error, response) {
    L.geoJson(response).addTo(map);
  }
);

```

--------------------------------

### Fetch Census Data by County

Source: https://uscensusbureau.github.io/citysdk/examples/old

Fetches census data for all counties within a specified state for the year 2017. Requires the 'citysdk' module.

```javascript
let census = require('citysdk')

census(
  {
    "vintage" : "2017",
    "geoHierarchy" : {
      "state" : "51",
      "county" : "*"
    },
    "sourcePath" : ["acs", "acs1"],
    "values" : ["NAME"],
    "predicates" : {
        "B01001_001E" : "0:100000"
    }
  },
  (err, res) => console.log(res)
)
    
```

--------------------------------

### Query Data with CitySDK and Add to Map

Source: https://uscensusbureau.github.io/citysdk/examples/leaflet

Use CitySDK to query for geojson data based on specified criteria (vintage, geoHierarchy, predicates, values) and add it as a layer to the map.

```javascript
census(
  {
    vintage: 2016,
    geoHierarchy: {
      state: 48,
      county: '*'
    },
    geoResolution: '500k',
    sourcePath: ['cbp'],
    predicates: {
      NAICS2012: 211 // NAICS code for Oil and Gas Extraction
    },
    values: ['ESTAB'] // number of establishments
  },
  function(error, response) {
    L.geoJson(response).addTo(map);
  }
);

```
Tokens:
Raw