To the victor go the spoils. Somewhere in Central America.

Surf Hacking (customized surf reports in my inbox)

A couple of years ago, MagicSeaweed (MSW) opened up their swell data via an API[1]. MSW is a free site that hosts a huge number of swell reports that cover the whole world, and is used by surfers everywhere.

Using their API, I wrote a simple program to notify me and a few buddies when decent waves were headed to a number of spots I had my eye on.

Scoring waves while I’m embedded deep in the city, without a car, requires a more tactical approach.

Why? Well, most people have a local break. They live near the beach and pop in before and after work. They follow local charts and generally know when swell is on the way. I, however, live in New York. Scoring waves while I’m embedded deep in the city, without a car, requires a more tactical approach. I need a tool to tell me when waves are headed my way. It’s also useful to track waves in Central America and the Caribbean — convenient locations for last minute vacations.

This little utility has stood up for over two years without any cost or maintenance required on my part — a pretty impressive achievement these days. It’s one of the more useful tools I’ve written, and best of all, everything about it is free.

How It Works

I wrote a script using node.js.

node.js: a scripting platform

Node is an open source platform that supports scripts written in JavaScript. I could choose any language I liked, and I chose JavaScript.

OK so back to my script. It’s called msw-api.

Given some spot identification number (assigned by MSW[2]), it reaches out to MSW to grab the latest swell data.

MagicSeaweed: Supplier of worldwide swell data

The script then supports querying of this data based on: size (swell height), power (period), shape (wind intensity & direction) and stars (which is basically the MSW secret sauce for overall swell quality).

The queries check size, power, shape and stars along with a minimum number of times they must occur in a row in order to be successful.

Swell data includes spurious results from time-to-time — typically pulses of good conditions that occur periodically. To combat this, I added one more feature — a sequence number. The queries check size, power, shape and stars along with a minimum number of times they must occur in a row in order to be successful.

The script lives on Github. A free service that hosts open source software.

Github: Code hosting

Now, I have another script, it’s called msw-subscribe. It can be run from the command line and its job is to use msw-api and then to email out reports to unsuspecting surfers when swell is on the way. Email isn’t something I want to deal with myself — so I use SendGrid and get an email service for free[3].

SendGrid: Email as a service

I host msw-subscribe on a platform supplied by Heroku. They charge by the amount of CPU (brain power) & RAM (memory) scripts use in hours per month.

Heroku: Platform hosting as a service

Heroku supports a Scheduler. It’s a little plugin that runs my script on a custom schedule. I’ve set it to run each night at 10pm ET.

Scheduler plugin for Heroku

Because my script only runs once a night for an extremely short period of time, I never reach the threshold of being charged by Heroku.

What It Looks Like

A customized swell report from Nosara, Costa Rica

This an example email in my Inbox right now — you can see everything matching my criteria:

  • 3' min height
  • 14 second period
  • max wind 20mph
  • 3 stars or greater
  • and all of this for occurring 3 or more times

Running it, looks something like this:

Code for the curious

Some Things to Keep In Mind

  1. There is no GUI. I write Graphical User Interfaces (GUI) as a job, and frankly, they are a lot of upkeep. Why bother for something as trivial as this where I set it up and forget?
  2. It is brittle. If MSW change their API (and it has been in beta for two years after all), then I’m going to have to rewrite it.
  3. It is limited. When I first wrote it, MSW were letting through two weeks worth of data. Soon after, they dropped it to 5 days[4] — which isn’t much time to arrange a flight. A while back I asked them to expose water temps but I never got a response.

It is quite ironic that of all the complex pieces of software I’ve written over the years, this little utility would be one of the most successful. It has very little ambition, and to this day, I’m quite amazed how useful it still is.

Of course MSW or one of their competitors could easily just add customized swell reports to their offerings. If they did I’d happily sunset this little guy for something more thorough. In the meantime, I’ll enjoy my own daily reports.

Interested in receiving some alerts yourself? Let me know with a response below.
[1] API stands for Application Programming Interface. Its a convoluted way of saying how computer programs talk together.
[2] You can find the spot IDs by looking up the spot and checking the URL, like this one. I did find the MSW undocumented spot lookup, but after some exasperating emails with them, I decided it wasn’t worth “violating” their terms of service.
[3] As long as I stay below their 12,000 emails per month limit!
[4] MSW are a company setup in the UK, and it shows at times. In all my dealings with them, they have been adamant that I not create a competing product. I sometimes don’t know why they even bothered opening their data up, as they have showed me (and by extrapolation, the development community) very little in the way of support.