SharedStreets Mobility Metrics is an open source command line interface (CLI) and frontend for ingestion and analysis of Mobility Data Specification (MDS) mobility data. It is capable of reading raw MDS and aggregating useful & privacy-protecting metrics for longterm storage and analysis. Raw data is not persisted after aggregation.
Returns raw metrics data for a provider for the specified day. This endpoint is used by the frontend, and can be used to power alternate UIs or scripted analysis.
Serves an html report that visualizes the metrics data for the specified day using maps, charts, and summaries.
Setup project and install dependencies.
npm install -g mobility-metrics
config.json file is required to run Mobility Metrics. Enable providers and set credentials through this file. This file is used to store access tokens - handle with care, these tokens are sensitive!. See the config file in
/example/example.json for a working example.
In your config.json file, each provider can be one of two types:
The CLI is responsible for downloading raw data, running aggregation and reports, then deleting the raw cache. Configure this command in cron for automated daily imports.
# --day = target backfill date in YYYY-MM-DD format # --days = number of days prior to target to also backfill mobility-metrics --config ./example/example.json --public ./public --cache ./cache --day 2019-07-20;
The metrics data and reports generated by the mobility-metrics CLI are intended to be served from a static HTTP server, such as apache, nginx, or a public HTTP service like netifly or Github Pages. See the gh-pages branch of this repository to see how the demo for this tool is hosted using simulated data in Nashville, TN.
For a simple demonstration, the node module
serve can be used to test out a configuration:
npm install -g serve mobility-metrics --config ./example/example.json --public ./public --cache ./cache --day 2019-07-20 serve ./public open http://localhost:5000/reports/2019-07-20/All
An example is provided in this repository for testing out mobility-metrics UI and aggregations. The example provides ready to use scripts that simulate MDS telemetry using an multi-agent model with the SharedStreets trip-simulator tool. Install the following requirements to get started:
To run the simulation, use the following script:
Now that you have raw simulated MDS data to work with, run a backfill using the mobility-metrics CLI:
mobility-metrics --config ./example/example.json --public ./public --cache ./cache --day 2019-07-20
A full static file structure should be generated at
./public. See the Serving API section above for tips on serving this endpoint over HTTP.
Run a test suite across the project. Auto-formats code using linter.
Runs a linter, prettier, and auto-formats code to meet consistent style, while checking for syntax errors.
npm run lint
Total vehicles: Total number of vehicles that were on the street at any time during the specified day. This includes all vehicles that were available, unavailable or reserved according to the event types specified here.
Active vehicles: Total number of vehicles that completed at least one trip during the specified day. (Trips)
Total trips: Total number of trips taken throughout the specified day.
Total trips distance: Total miles traveled by any vehicles throughout the specified day. (trip_distance)
Vehicle Utilization: Percentage of vehicles that were active over the course of a day.
Average distance per vehicle: Total trips distance, divided by active vehicles
Average trips per active vehicle: Total trips, divided by active vehicles
Average trip distance: Total trips distance, divided by total trips
Average trip duration: Total trips duration, divided by total trips
Trip Volume: The number of vehicles that moved over a street or in a zone during the time window specified.
Availability: The maximum number of vehicles that were available to users during the time window specified.
On-street: The maximum number of vehicles that are on the street and available or unavailable during the time window specified.
Pickups: The total number of trips that began during a time window
Dropoffs: The total number of trips that ended during a time window
Flows: The number of trips that went from one area of the city to another area of the city, sometimes referred to as origin/destination data or “O/D pairs”