My New Web Service: River Runner

In my spare time, when I’m not trying to be a web developer, I enjoy whitewater kayaking. Here’s a photo of me kayaking a river out in West Virginia a few years ago. It’s great fun.

One question every kayaker asks before heading out for the next adventure is: “Is the river up?” IOW, is the level of the water high enough for a good day of boating?

Luckily, that question is easy to answer in today’s modern, digitally-connected world. You see, there are 100’s, if not 1000’s, of realtime water level gauges on the rivers across the U.S. and a few government agencies, like the National Weather Service, provide those realtime data for public use.

This post is about the web service I created to pull water level data from the NWS. In a future post, I’ll write about the WordPress widget and Amazon Alexa skill I created to use this service.

REST or SOAP or Whatever

For some reason, I spent way too much time trying to decide if I was going to create a REST or SOAP service. I thought it would be cool to follow some standard, but I ultimately decided to just go with “whatever,” wrote my own solution, and avoided the overhead of both.

Yeah, I know. It was probably the wrong decision, but I just wasn’t getting anywhere and wanted to move on.

The Data Source

In the beginning, I considered not creating the web service layer. The National Weather Service provides the water level data in a wonderfully simple XML format. I could have simply pulled the data straight into my WordPress widget, but I wanted to do more than just display the raw river level and it didn’t make sense to write that logic twice – once in the widget and once in the Alexa skill, so a web service was the solution for me.

For the data itself, there were a few extra bits I used, but the key data points were the <valid> and <primary> elements inside <datum>:

    <valid timezone="UTC">2016-09-01T00:00:00-00:00</valid>
    <primary name="Stage" units="ft">2.43</primary>
    <secondary name="Flow" units="kcfs">0.0145</secondary>

The Code

Once I decided to go simple on the format and understood the data I needed, creating the service was relatively simple. I think I wrote and tested the whole thing in one, not-too-long coding session. You can view the source code in my Bitbucket repository.

Now, I wouldn’t call it a model of great coding, but it does work.

I used simplexml_load_file to pull in the XML and it was easy to grab the values I needed. After working with the data, I added that “little extra” I wanted and then used json_encode to package up the output. Again, super simple.

I also, with the help of a few code examples I forgot to document, created the option to output the results in XML. Probably not necessary, but seemed like a nice thing to do.

Here are the two outputs of this service:

Accessing The Service

The tricker part of this project was making it available online. I decided I would create a “service” subdomain and then serve this web service via that subdomain.

I had never setup a publicly-accessible subdomain before, so it took me a little while to configure my Linode DNS settings and then properly set up a new NGINX server block, but after a few stumbles, I got it all working.


So, that’s the story on my web service. Again, you can review the code in my Bitbucket repository, if you like.

My next post will be about my WordPress widget and Alexa Skill that use this service.