Stormpulse API

UPDATE: January 26, 2011

Effective immediately the Stormpulse Maps API will become part of our Enterprise plans for internal (intranet) use only.  We are no longer selling API keys for public use.  If you have a paid, public API subscription, your API key will continue to work until the end of your subscription.  Please contact Stormpulse Support (support@stormpulse.com) for details.

UPDATE: January 11, 2011

NOTE: This was originally published as an email to our affiliates, sent in December 2010.  We are posting it to the blog today to serve as a permanently-visible public notice.

Since launching the Stormpulse website in 2007, we’ve had to make changes along the way to ensure that Stormpulse will remain viable and useful for the millions of visitors that have benefited from our storm maps.

As you may remember, during the 2010 hurricane season we sent an email to our affiliates explaining that we may have to deactivate certain API keys during peak times. Fortunately we only needed to do this in a handful of cases, and we were able to finish the 2010 season with no further slowdowns due to demand, while still supporting over 1,000 free maps users.

As we look ahead to 2011, it is clear we can’t continue to support and develop the free program while also meeting the demands that have been placed on us by thousands of requests for additional development (mobile apps, real-time updates) that will cost us significant sums of time and money.

As a result, and after thinking it through, we’ve decided to discontinue the free Stormpulse API program. This change will become effective on January 17, 2011. After this date, your Stormpulse free API key will cease to work unless you choose to upgrade to a paid subscription.

There are three paths to upgrade to a paid subscription, depending on your existing account and the type of site you are running:

  • If you started using the Stormpulse API before we required registration (back when we handed out API keys via email), you should simply visit our web publishing products page to register for one of the new paid plans. (If you have a Stormpulse Pro account, make sure you are signed out of that).
  • If you have a Free Maps account and your site is open to the public, fill out this form and we will arrange a subscription plan for you.
  • If you have a Free Maps account and you are signed in and your site is closed to the public (intranet, username/password protected), you may go here to upgrade to a monthly or yearly Stormpulse Maps Intranet account.

Please feel free to contact us with any questions you may have as we take this important step.

API DOCUMENTATION:

Here’s an example of the HTML you would then need to place on your web page, where ‘ABCDEF’ should be replaced with your own API key:

<script src="http://www.stormpulse.com/api/maps/current/?key=ABCDEF" type="text/javascript"></script>

The ‘current’ phrase in the URL means that this will pull back a map showing current tropical cyclone activity in the Atlantic basin. To highlight a particular storm (handy when multiple storms are active), simply change this phrase to a different phrase, such as ‘edouard’ or ‘tropical-storm-edouard-2008’ or even ‘five’ (since Edouard is the fifth Tropical Depression of the year):

<script src="http://www.stormpulse.com/api/maps/tropical-storm-edouard-2008/?key=ABCDEF" type="text/javascript"></script>

<script src="http://www.stormpulse.com/api/maps/five/?key=ABCDEF" type="text/javascript"></script>

<script src="http://www.stormpulse.com/api/maps/tropical-depression-five-2008/?key=ABCDEF" type="text/javascript"></script>

You can even show storms from yesteryear using the same syntax, for example the legendary Hugo:

<script src="http://www.stormpulse.com/api/maps/hurricane-hugo-1989/?key=ABCDEF" type="text/javascript"></script>

Or perhaps you can only remember the name of an infamous storm; often you can get away with just using the name:

<script src="http://www.stormpulse.com/api/maps/gilbert/?key=ABCDEF" type="text/javascript"></script>


SETTING THE STORM BASIN

Since the beginning of the 2009 season, Stormpulse.com has provided coverage of the Northeast Pacific Basin as well as the Atlantic.  The API map defaults to the Atlantic basin, so if you would like to focus on the latest activity in the Pacific, you need to add a reference to Pacific into your URL, like so:

<script src="http://www.stormpulse.com/api/maps/pacific/current/?key=ABCDEF" type="text/javascript"></script>

The same rules that govern choosing Atlantic seasons and storms also applies to the Pacific. For example, to bring up a map of Hurricane Iniki, you would use the following code:

<script src="http://www.stormpulse.com/api/maps/pacific/hurricane-iniki-1992/?key=ABCDEF" type="text/javascript"></script>

And to bring up the entire 2008 Northeast Pacific Basin hurricane season, you would use:

<script src="http://www.stormpulse.com/api/maps/pacific/2008-hurricane-season/?key=ABCDEF" type="text/javascript"></script>


NEW!
JAVASCRIPT API REFERENCE

In addition to the ability to embed maps of various types and sizes, the Stormpulse API includes JavaScript objects and functions that allow you to control the display of the map and add custom markers (locations).

The syntax (the way the code is written) is almost identical to that of Google Maps, so if you have experience with GMaps, you should feel right at home with the Stormpulse objects as well.

