Use OpenShift to Map River Levels With Flask, MongoDB, Leaflet, and OpenStreetMaps - Archived

The application I’m going to write about here actually had its start a
few years back. I have a number of friends in the whitewater paddling
community around Boston and at the time, I had started playing around
with some of the “Web 2.0” (now that’s a dated term!) shiny-ness such as
Google Maps and the Google Maps API. What if, one of those friends
asked, I wrote an app that would let us see at a glance the water levels
for the local rivers we paddle?

I crated that application and you can see it running on OpenShift at

I spent a fair bit of time poking at the idea but I never got to a
working application. There were just too many moving parts. The USGS,
which maintains the gauges, didn’t have an easy way to get at the data;
I would have had to scrape it off Web pages. I would have had to run a
back-end PHP application and setup an associated database to
periodically do the scraping. And the Google Maps API, which I was
planning to use to display the data, was in relatively early days. I
periodically thought about revisiting the idea, but all those moving
parts made it all seem like too much bother just to get to the point
where I could, well, code the app.

Fast forward to OpenShift community day in Boston this past June. If
you’re reading this, you probably know what
OpenShift is. But in case you don’t, it’s
Red Hat’s Platform-as-a-Service, a cloud computing service model that
aims to make life easier for developers by abstracting away underlying
infrastructure details that aren’t typically relevant to writing Web
applications (such as the provisioning and patching of operating
systems). For our purposes here, I’m going to focus on the hosted Online
version of OpenShift, although there are also enterprise and community
(OpenShift Origin) versions.

Anyway, my colleague Steven Citron-Pousty showed me a demo he had put
together that displayed the location of national parks as pins on a map
that could be scaled and zoomed. Jaw drops. This was exactly what I had
been trying to do! I still had some details to work out–such as getting
the data–but SteveCP had shown me a basic approach that also, not
incidentally, used OpenShift to greatly simplify getting a lot of the
infrastructure set up and operating. It doesn’t eliminate the supporting
components–and, indeed, one of the nice things about OpenShift is that
it gives you a rich choice of languages, frameworks, and other tooling.
But it eliminates much of the unproductive busywork associated with
installing and configuring software on bare metal or on a bare VM. 

But enough preliminaries. Onto the app! (I also encourage you to check
out Part

and Part

of this series of posts by SteveCP which cover overlapping topics. I’ll
move relatively quickly over material detailed in those posts.)

1. Architecture

I’ll start by briefly discussing how everything fits together so that
you can better understand why we’re doing what we’re doing when we get
into the details.

The application runs on a small gear on OpenShift Online. A gear is an
isolated application container and you get three small gears with a free
OpenShift account. The application is written in Python 2.6 and
Flask, a “micro framework” for Python based
on Werkzeug and Jinja 2. (A couple of utility programs I wrote to
manipulate the data are also written in Python.) Flask templating is
used to display an HTML/CSS/JS file that uses Leaflet, a “a modern
open-source JavaScript library for mobile-friendly interactive maps,” to
display the pins and map tiles (which are from OpenStreetMaps). The data
is obtained from a USGS Web service (returning JSON) and stored in a
MongoDB database. 

As you can see, that is a lot of moving parts but it’s surprisingly
manageable with OpenShift. Indeed, I probably spent more time wrestling
with complexities of data formats and retrieval than I did with the rest
of the code. For the purposes of this post, I’m going to focus on the
application and only deal briefly with the particulars of the USGS data
which I’ll cover in more detail in a future post.

2. Building the Foundation

First we setup the infrastructure. I assume that you have the rhc client
tools and git installed and have a basic understanding of working with
and pushing code to the OpenShift service. The name of the application
is wwos. 

SteveCP’s posts listed above provide some more detail, but here are the
basic steps:

Install Python:

rhc app create -t python-2.6 -a wwos

