Need help with acts_as_geocodable?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

205 Stars 42 Forks Other 199 Commits 2 Opened issues


Simple geocoding for Active Record models

Services available


Need anything else?

Contributors list


Gem Version Build Status Code Climate Code Coverage Dependency Status

actsasgeocodable helps you build geo-aware applications. It automatically geocodes your models when they are saved, giving you the ability to search by location and calculate distances between records.

Beginning with version 2, we require Rails 3. Use one of the 1.0.x tags to work with Rails 2.3.

We've adopted the ARel style syntax for finding records.


event = Event.create(
  street: "777 NE Martin Luther King, Jr. Blvd.",
  locality: "Portland",
  region: "Oregon",
  postal_code: 97232

event.geocode.latitude # => 45.529100000000 event.geocode.longitude # => -122.644200000000

event.distance_to("49423") # => 1807.66560483205

Event.origin("97232", within: 50)

Event.origin("Portland, OR").nearest


Install as a gem

gem install acts_as_geocodable

or add it to your Gemfile

gem "acts_as_geocodable"

Graticule is used for all the heavy lifting and will be installed too.


Before October 2008, precision wasn't included in the

model. Make sure you add a string precision column to your geocode table if you're upgrading from an older version, and update Graticule.

Also, if you're upgrading from a previous version of this plugin, note that

has been renamed to
to be consistent with Graticule 0.2. Create a migration that has:
rename_column :geocodes, :city, :locality

Also remember to change your mapping in your geocodable classes to use the

key instead of
class Event < ActiveRecord::Base
  acts_as_geocodable address: { street: :address1, locality: :city, region: :state, postal_code: :zip }


Create the required tables

rails generate acts_as_geocodable
rake db:migrate

Set the default geocoder in your environment.rb file.

Geocode.geocoder = Graticule.service(:yahoo).new("your_api_key")

Then, in each model you want to make geocodable, add

class Event < ActiveRecord::Base

The only requirement is that your model must have address fields. By default, actsasgeocodable looks for attributes called street, locality, region, postalcode, and _country. To change these, you can provide a mapping in the

class Event < ActiveRecord::Base
  acts_as_geocodable address: { street: :address1, locality: :city, region: :state, postal_code: :zip }

If that doesn't meet your needs, simply override the default

method in your model, and return a
with those attributes set.

actsasgeocodable can also update your address fields with the data returned from the geocoding service:

class Event < ActiveRecord::Base
  acts_as_geocodable normalize_address: true

IP-based Geocoding

actsasgeocodable adds a

method in your controllers that uses to guess remote users location based on their IP address.
def index
  @nearest = Store.origin(remote_location).nearest if remote_location
  @stores = Store.all

Keep in mind that IP-based geocoding is not always accurate, and often will not return any results.


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

To Do

  • configurable formulas

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.