To control the map using JavaScript, we must define a function called onStormpulseReady. This function is called by the map when the map has finished loading and is ready to be manipulated. Here’s how we do that:

function onStormpulseReady() {
// Your code goes here.
}

Let’s replace that “Your code goes here” with something more interesting, shall we? First, we need to create a reference (variable) to the map. The embedded map has an id of “stormpulse”, so here’s what we need to write:

function onStormpulseReady() {
var map = new SP.Map('stormpulse');
}

Now that we have a reference to the map, we can begin turning layers on and off, like so:

function onStormpulseReady() {
var map = new SP.Map('stormpulse');
map.hideClouds();
map.showRadar();
}

As of API v0.1a, the following layer functions are available (all of them are called without any arguments):

 

  • hideClouds
  • showClouds
  • hideRadar
  • showRadar
  • hideSevereWeather
  • showSevereWeather

 

In addition to turning layers on and off, we can also create and add map markers, like so:

function onStormpulseReady() {
var map = new SP.Map('stormpulse');
var marker = new SP.Marker(new SP.LatLng(27.5, -88.1), {"name": "S.S. Minnow"});
map.addOverlay(marker);
}

In addition to “name”, you may also pass in the following options to the marker object:

 

    • typ
    • address1
    • address2
    • city
    • postalCode
    • link
    • linkTxt
    • color

: in hexadecimal color format, for example 0xFF000 for red, 0x00FF00 for green, etc.

    • size

: the font-size of the label, the default is 10.

    • minZoom

: the Stormpulse map has 6 zoom levels. If you set this to 4, your marker will only show up once you are at zoom level 4 or greater. You can use this to manage the complexity of visualizing a lot of close locations at the same time.

 

After creating a map marker, you can update its position:

function onStormpulseReady() {
var map = new SP.Map('stormpulse');
var marker = new SP.Marker(new SP.LatLng(27.5, -88.1), {"name": "S.S. Minnow"});
map.addOverlay(marker);
marker.setLatLng(new SP.LatLng(27.55, -88.3));
}

This is an extremely useful way to visualize your assets on the Stormpulse map as their real-world locations change.


SEVERE WEATHER COVERAGE

Stormpulse covers severe weather alerts (watches and warnings) issued by the National Weather Service. You can embed a map showing the latest watches and warnings for your region, city, or zip code just by changing the URL in the JavaScript tag.

For example, to show a state-level view of the Lone Star state:

<script src="http://www.stormpulse.com/api/maps/severe/tx/?key=ABCDEF" type="text/javascript"></script>

To show a close-up of Hartford, Connecticut:

<script src="http://www.stormpulse.com/api/maps/severe/ct/hartford?key=ABCDEF" type="text/javascript"></script>

Or to show what’s going on in Beverly Hills:

<script src="http://www.stormpulse.com/api/maps/severe/90210/?key=ABCDEF" type="text/javascript"></script>

Or to show a national view of the United States:

<script src="http://www.stormpulse.com/api/maps/severe/us/?key=ABCDEF" type="text/javascript"></script>

The map will automatically center and zoom to give a ‘reasonable’ overview of the area in scope. However, feel free to send us your feedback as you find your tastes differ from ours. More customizations are always in the works.

SETTING THE HEIGHT AND WIDTH

You can specify the height and width of the map returned by the JavaScript tag by passing in an extra parameter (or two) to the URL–namely ‘height’ and ‘width’, for example:

<script src="http://www.stormpulse.com/api/maps/current/?key=ABCDEF&height=600&width=720" type="text/javascript"></script>

You can even request a full-screen map (one that consumes the entire browser window) by requesting height=100%, width=100%, for example:

<script src="http://www.stormpulse.com/api/maps/current/?key=ABCDEF&height=100%&width=100%" type="text/javascript"></script>


SETTING THE WMODE

One of the more advanced settings available to users of the embedded map is the ability to set the wmode parameter on the Flash app. This value controls whether or not HTML elements are visible above or behind the map. The three acceptable values are ‘window’ (default), ‘opaque’, and ‘transparent’. You can see examples of each here. Here’s an example of setting the parameter in the API call:

<script src="http://www.stormpulse.com/api/maps/current/?key=ABCDEF&wmode=opaque" type="text/javascript"></script>

This feature is somewhat “use at your own risk”, as we’ve heard of problems using certain wmodes with certain browsers (see: http://is.gd/kCCd). Please feel free to report what you encounter and let us know if we can do anything differently on our end to help.

FUTURE UPGRADES

The nice thing about this service, in addition to it being free, is that you will automatically benefit from enhancements we plan to roll out to the map in the near future, including the tracking of developing systems (invests/disturbances) in addition to those that have gained tropical depression status.

Thanks for using Stormpulse.