Use the Flask quickstart (or go to the repository and clone the files

cd wwosgit remote add upstream -m master git:// pull -s recursive -X theirs upstream master

(Ideally Flask would be packaged in a cartridge. We just haven’t done so
yet. However, with the new v2 cartridge architecture, it should now be
quicker and easier to create new cartridges.)

Add MongoDB:

rhc cartridge add mongodb-2.2 -a wwos

Add Cron:

rhc cartridge add cron-1.4 -a wwos

Now… Actually that’s all there is to get things setup. Not bad. Onto

3. Create a File with the Initial Data

The USGS won’t let you pull data associated with all their gauges at one
time; you have to specify at least one “major filter.” It turns out, for
reasons I won’t delve into in this post, that the best approach seems to
be to create a list of two letter lowercase state abbreviations (plus DC
and Puerto Rico) and iterate over the list thusly:

statelist = ["al","ak","az","ar","ca","co","ct","de","dc","fl","ga","hi","id","il","in","ia","ks","ky","la","me","md","ma","mi","mn","ms","mo","mt","ne","nv","nh","nj","nm","ny","nc","nd","oh","ok","or","pa","ri","sc","sd","tn","tx","ut","vt","va","wa","wv","wi","wy","pr"]

for i in statelist:    requesturl = ",1.1&stateCd=" + i +"&parameterCd=00060,00065&siteType=ST"    req = urllib2.Request(requesturl)    opener = urllib2.build_opener()    f =     entry = json.loads(

Each request returns all the gauges in the state of type “ST” (stream).

For each entry, we then iterate through the individual gauges and save
the values.

count = int (len(entry['value']['timeSeries']) - 1)

while count >= 0:

    agaugenum = entry['value']['timeSeries'][count]['sourceInfo']['siteCode'][0]['value']

    asitename = entry['value']['timeSeries'][count]['sourceInfo']['siteName']     alat = entry['value']['timeSeries'][count]['sourceInfo']['geoLocation']['geogLocation']['latitude']

    along = entry['value']['timeSeries'][count]['sourceInfo']['geoLocation']['geogLocation']['longitude']  

    agauge = {     "sitename": asitename,    "pos": [along, alat],    "flow": 0,    "height": 0,    "timestamp": 0,    "statecode": i     }

#output is an empty dictionary created outside all loops

output[agaugenum] = agauge      count = count - 1

A few comments:

  • Yes, the JSON returned by the USGS is quite baroque. That’s why I’m
    saving it for another post.
  • Count is the number of records to iterate over for each state.
  • Longitude and latitude are saved the way they are for reasons that
    will become clear in the next section.
  • Flow, height, and timestamp are placeholders for time-variant data.

Finally, once we’ve iterated through all the states (and all the gauges
within each state), we write out the data to a JSON-ish file.
(Mongoimport is a bit fussy about formats and I couldn’t get the
built-in Python dump functions to work properly.)

fileout = open('gaugesall.json', 'w')

for k in output:     agaugestr = '{ "_id" : "' + k + '",'    asitenamestr = ' "sitename" : "' + output[k]["sitename"] + '" ,'    astatecodestr = ' "statecode" : "' + output[k]["statecode"] + '" ,'    aposstr = ' "pos" : [' + str(output[k]["pos"][0]) + ', ' + str(output[k]["pos"][1]) + '] ,'    aflowstr = ' "flow" : "' + str(output[k]["flow"]) + '" ,'    aheightstr = ' "height" : "' + str(output[k]["height"]) + '" ,'    atimestampstr = ' "timestamp" : "' + str(output[k]["timestamp"]) + '" }'

    outstr= agaugestr + asitenamestr + astatecodestr + aposstr + aflowstr + aheightstr + atimestampstr

    fileout.write(outstr)    fileout.write("\n") fileout.close()

Your file should look like this but with a whole lot more lines.

{ "_id" : "08072760", "sitename" : "Langham Ck at W Little York Rd nr Addicks, TX" , "statecode" : "tx" , "pos" : [-95.646612, 29.86717035] , "flow" : "0" , "height" : "0" , "timestamp" : "0" }{ "_id" : "11055500", "sitename" : "PLUNGE C NR EAST HIGHLANDS CA" , "statecode" : "ca" , "pos" : [-117.141704, 34.11834458] , "flow" : "0" , "height" : "0" , "timestamp" : "0" }

4. Load the Data into MongoDB

Because OpenShift is platform as a service and not infrastructure as a
service there are limited places where you can write data to the server.
One of those locations is app-root/data (under the applications home
directory). That is where we will scp our data file to. 

scp gaugesall.json

Now that we have the file on the server we can SSH in and then run the
mongoimport command:

mongoimport -d gauges -c gaugepoints --type json --file app-root/data/gaugesall.json -h $OPENSHIFT_MONGODB_DB_HOST -u admin -p $OPENSHIFT_MONGODB_DB_PASSWORD

This should import about 9,500 points into a collection called gauge
points in the gauges database.

Now create a 2d index to spatially enable your database.


>use gauges

>db.gaugepoints.ensureIndex( { pos : "2d" } )

(This is why we stored the longitude and latitude as we did previously.)

5. Create a Utility to Update the Database as a Cron Job

We now want write some code to add the flow, height, and creation time
to the gauges. For our purposes here, I’m going to describe doing so
with a python program that gets executed as a cron job by OpenShift. One
could also use virtually identical code that can be executed through
Flask in response to an HTTP request which allows for manual or
scheduled updates from outside OpenShift. I’ll discuss this briefly in
the next section.

Most of the code in this utility is the same as that used to create the
gaugesall.json file so I’m only going to describe the differences.

First, you need to establish a connection to the database.

conn = pymongo.Connection(os.environ['OPENSHIFT_MONGODB_DB_URL']) db = conn.gauges

Then we iterate through the states and get the count for a given state
as before, but now the code within that inner loop is as follows. (The
try/except code was to deal with some weird glitches with some gauges.)

while count >= 0:

    agaugenum = entry['value']['timeSeries'][count]['sourceInfo']['siteCode'][0]['value']

     variablecode = str(entry['value']['timeSeries'][count]['variable']['variableCode'][0]['variableID'])

    try:        variablevalue = str(entry['value']['timeSeries'][count]['values'][0]['value'][0]['value'])    except:        variablevalue = ""

    try:        creationtime = str(entry['value']['timeSeries'][count]['values'][0]['value'][0]['dateTime'])    except:        creationtime = ""

#Gage ht. ft. variableID 45807202

    if variablecode == '45807202':        db.gaugepoints.update({"_id":agaugenum},{"$set":{"height":variablevalue}})

#Discharge cfs variableID 45807197

    if variablecode == '45807197':        db.gaugepoints.update({"_id":agaugenum},{"$set":{"flow":variablevalue}}) 


    count = count - 1     conn.close()

A couple of things to note. 

  • When we created the collection, we saved the gauge number
    (agaugenumber) as _id. This automatically makes it the primary
    index in MongoDB, which makes sense because we are making all the
    changes against that index.
  • The business with the variablecode comes about because each JSON
    record returned  by the USGS Web service is actually just for one
    variable. Thus, for most stream gauges, two records are returned:
    one for the height and one for the flow. (Other variables are

You can now add this utility to your repo/.openshift/cron/daily
directory and push it to OpenShift. (See this post for more information

6. Filling out the Flask Framework

SteveCP discusses Flask in one of the earlier linked

and I won’t repeat what he writes here. As a way of testing things out,
you probably want to write a couple of simple Flask functions. For
example, this function would return JSON showing all the records in the
collection if you go to http://wwos-YOURDOMAIN/

@app.route("/ws/gauges")def gauges():    #setup the connection to the gauges database    conn = pymongo.Connection(os.environ['OPENSHIFT_MONGODB_DB_URL'])    db = conn.gauges

#query the DB for all the gaugepoints    result = db.gaugepoints.find()

#Now turn the results into valid JSON    return str(json.dumps({'results':list(result)},default=json_util.default))

You can also write a function that will update a single state thusly in
response to, say,

@app.route("/ws/gauges/update/state")def updatestate():

   statelist = ["al","ak","az","ar","ca","co","ct","de","dc","fl","ga","hi","id","il","in","ia","ks","ky","la","me","md","ma","mi","mn","ms","mo","mt","ne","nv","nh","nj","nm","ny","nc","nd","oh","ok","or","pa","ri","sc","sd","tn","tx","ut","vt","va","wa","wv","wi","wy","pr"]  #setup the connection to the gauges database    conn = pymongo.Connection(os.environ['OPENSHIFT_MONGODB_DB_URL'])    db = conn.gauges

    i = request.args.get('st')

    requesturl = ",1.1&stateCd=" + i +"&parameterCd=00060,00065&siteType=ST"

Followed by the code we wrote for the earlier update function. (Updates
through the Web service interface seem to be more robust if you can do
them state by state to allow for failures of some requests–easy enough
to do in a script file.)

However, what we really need Flask to do for us is to return the points
within a bounding box defined by longitude/latitude pairs.

#find gauges within a lot/long bounding box passed in as query parameters (within?lat1=45.5&&lon1=-82&lat2=42&lon2=-84)@app.route("/ws/gauges/within")def within():    #setup the connection    conn = pymongo.Connection(os.environ['OPENSHIFT_MONGODB_DB_URL'])    db = conn.gauges

    #get the request parameters    lat1 = float(request.args.get('lat1'))    lon1 = float(request.args.get('lon1'))    lat2 = float(request.args.get('lat2'))    lon2 = float(request.args.get('lon2'))

    #use the request parameters in the query    result = db.gaugepoints.find({"pos": {"$within": {"$box" : [[lon1,lat1],[lon2,lat2]]}}})

    #turn the results into valid JSON    return str(json.dumps(list(result),default=json_util.default))

What’s going on here is that the framework is being passed a request
with query parameters and a result is returned using one of MongoDB’s
geo functions (which is why we had to spatially enable the pos field in
our collection earlier). But where does this query come from? To answer
that, I’m going to show you one more very short chunk of code from our
app and follow where that takes us.

If you were to type http://wwos-YOURDOMAIN/, you’d end up

@app.route("/")def mainapp():    return render_template("index.html")

7. The Map

Flask uses Jinja2 templating and that’s about all I’m going to say on
that subject as our use of templates here is extremely simple. Suffice
it to say that, under your application’s
wsgi directory (where a file
called application calls your customized code), you create a directory
called templates and you put your index.html file there. This means
that if you type http://wwos-YOURDOMAIN/ into a browser, you
get to index.html (by way of Flask). As mentioned earlier, this
application uses Leaflet to display the map and pins. I’m not going to
go through all the details–Leaflet’s API information is pretty
good–but I’ll walk you through the overall flow in index.html leaving
out a lot of the CSS/styling/etc.

First we run the Leaflet JavaScript

 <script src=""></script> 

Then we create a map and add a layer group to that map. (I center it
near Boston. You could write code to try to use your location.)

var map ='map').setView([42.35, -71.06], 10);var markerLayerGroup = L.layerGroup().addTo(map);

We use OpenStreetMaps tiles. (Leaflet lets you use a variety of tile

L.tileLayer('http://{s}{z}/{x}/{y}.png', { maxZoom: 18, attribution: 'Map data &copy; <a href="">OpenStreetMap</a> contributors, <a href="">CC-BY-SA</a> Written by <a href="">Gordon Haff</a>. Running on OpenShift by Red Hat. <a href=""> About.</a>' }).addTo(map);

Now–drumroll please–we tie the whole application together. In response
to appropriate events (the map.on lines), we call getPins , which is
sending an http request back to the application which got us to
index.html in the first place.

function getPins(e){   bounds = map.getBounds(); url = "/ws/gauges/within?lat1=" + bounds.getNorthEast().lat + "&lon1=" + bounds.getNorthEast().lng + "&lat2=" + bounds.getSouthWest().lat + "&lon2=" + bounds.getSouthWest().lng; $.get(url, pinTheMap, "json")

Finally, we draw the pins using the data retrieved from that request.
(We check how far out the map is zoomed because, with over 9,000 points,
the performance becomes unacceptable if you try to draw too many on the
screen. 8–which corresponds to an area covering a couple of
average-sized states on most devices–seemed about right.) 

River Gauges Image

8. An Application is Never Really Done

As I mentioned earlier, I’ll be writing another post that gets into some
details about the USGS data and some of the challenges I encountered and
(mostly) overcame dealing with it. Beyond this particular dataset, you
could also use this same basic code to write applications that showed
many manner of places, whether points of interest or something else.

One thing that I should add to the application is the ability to
optionally geolocate to where the user is located. For reasons related
to how some browsers don’t always throw locationerror events, this
turned out to be harder to do well than anticipated so I left it out for

Coming back to OpenShift, one thing I hope you take away is that–while
this app certainly has some complexities–setting up the basic
infrastructure was pretty straightforward and let you pretty much jump
right into retrieving data and coding. At the same time, OpenShift gave
me lots of options about how to go about developing this applications,
from language to database to framework.

Here’s the code on GitHub.

What’s Next?

MongoDB, OpenShift Online, Python
Comments are closed.