earth_tools is a wrapper around the wonderful earthtools.org webservices, which allows you to determine the sea level height, time zone, and surise/sunset times from a set of coordinates.
- Supports Ruby 1.9.3
Will be testing on other versions in the future.
Add to your Gemfile:
and then bundle your gemfile:
and you are done!
The run down of the 3 major functions available
# API result = EarthTools.time_zone(latitude, longitude) # Example result = EarthTools.time_zone(40.71417, -74.00639) # New York City result.iso_time # => 2012-06-14 12:56:40 -0500 result.utc_offset # => -5 result.utc_time # => 2012-06-14 17:56:40 +0000
Height above/below sea level
# API result = EarthTools.height(latitude, longitude) # Example result = EarthTools.height(52.4822, -1.8946) # Birmingham, AL result.meters # => 141 result.feet # => 462.6 result.height # => 462.6 (when EarthTools::Configuration.units is set to :english units)
# API result = EarthTools.sunrise_sunset(latitude, longitude, month, day, timezone, dst) # Example result = EarthTools.sunrise_sunset(40.71417, -74.00639, 12, 4, -5, 0) # New York City, December 4th result.sunrise # => 2012-12-04 07:05:50 -0500 result.sunset # => 2012-12-04 16:26:59 -0500
# Configure block (set to defaults) EarthTools.configure do |config| config.always_raise =  # Add any errors that you would like to be custom handled, see "Error handling" section below config.cache = nil # Cache object (must respond to #, #=, and #keys) config.cache_prefix = "earth_tools:" # Prefix to all cache keys config.timeout = 3 # Timeout in seconds config.units = :english # Also, can specify :metric end # Static call EarthTools::Configuration.timeout = 5 # Set timeout to 5 seconds
Earth Tool API restrictions
Earth Tools imposes some usage restrictions that are duplicated below (these restrictions may not be kept up-to-date, so please check the website):
- You must not make more than 1 (one) request per second to these webservices.
- You must cache results if you believe that you will need to make another identical request within any 24-hour period.
- You must delete any cached data when you no longer need it and in any case after 14 days. You should then make a new request for the data in line with the previous two rules. If you wish to keep access to data I am able to license the data for use in this way.
Caching (TBD update this section)
It is recommended to cache retrieved data when relying on an external service. You can configure a cache store:
EarthTools::Configuration.cache = Redis.new
The cache store can be any object that supports the following methods:
|`store#(key)`||retrieves a value|
|`store#=(key, value)`||stores a value|
|`store#keys`||lists all keys|
Even a plain Ruby hash will work, though it's not a great choice (cleared out when app is restarted, not shared between app instances, etc).
You can also set a custom prefix to be used for cache keys:
EarthTools::Configuration.cache_prefix = "..."
By default the prefix is
If you need to expire cached content:
EarthTools.cache.expire("http://...") # expire cached result for a URL EarthTools.cache.expire(:all) # expire all cached results
Do not include the prefix when passing a URL to be expired. Expiring
:all will only expire keys with the configured prefix (won't kill every entry in your key/value store).
By default Earth Tools will rescue any exceptions raised by calls to the webservice and return an empty array (using warn() to inform you of the error). You can override this and implement custom error handling for certain exceptions by using the
EarthTools::Configuration.always_raise = [SocketError, TimeoutError]
Issues & contributing
No outstanding issues right now. Please post any issues to the issues queue on github.
I would love to see this functionality brought into the
geocoder gem or similar in the future.
License and attributions
This gem's structure and design borrows heavily from
geocoder, so thanks to its author. Find me on twitter @maxckramer.