Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

occrp-story-map-generate-geojson

Generates GeoJSON for use with OCCRP story map at occrp-story-map

oclif

readme

occrp-story-map-generate-geojson

This is a standalone CommandLine tool that generates GeoJSON for use with occrp-story-map.

The tool will read from a stories.json file in the format of the occrp-story-map project, and will query an OSRM compatible API for directions between the points in the story.

It will then output these points as GeoJSON to the file specified by the OUTPUT variable either on the command-line or in the .env file.

Getting started

Note: This library is intended as a dependency for occrp-story-map. It functions as a standalone, but it's not really useful.

Setting up for development

yarn install
cp .env.sample .env

Executing the command-line tool

./bin/run

Flags

Option Description
--version -v Display version
--help -h Display usage information
--output -o Override the output file and use the provided path
--input -i Override the input path provided and use the provided path

Env variables

The project supports an .env file at the root, but it also will read from the .env file loaded at the root of a project where it is a dependency.

The following .env variables are supported:

Option Required Description
ROUTER_PROFILE optional The default Router Profile and corresponding router to use. Default: 'driving'
ROUTE_OVERVIEW optional The OSRM route_overview value. Can be full or simplified. Full provides a comprehensive high-resolution GeoJSON set. Simplified provides a simple GeoJSON approximation with only a few points
FILE_NAME optional The name of the output file. Default routes.json
OUTPUT required if not provided on command-line The path to write the output file. E.g. dist.
INPUT required if not provided on command-line The path of the input file. E.g. story/story.en.json.
ALWAYS_USE_ALL_POINTS optional If true then routes will be generated that visit every previous point in the story. Otherwise, routes only go from the previous point to the next one.

Routers

The tool uses a small standalone javascript class to provide an interface with any OSRM-compatible routing interface.

The Router class is defined in router.js. This could be easily extended in the future to support other APIs.

Each provided router is defined in src/routers. These are instances of the Router class.

Currently the following routers are provided:

Router InstanceOf Description
trainRouter.js Router Provides an interface to the Railway router available at https://signal.eu.org/. Routes calculated follow rails provided in the OpenStreetMaps database.
drivingRouter.js Router Provides an interface to the OSRM Router https://router.project-osrm.org/. Routes calculated follow streets and roads.

Adding a new router

To add a new OSRM-compatible router, you simply need to duplicate src/routers/drivingRouter.js, update the URL and 'profile' provided in the constructor with those of the OSRM Compatible router.

You then need to add your router to the availableRouters object in src/router.js. The key of this object will be the ROUTER_PROFILE that you need to specify in your env file.

Point-specific routers

Some story points specify which router profile should be used for the point in their JSON structure with the key transportType. This key overrides all the other variables set (environment variables for example). The value of this key must correspond to a router in availableRouters in src/routers.js.