diff --git a/Dockerfile b/Dockerfile
index e8bc6ecd8c5143b3bcd5565984b686603c601be6..c5f117fbac06d5055def3a632226f7b30c353ddf 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,13 +4,13 @@ MAINTAINER Markus Willman
 
 SHELL ["/bin/bash", "-c"]
 
-# update the system, install python and create symlinks and directories
+# update the system, install python 2.7 and create symlinks and directories
 RUN apt-get update -qqy --fix-missing \
 	&& apt-get upgrade -qqy \
 	&& apt-get install -qqy --no-install-recommends \
 	build-essential \
-	python \
-	python-dev \
+	python2.7 \
+	python2.7-dev \
 	python-pip \
 	python-setuptools \
 	supervisor \
@@ -30,7 +30,7 @@ WORKDIR /opt/services/smartbusstop
 COPY . /opt/services/smartbusstop
 ADD http://data.foli.fi/gtfs/gtfs.zip /opt/services/smartbusstop/data/gtfs.zip
 
-# install python dependencies opencv-python needs libgtk2.0-dev installed in the system, if we want to install it here (virtualenv pip)
+# install python dependencies, note: opencv-python needs libgtk2.0-dev installed in the system, if we want to install it here
 RUN pip --no-cache-dir install -r /opt/services/smartbusstop/system-requirements.txt \
 	&& rm -f /opt/services/smartbusstop/system-requirements.txt \
 	&& virtualenv /opt/services/smartbusstop/.venv \
diff --git a/README.md b/README.md
index 781951e92aa5b4be968af9ca94ebc76b8c4542a9..6c11c863b07e3870eb1f00c965c0b8c820346384 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,7 @@ The deploy branch **can not** be pushed to directly using command line tools, as
 it is protected in such a way, so make a merge request and accept it, to trigger a
 deploy, using gitlab web interface.
 
-## About the Flask Application (WIP)
+## About the Flask Application
 
 It will respond to requests based on which templates exist in the templates
 directory, excluding any templates placed in the internal sub directory.
@@ -105,22 +105,106 @@ harder to access unintended content through it. The ref argument can contain any
 alphanumeric characters underscores or dashes after the word kiosk for logging
 purposes. The ref argument is also preserved for all internal ajax calls. 
 
-### Javascript json endpoints (tentative)
+The application uses a fairly strict Content-Security-Policy regardless of which
+mode it is accessed under.
 
-#### Stop Information
+## Localization
+
+Localization is done using `Flask-Babel` to create or update gettext message catalogs
+the scripts in the `scripts` directory can be used. They **must** be ran from the
+repository root.
+
+When using docker translations are automatically compiled at build time.
+
+### Javascript JSON endpoints
+
+Note the endpoints rely on the standardized GTFS data from the archive over the data
+from Föli JSON API's which is non-standard whenever possible. For example GTFS data
+is used for all schedule data, over the SIRI SM (Stop Monitoring) endpoint even, 
+because we have no control over how much or how little data said endpoint produces
+whereas we have full control over GTFS data.
+
+Likewise bridging the two data sources is not reliable or trivial, this only done
+for shape information currently and even then multiple shapes can be returned for
+one vehicle in theory (the theoretical worst case being it would return all shapes
+for the current day for every vehicle).
+
+#### Stop information
 
 ```
 URI: /api/v1/info/<stopId>
-Data Source: http://data.foli.fi/gtfs/gtfs.zip
+Data Source: GTFS stops.txt
 Returns: JSON object corresponding to the provided stop code ammended with the
 stop_url field.
 ```
 
