firstworks Technologies Services Examples
About Documentation Supported API's Buy Online Support
Introduction

The firstworks Weather Cache for Linux is a light, simple, caching proxy, targeted for use with Weather API's.


Weather API's provide web-services that allow you to display current conditions, forecasts or historical weather information on your website or mobile app.

But, downloading weather data from across the internet takes time. Fetching it on the server-side while building a page can slow page loads significantly. Fetching it on the client-side allows the rest of the page to load quickly but introduces Cross-Site Scripting (XSS) issues.

Weather API's also have request count limits. When you exceed the limit you get throttled, blocked, or have to pay more. A weather badge on a busy site can become expensive.

The firstworks Weather Cache sits between your application and the Weather API's web-service, forwarding requests from your application and receiving results from the web-service. Each result is cached in a local database and tagged with an expiration date before being returned to your application. If the cache receives a request for the same data prior to the expiration date, the result is fetched from the database, rather than from the web-service.

  • When results are fetched from the local database rather than from across the internet, page load times are improved dramatically.
  • Since duplicate requests are resolved locally, the number of requests to the Weather API are minimized.
  • Cross-Site Scripting issues are avoided because the domain of the cache is the same as the rest of your site.

The Weather Cache is designed to be API-agnostic. You can develop applications using the Weather API of your choice or seamlessly integrate the cache into existing applications.

However, the cache does a few semi-intelligent things to work around some common cache-defeating issues.

  • Parameters are normalized so subtly different requests for the same information will be recognized as the same request.
  • Mobile devices are "snapped" to a grid. Successive requests from mobile devices tend to send slightly different latitudes and longitudes, especially if the device is moving. When snapped to a grid, the location of the device only changes when it has has moved far enough to snap to a different grid point. Multiple mobile devices in close proximity snap to the same grid point.

The Weather Cache is also designed for compatibility. It is distributed as a self-contained, statically-linked x86 Linux binary and should be compatible with any x86 or x86_64 Linux platform. Its only requirements are a web server configured to support CGI's and read/write access to the /var/tmp directory.


Installation

Click "Buy Online" above or this link and follow the instructions for purchasing the Firstworks Weather Cache for Linux online.

Follow the check-out process. You should receive an email with a link to download your purchase.
Click that link to download the file weathercache-1.0.tar.gz.

Extract the file and enter the directory created by the extraction:

tar xfz weathercache-1.0.tar.gz
cd weathercache-1.0

Read the license:

more LICENSE

It's basically a single-instance-on-a-single-node license. For custom licensing terms, see Support.

If you agree with the terms of the license, copy the executable into the document root of your website.

cp weathercache.cgi my_website_document_root

Configuration

The Weather Cache itself doesn't require any configuration. But you must configure your web server to support CGI's if it's not already configured that way.

For the Apache web server, this usually consists of uncommenting the AddHandler line for cgi-script and adding the ExecCGI option to the section for your DocumentRoot.

httpd.conf
...
AddHandler cgi-script .cgi
...
<Directory "/var/www/html">
...
    Options Indexes FollowSymLinks ExecCGI
...
</Directory>
...

Be sure to restart the web server after reconfiguring it.


Using the Cache

To use the firstworks Weather Cache, prepend its URL to your Weather API calls.

For example, to use the (fictitious) Weather API http://api.wservice.com/current.asp you might make a request like:

http://api.wservice.com/current.asp?q=Atlanta,ga&mode=json&apikey=a1b2c3d4e5

If your domain name is mydomain.com, then to use the Weather Cache, you would update the call above to:

http://mydomain.com/weathercache.cgi/api.wservice.com/current.asp?q=Atlanta,ga&mode=json&apikey=a1b2c3d4e5

That's all there is to it.

Of course, you can move weathercache.cgi to a different location as long as you update the URL to point to the new location.


Parameters

The Weather Cache supports a few parameters. These parameters control cache behavior and are not passed on to the Weather API.

wcexpire

By default, cached responses expire after 15 minutes but this can be overriden on a per-request basis. To override the expiration for a specific request, set the wcexpire parameter to the number of seconds that you want it to expire after.

For example, to set the request above to expire after one hour (3600 seconds), you would update the call to:

http://mydomain.com/weathercache.cgi/api.wservice.com/current.asp?q=Atlanta,ga&mode=json&apikey=a1b2c3d4e5&wcexpire=3600

wcgridsnap

By default, latitudes and longitudes are snapped to the nearest 1/8th of a degree. To override this behavior, set the wcgridsnap parameter to the number of thousandths of a degree that you want them to snap to.

For example, a request that snaps to the nearest 1/4th (250/1000ths) of a degree would look something like this:

http://mydomain.com/weathercache.cgi/api.wservice.com/current.asp?q=33.7550,-84.3900&mode=json&apikey=a1b2c3d4e5&wcgridsnap=250

Values of wcgridsnap greater than 1000 are rounded down to 1000. To disable grid-snap altogether, set wcgridsnap to 0.


Limitations

The current version of the Weather Cache does have a few limitations.

  • It only runs on Linux.
  • It only runs on x86 and x86_64 platforms.
  • It cannot connect to Weather API's via https, only via http.
  • It does not support Weather API's which require data to be POST'ed (eg. SOAP API's).
  • It does not support Weather API's which require special HTTP headers (eg. to pass the API key).

These issues will be resolved in future releases.

Copyright 2014 - David Muse - Contact