Skip to content
Ruby API wrapper around
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status Dependency Status Code Climate

earth_tools is a wrapper around the wonderful 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.

Installation instructions

Add to your Gemfile:

gem 'earth_tools'

and then bundle your gemfile:

bundle install

and you are done!


The run down of the 3 major functions available

Time zone

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

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)

Sunrise/sunset times

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
# 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):

  1. You must not make more than 1 (one) request per second to these webservices.
  2. You must cache results if you believe that you will need to make another identical request within any 24-hour period.
  3. 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 =

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 earth_tools:

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).

Error handling

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 :always_raise option:

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.

Something went wrong with that request. Please try again.