-#### Data Files
+#### Arriving buses
+
+```
+URI: /api/v1/arrivals/<stopId>/[<routeType>/?limit=<n>]
+Data Source: GTFS trips.txt + routes.txt
+Returns: next N arriving trips on a specific stop. The routeType parameter
+controls how much information is returned about each trip (head/full/partial),
+partial limits the stop points to 10 closest and head does not include stop points
+at all.
+```
+
+#### Routes for specific stop
+
+```
+URI: /api/v1/routes/<stopId>[/<type>/]
+Data Source: GTFS routes.txt
+Returns: a list of routes that stop at a specifc stop (route contains 1 to N
+trips, this does not contain trip info). The type parameter controls whether
+this returns the full route info (equivalent to 'head' routeType in arrivals
+endpoint) or just a list of short names.
+```
+
+#### Stop schedule (trips)
+
+```
+URI: /api/v1/trips/<stopId>/[<routeType>/?offset=<n>&limit=<m>]
+Data Source: GTFS trips.txt + routes.txt
+Returns: schedule information for a specific stop. This endpoint is a
+superset of the arrivals endpoint that can be used to retrieve paginated
+schedule information for the day routeType parameter behaves identically.
+```
+
+#### Trip information
+
+```
+URI: /api/v1/trip/<tripSlug>/
+Data Source: GTFS trips.txt + routes.txt
+Returns: the full stop point listing of any trip for today, intended for use
+with the arrivals or trips endpoints above (with routeType 'head').
+```
+
+#### Real time location information
+
+```
+URI: URI: /api/v1/locator[/<stopId>/<type>]
+Data Source: Föli SIRI Vehicle Monitoring
+Returns: vehicles in transit related to specific stop. The type parameter can
+be either 'raw' (returns the unfiltered VM response), 'nearby' (returns all
+buses within 5 kilometers of the selected stop) or 'routed' (returns all buses
+that stop at the selected stop).
+```
+
+#### Track specific bus
+
+```
+URI: URI: /api/v1/locator/vehicle/[<busId>/<getShape>/]
+Data Source: Föli SIRI Vehicle Monitoring + GTFS shapes.txt
+Returns: single vehicle record by the vehicle id (here busId) in SIRI, if 
+getShape is non-zero also includes shape information for the current route
+(lineref) and block (key 'shapes' in response). May return more than one shape.
+```
+
+#### Data files
 
 ```
 URI: URI: /api/v1/data/[<stopId>/]<path>.json
 Data Source: data directory
 Returns: the corresponding data file, if stopCode is provided files specific to
-that GTFS stop_code will have priority.
+that GTFS stop_id will have priority.
 ```
diff --git a/requirements.dev.txt b/requirements.dev.txt
new file mode 100644
index 0000000000000000000000000000000000000000..7cac4ed7003073c795988929727a6774e372c7f4
--- /dev/null
+++ b/requirements.dev.txt
@@ -0,0 +1,8 @@
+Flask>=0.12.2
+Flask-Babel
+speaklater
+six
+pytz
+transitfeed
+python-dateutil
+requests
diff --git a/requirements.txt b/requirements.txt
index 7cac4ed7003073c795988929727a6774e372c7f4..42d2d241466edea64222c2c505eefc93ec602c57 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,8 +1,8 @@
-Flask>=0.12.2
-Flask-Babel
-speaklater
-six
+Flask==0.12.2
+Flask-Babel==0.11.2
+speaklater==1.3
+six==1.11.0
 pytz
-transitfeed
-python-dateutil
-requests
+transitfeed==1.2.16
+python-dateutil==2.6.1
+requests==2.18.4
diff --git a/system-requirements.dev.txt b/system-requirements.dev.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6c1399c1bf608904af79d946b26b34297cd52c6b
--- /dev/null
+++ b/system-requirements.dev.txt
@@ -0,0 +1,2 @@
+uWSGI>=2.0.15
+virtualenv>=15.1.0
diff --git a/system-requirements.txt b/system-requirements.txt
index 6c1399c1bf608904af79d946b26b34297cd52c6b..743ccbd8196d035bbb4d25f1b36a5024d1c54973 100644
--- a/system-requirements.txt
+++ b/system-requirements.txt
@@ -1,2 +1,2 @@
-uWSGI>=2.0.15
-virtualenv>=15.1.0
+uWSGI==2.0.17
+virtualenv==15.1.0