Skip to content

okffi/maas-server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

71 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

maas-server

OKFFI Fluency Navigator MaaS API server

See Sujuvuusnavigaattori for further info.

ERRATA

If you're running into this error:

Retryable error: Error uploading script: Upload failed with non-zero exit status: 1

Then you're facing a known problem in mixing docker and packer, which exists as of June 2015, and is discussed in packer issue #1752.

This repository contains patched packer files that work fine with shell provisioning scripts.

Server API overview

Introduction

API server is used to collect, process and build reports on bicycle travel data.

API client applications can serve two purposes:

  1. contribute travel data to the server
  2. request reports to visualize travel situation

API clients specifically submit user's travel plans, traces, routes and may request and visualize reports.

Default format is JSON encoded as UTF-8.

Input data should be submitted with Content-type: application/json header, in which case request body must contain a JSON object.

In case Content-type: application/json header is not present, all data should be submitted as a JSON-encoded string in a payload parameter.

Examples

Consider this plan object to be submitted:

var obj={
        journey_id: 'abcdefghijklmnopqrstuvwxyz0123456789', 
        timestamp: (new Date()).toJSON(), 
        coordinates: [[0,0], [0,1], [1,1], [1,0]]
    };

Standard approach:

$.ajax({
    url: 'http://maas.okf.fi/plans',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(obj)
})
.done(...)

Conservative approach:

$.ajax({
    url: 'http://maas.okf.fi/plans',
    type: 'POST',
    data: { payload:JSON.stringify(obj) }
})
.done(...)

Status and error handling

The server supports CORS.

Successful responses with payload generate status code 200.

Empty responses generate status code 204.

Bad requests generate status code 400.

Server errors generate status code 500.

Requests are rejected entirely even if one of data elements is missing a mandatory field.

Journey handling

A client is expected to generate a UUID-like unique ID that is meant to identify a user actually following a travel plan and thus performing a journey. This ID is called journey_id and has to be provided in the API calls as per documentation below.

Please see the workflow description for working with journey_id.

Workflow

A typical workflow of client application is to:

  1. Generate journey_id as a sufficiently long (30+ characters) random string
  2. Request an OTP plan
  3. Supply the plan and journey_id to the API server, obtaining the planID
  4. Display speed report for a plan using planID
  5. If user confirms the journey plan, start collecting traces/routes, otherwise go back to 2
  6. Submit traces/routes to the API server regularly
  7. If user reaches the destination, hits the stop button, cancels the journey or does not move for a significant amount of time (15+ minutes), go back to 1.
  8. If user requests a new plan on the way, go back to 2.

Another common type of workflow is to diplay speed situation using coordinates of a user's viewport as a boundaries parameter.

Endpoints

Below is a list of currently implementes server endpoints.

URI Description
GET /reports/speed-averages Obtain average speed report as a geoJSON FeatureCollection
GET /plans/{planID} Obtain a previously saved plan as a geoJSON Feature
POST /plans Save a plan
POST /traces Save a trace or several traces
POST /routes Save a route or several routes
GET /demo.html Open a demo page (Content-type: text/html)
GET /wfs.xml? A very simple WFS-compatible interface to report data (Content-type: text/xml)

Plans

Plans are produced by Open Trip Planner based on Open Street Map and are used to spatially describe a travel intention of a user.

Plans are used to map traces onto existing map objects (streets etc.) to correct potentially inaccurate GPS data.

POST /plans

Parameters:

Name Format Mandatory Notes
journey_id string yes
coordinates array yes This must be a from->to array of 2 or more coordinates as in a geoJSON LINESTRING: longitude, latitude [, altitude]
timestamp string yes This should be in ISO8601 format with time zone (see toJSON() method). Submitting time in UTC time zone is strongly recommended

Such request will return a unique plan id that can be used to retrieve plan details later via the following request:

GET /plans/{planID}

or to obtain a report on average speeds (see below).

Routes

Routes are segments (lines) in a travel plan that the traveller has just completed. A route is a just a single line with an average speed (in m/s) calculated for that line.

Routes form a dataset for average speeds report.

POST /routes

