This is a web API for serving layer groups, which are a custom data model for named groups of Mapbox GL layers and their associate legend and source data.

This API is consumed by these apps:

• Labs ZoLa
• Streets
• Population FactFinder

Requirements

You will need the following things properly installed on your computer.

• Git
• Node.js (with NPM)
• Yarn

Local development

• Clone this repo: git clone [email protected]:NYCPlanning/labs-layers-api.git
• Navigate to the repo: cd labs-layers-api
• Install the dependencies: yarn
• Start the server: NEW_RELIC_LICENSE_KEY=<your-key> yarn run dev

Changing Carto instance

By default, the API will serve layers from the planninglabs carto account, which holds production layers.

To switch to the dcpadmin account, which holds staging layers, specify the CARTO_USERNAME environment variable on startup:

CARTO_USERNAME='dcpadmin' yarn run dev

or

NEW_RELIC_LICENSE_KEY=<your-key> CARTO_USERNAME='dcpadmin' yarn run dev

Not all layers are yet in "Data Pipeline"/Have staging equivalents

About a half dozen source layers are not yet in the dcpadmin account. They will be excluded from the generated anonymous map when dcpadmin is the specified carto instance. They are filtered out by checking for the dataPipeline boolean property attached to sources.

These layers currently include subways, flood insurance rates, and industrial business zones.

Changing PORT/HOST

When running locally, the application will default to port 3000. Under most circumstances, the default port should be adequate. If there is a reason to override the default, both the PORT and HOST variables must be changed at the same time:

PORT=3120 HOST=http://localhost:3120 yarn run dev

In Production/staging, Heroku automatically sets both PORT and HOST variables.

Running without New Relic

For development purposes, you can run the API without providing a New Relic license key by disabling New Relic. Comment out the New Relic import at the top of app.js:

// require('newrelic');

Architecture

Layer Groups

The layer-groups endpoint delivers layer groups, which are groups of MapboxGL layers. For example, the "subways" layer group includes the subway lines, subway routes, and subway station entrances layers. Each layer defines has style and some filter definitions. Alongside layers, the Layers API also delivers sources which provide SQL definitions for the layers. One source may correspond to multiple layers. For example, a subways source powers the layers for Subway A line, Subway J line and Subway G line, etc.

Most importantly, along with Layer Groups, the Layers API payload delivers a MapboxStyle object, which provides vector tile URL definitions for all source layers. These tile url definitions are anonymous maps generated by Layers API using the Carto Maps API.

Anonymous Maps

Anonymous maps from the Carto Maps API are generated on each request to the /layer-groups endpoint. They are short-lived, meaning they will be destroyed after a period of time

See the getVectorTileTemplate funtion within utils/carto.js.

Population Factfinder Layer Groups and Sources

Population Factfinder relies on a "one-off", factfinder-specific Layer Groups and Sources in the Layers API. These are necessary for Factfinder-specific adjustments to these layers (legend title, slight styling changes) that should not affect other apps.

These Layer Groups and Sources have the prefix factfinder--. For example, layer-groups/factfinder--neighborhood-tabulation-areas.json

Some of thse PFF layers/sources use geojson of NTAs along with various data from the ACS and Decennial census. This geojson is kept directly in ./data/sources. The code and documentation on how to generate or update this data is found in the jupyter notebook ./process-data/etl/build_choropleths.ipynb.

Schemas

• Layer Group
• Layer
• Source

Testing and checks

• ESLint - We use ESLint with Airbnb's rules for JavaScript projects

  • Add an ESLint plugin to your text editor to highlight broken rules while you code
  • You can also run eslint at the command line with the --fix flag to automatically fix some errors.

• Testing

  • run yarn test

Sprites

The sprite sheet is generated by scripts that create a set of SVGs, then turn them into four files served in public/static/:

• sprite.json
• sprite.png
• [email protected]
• [email protected]

SVG files are output to assets/sprite/svg/ by assets/sprite/create-sprite-svgs.js. Edit this file to change the automatically-created SVGs.

• Run npm run create-sprite-svgs to create the SVGs

The .png and .json files for Mapbox GL to consume are created with spritezero-cli.

• If you haven't, install the command-line interface: npm install -g @mapbox/spritezero-cli
• Run the commands to generate the sprites at each resolution:
  • spritezero public/static/sprite assets/sprite/svg/
  • spritezero public/static/sprite@2x assets/sprite/svg/ --ratio=2