https://github.com/nycplanning/labs-layers-api
API for serving complex mapboxGL styles
https://github.com/nycplanning/labs-layers-api
labs
Last synced: 6 months ago
JSON representation
API for serving complex mapboxGL styles
- Host: GitHub
- URL: https://github.com/nycplanning/labs-layers-api
- Owner: NYCPlanning
- License: other
- Created: 2018-08-06T18:13:01.000Z (about 7 years ago)
- Default Branch: develop
- Last Pushed: 2025-04-02T13:33:59.000Z (7 months ago)
- Last Synced: 2025-04-02T14:33:10.458Z (7 months ago)
- Topics: labs
- Language: JavaScript
- Size: 11.3 MB
- Stars: 13
- Watchers: 8
- Forks: 3
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://circleci.com/gh/NYCPlanning/labs-layers-api)
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](https://github.com/NYCPlanning/labs-zola)
- [Streets](https://github.com/NYCPlanning/labs-streets)
- [Population FactFinder](https://github.com/NYCPlanning/labs-factfinder)
## Requirements
You will need the following things properly installed on your computer.
- [Git](https://git-scm.com/)
- [Node.js](https://nodejs.org/) (with NPM)
- [Yarn](https://yarnpkg.com/en/)
## Local development
- Clone this repo: `git clone git@github.com:NYCPlanning/labs-layers-api.git`
- Navigate to the repo: `cd labs-layers-api`
- Install the dependencies: `yarn`
- Start the server: `NEW_RELIC_LICENSE_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= 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](https://docs.mapbox.com/mapbox-gl-js/style-spec/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](https://docs.mapbox.com/mapbox-gl-js/style-spec/root/), which provides [vector tile URL definitions](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/) for all source layers. These tile url definitions are _anonymous maps_ generated by Layers API using the [Carto Maps API](https://carto.com/developers/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](https://carto.com/developers/maps-api/guides/anonymous-maps/#:~:text=Anonymous%20Maps%20cannot%20be%20removed,five%20minutes%2C%20or%20sometimes%20longer)
See the `getVectorTileTemplate` funtion within `utils/carto.js`.
### Population Factfinder Layer Groups and Sources
[Population Factfinder](https://github.com/NYCPlanning/labs-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](https://github.com/NYCPlanning/labs-layers-api/blob/develop/schemas/layer-group.js)
- [Layer](https://github.com/NYCPlanning/labs-layers-api/blob/develop/schemas/layer.js)
- [Source](https://github.com/NYCPlanning/labs-layers-api/blob/develop/schemas/source.js)
## 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`
- `sprite@2x.json`
- `sprite@2x.png`
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](https://github.com/mapbox/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`