supports both single-object and array-of-objects formats.

Parameters:

Name Format Mandatory Notes
journey_id string yes
timestamp string yes This should be in ISO8601 format with time zone (see toJSON() method). Submitting time in UTC time zone is strongly recommended.
coordinates array yes This must be a from->to array of exactly 2 coordinates as in a geoJSON LINESTRING: longitude, latitude [, altitude]
speed float yes Average speed along the route.
mode string yes OTP plan mode

Traces

Traces are momentary snapshots of data about a moving bicycle rider as collected from a mobile client. Each trace contains a single set of spatial coordinates.

Traces form a very basic dataset about actual bicycle travel.

POST /traces

supports both single-object and array-of-objects formats.

Parameters:

Name Format Mandatory Notes
journey_id string yes
timestamp string yes This should be in ISO8601 format with time zone (see toJSON() method). Submitting time in UTC time zone is strongly recommended.
latitude float yes Geographical latitude of a user
longitude float yes Geographical longitude of a user
altitude float no Geographical altitude of a user

Reports

Reports generate aggregated data about average bicycle speeds in various spatial areas.

Data returned is a FeatureCollection from geoJSON specification.

Each feature has a geometry attribute, containing a linestring, and a speed custom property that contains an array of average speed values in meter/second, matching al of the segments in that linestring.

GET /reports/speed-averages

Parameters:

Name Format Mandatory Notes
planID integer no Obtained in a separate POST call (see above)
boundary_sw_lon float no Longitude of the south-western boundary (all four must be present)
boundary_sw_lat float no Latitude of the south-western boundary
boundary_ne_lon float no Longitude of the north-eastern boundary
boundary_ne_lat float no Latitude of the north-eastern boundary
after string no This should be in ISO8601 format with time zone (see toJSON() method). Submitting time in UTC time zone is strongly recommended.
before string no Same as above
type string no can be either baseline, realtime or combined (default: combined)

There are optional parameters that provide for limiting aggregation and averages based on space and/or time. Specifically, boundaries is used to specify spatial limit; before and after are timestamps to limit selection (moments of time indicated by either of the timestamps are excluded from selection).

If a planID is provided, the report will only cover areas that are part of the specified plan.

Baseline reports are based on carefully processed data, realtime reports are based on community data.

Database schema

Fluency related data is stored in the following db tables (PostgreSQL/PotGIS data types):

trace table:

Name Type notnull PK Notes
trace_id BIGSERIAL true true
journey_id TEXT true
timestamp TIMESTAMP true
geometry geometry true POINT

plan table:

Name Type notnull PK notes
plan_id BIGSERIAL true true
journey_id TEXT true
timestamp TIMESTAMP true WITH TIME ZONE
geometry geometry true LINESTRING

route table:

Name Type notnull PK Notes
route_id BIGSERIAL true true
journey_id TEXT true
timestamp TIMESTAMP true WITH TIMEZONE
geometry geometry true LINESTRING, simple, two points
speed DECIMAL(21,16) true
mode TEXT true obtained from an OTP plan
realtime BOOLEAN false default: true

report table (used as a cache for quicker delivery of report data):

Name Type notnull PK Notes
report_id BIGSERIAL true true
timestamp TIMESTAMP true WITH TIMEZONE, contains report generation time
geometry geometry true LINESTRING
speed DECIMAL(21,16) true average speed per linestring, defaults to 0
reading DECIMAL(21,16) true average number of readings per linestring, defaults to 0
type TEXT true either 'realtime', 'baseline' or 'combined'

Server dockerization

Maas-docker is a utility that facilitates deployment and running of MaaS API Server via Docker container with the use of Packer.

Packer is a utility to streamline creation and deployment of virtual machine images.

Docker is a flavor of machine virtualization tools with neat features.

maas-docker.sh script allows you to:

  1. create Docker image from official ubuntu:latest and build MaaS API Server environment inside it
  2. run MaaS API API Server as a docker container
  3. view running Docker containers
  4. stop a running Docker container

The script is also capable of updating the base operating system.

Run script to see the usage help.

About

OKFFI Fluency Navigator MaaS server

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages