Name: maas-siri-vm-server
Owner: Open Knowledge Finland
Description: OKFFI Fluency Navigator MaaS server that consumes SIRI VM data
Created: 2015-06-06 11:29:56.0
Updated: 2015-06-12 12:25:40.0
Pushed: 2015-06-16 12:15:43.0
Homepage: null
Size: 2380
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
OKFFI Fluency Navigator MaaS API server
See Sujuvuusnavigaattori for further info.
If you're running into this error:
you're facing a known problem in mixing docker and packer, which exists as of June 2015, and is discussed in [packer issue #1752](https://github.com/mitchellh/packer/issues/1782).
s repository](https://github.com/stefancocora/packer-issue1752-fix) contains patched packer files that work fine with `shell` provisioning scripts.
erver API overview
Introduction
server is used to collect, process and build reports on bicycle travel data.
client applications can serve two purposes:
ontribute travel data to the server
equest reports to visualize travel situation
clients specifically submit user's travel plans, traces, routes and may request and visualize reports.
ult format is JSON encoded as UTF-8.
t data should be submitted with `Content-type: application/json` header, in which case request
must contain a JSON object.
ase `Content-type: application/json` header is not present, all data should be submitted as
ON-encoded string in a `payload` parameter.
Examples
ider this plan object to be submitted:
var obj={
journey_id: 'abcdefghijklmnopqrstuvwxyz0123456789',
timestamp: (new Date()).toJSON(),
coordinates: [[0,0], [0,1], [1,1], [1,0]]
};
dard approach:
$.ajax({
url: 'http://maas.okf.fi/plans',
type: 'POST',
contentType: 'application/json',
data: JSON.stringify(obj)
}) .done(…)
ervative approach:
$.ajax({
url: 'http://maas.okf.fi/plans',
type: 'POST',
data: { payload:JSON.stringify(obj) }
}) .done(…)
Status and error handling
server supports [CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
essful responses with payload generate status code 200.
y responses generate status code 204.
requests generate status code 400.
er errors generate status code 500.
ests are rejected entirely even if one of data elements is missing a mandatory field.
Journey handling
ient is expected to generate a UUID-like unique ID that is meant to identify a user actually following a travel plan and thus
orming a journey. This ID is called `journey_id` and has to be provided in the API calls as per documentation below.
se see the workflow description for working with `journey_id`.
Workflow
pical workflow of client application is to:
enerate `journey_id` as a sufficiently long (30+ characters) random string
equest an OTP plan
upply the plan and `journey_id` to the API server, obtaining the `planID`
isplay speed report for a plan using `planID`
f user confirms the journey plan, start collecting traces/routes, otherwise go back to 2
ubmit traces/routes to the API server regularly
f 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.
f user requests a new plan on the way, go back to 2.
her common type of workflow is to diplay speed situation using coordinates of a user's viewport as a `boundaries` parameter.
Endpoints
w is a list of currently implementes server endpoints.
| Description
---------------------------- | ------------------------------------------------------------------
/reports/speed-averages` | Obtain average speed report as a geoJSON FeatureCollection
/plans/{planID}` | Obtain a previously saved plan as a geoJSON Feature
T /plans` | Save a plan
T /traces` | Save a trace or several traces
T /routes` | Save a route or several routes
/demo.html` | Open a demo page (`Content-type: text/html`)
/wfs.xml?` | A very simple [WFS](http://www.opengeospatial.org/standards/wfs)-compatible interface to report data (`Content-type: text/xml`)
Plans
s are produced by [Open Trip Planner](http://www.opentripplanner.org/) based on [Open Street Map](http://www.openstreetmap.org/) and are used to spatially describe a travel intention of a user.
s are used to map traces onto existing map objects (streets etc.) to correct potentially inaccurate GPS data.
T /plans`
meters:
| Format | Mandatory | Notes
------------- | -------- | --------- | --------
ney_id | string | yes |
dinates | array | yes | This must be a from->to array of 2 or more coordinates as in a [geoJSON](http://geojson.org/geojson-spec.html) LINESTRING: longitude, latitude [, altitude]
stamp | string | yes | This should be in ISO8601 format with time zone (see [toJSON()](http://www.w3schools.com/jsref/jsref_tojson.asp) method). Submitting time in UTC time zone is strongly recommended
request will return a unique plan id that can be used to retrieve plan details later via the following request:
/plans/{planID}`
o obtain a report on average speeds (see below).
Routes
es are segments (lines) in a travel plan that the traveller has just completed. A route is a just a single line with an
age speed (in m/s) calculated for that line.
es form a dataset for average speeds report.
T /routes`
orts both single-object and array-of-objects formats.
meters:
| Format | Mandatory | Notes
------------- | -------- | --------- | --------
ney_id | string | yes |
stamp | string | yes | This should be in ISO8601 format with time zone (see [toJSON()](http://www.w3schools.com/jsref/jsref_tojson.asp) method). Submitting time in UTC time zone is strongly recommended.
dinates | array | yes | This must be a from->to array of exactly 2 coordinates as in a [geoJSON](http://geojson.org/geojson-spec.html) LINESTRING: longitude, latitude [, altitude]
d | float | yes | Average speed along the route.
| string | yes | OTP plan mode
Traces
es are momentary snapshots of data about a moving bicycle rider as collected from a mobile client.
trace contains a single set of spatial coordinates.
es form a very basic dataset about actual bicycle travel.
T /traces`
orts both single-object and array-of-objects formats.
meters:
| Format | Mandatory | Notes
------------- | -------- | --------- | --------
ney_id | string | yes |
stamp | string | yes | This should be in ISO8601 format with time zone (see [toJSON()](http://www.w3schools.com/jsref/jsref_tojson.asp) method). Submitting time in UTC time zone is strongly recommended.
tude | float | yes | Geographical latitude of a user
itude | float | yes | Geographical longitude of a user
tude | float | no | Geographical altitude of a user
Reports
rts generate aggregated data about average bicycle speeds in various spatial areas.
returned is a `FeatureCollection` from [geoJSON specification](http://geojson.org/geojson-spec.html).
feature has a `geometry` attribute, containing a linestring, and a `speed` custom property that contains an array of average speed
es in meter/second, matching al of the segments in that linestring.
/reports/speed-averages`
meters:
| Format | Mandatory | Notes
--------------- | -------- | --------- | --------
ID | integer | no | Obtained in a separate POST call (see above)
dary_sw_lon | float | no | Longitude of the south-western boundary (all four must be present)
dary_sw_lat | float | no | Latitude of the south-western boundary
dary_ne_lon | float | no | Longitude of the north-eastern boundary
dary_ne_lat | float | no | Latitude of the north-eastern boundary
r | string | no | This should be in ISO8601 format with time zone (see [toJSON()](http://www.w3schools.com/jsref/jsref_tojson.asp) method). Submitting time in UTC time zone is strongly recommended.
re | string | no | Same as above
| string | no | can be either `baseline`, `realtime` or `combined` (default: `combined`)
e are optional parameters that provide for limiting aggregation and averages based on space and/or time.
ifically, `boundaries` is used to specify spatial limit; `before` and `after` are timestamps to limit selection
ents of time indicated by either of the timestamps are excluded from selection).
`planID` is provided, the report will only cover areas that are part of the specified plan.
line reports are based on carefully processed data, realtime reports are based on community data.
atabase schema
ncy related data is stored in the following db tables (PostgreSQL/PotGIS data types):
ce` table:
| Type | notnull | PK | Notes
------------- | -------------- | --------- | --------- | -------
e_id | BIGSERIAL | true | true |
ney_id | TEXT | true | |
stamp | TIMESTAMP | true | |
etry | geometry | true | | POINT
n` table:
| Type | notnull | PK | notes
------------- | -------------- | --------- | --------- | -------
_id | BIGSERIAL | true | true |
ney_id | TEXT | true | |
stamp | TIMESTAMP | true | | WITH TIME ZONE
etry | geometry | true | | LINESTRING
te` table:
| Type | notnull | PK | Notes
------------- | -------------- | --------- | --------- | -----
e_id | BIGSERIAL | true | true |
ney_id | TEXT | true | |
stamp | TIMESTAMP | true | | WITH TIMEZONE
etry | geometry | true | | LINESTRING, simple, two points
d | DECIMAL(21,16) | true | |
| TEXT | true | | obtained from an OTP plan
time | BOOLEAN | false | | default: true
ort` table (used as a cache for quicker delivery of report data):
| Type | notnull | PK | Notes
------------- | -------------- | --------- | --------- | -----
rt_id | BIGSERIAL | true | true |
stamp | TIMESTAMP | true | | WITH TIMEZONE, contains report generation time
etry | geometry | true | | LINESTRING
d | DECIMAL(21,16) | true | | average speed per linestring, defaults to 0
ing | DECIMAL(21,16) | true | | average number of readings per linestring, defaults to 0
| TEXT | true | | either 'realtime', 'baseline' or 'combined'
erver dockerization
-docker is a utility that facilitates deployment and running
aaS API Server via Docker container with the use of Packer.
ker](https://packer.io/) is a utility to streamline creation and deployment of virtual
ine images.
ker](http://docker.io/) is a flavor of machine virtualization tools with neat features.
s-docker.sh` script allows you to:
reate Docker image from official ubuntu:latest and build MaaS API Server environment inside it
un MaaS API API Server as a docker container
iew running Docker containers
top a running Docker container
script is also capable of updating the base operating system.
script to see the usage help.