Graticule is a geocoding API for looking up address coordinates and performing distance calculations, supporting many popular APIs.
Clone or download
Pull request Compare This branch is 82 commits behind collectiveidea:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Graticule is a geocoding API for looking up address coordinates. It supports many popular APIs, including Yahoo, Google, Yandex, and


require 'rubygems'
require 'graticule'
geocoder = Graticule.service(:google).new "api_key"
location = geocoder.locate "61 East 9th Street, Holland, MI"

Distance Calculation

Graticule includes 3 different distance formulas, Spherical (simplest but least accurate), Vincenty (most accurate and most complicated), and Haversine (somewhere inbetween).

geocoder.locate("Holland, MI").distance_to(geocoder.locate("Chicago, IL"))
#=> 101.997458788177

Command Line

Graticule includes a command line interface (CLI).

$ geocode -s yahoo -a yahookey Washington, DC
Washington, DC US
latitude: 38.895222, longitude: -77.036758

Mailing List

Join us on the mailing list.


In the spirit of free software, everyone is encouraged to help improve this project.

Here are some ways you can contribute:

  • using alpha, beta, and prerelease versions
  • reporting bugs
  • suggesting new features
  • writing or editing documentation
  • writing specifications
  • writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
  • refactoring code
  • closing issues
  • reviewing patches

Submitting an Issue

We use the GitHub issue tracker to track bugs
and features. Before submitting a bug report or feature request, check to make sure it hasn’t already
been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
bug report, please include a Gist that includes a stack trace and any
details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

1. Fork the project.
2. Create a topic branch.
3. Implement your feature or bug fix.
4. Add specs for your feature or bug fix.
5. Run bundle exec rake. If your changes are not 100% covered and passing, go back to step 4.
6. Commit and push your changes.
7. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)