Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Local geocoder

Build Status

Reverse geocodes lng, lat pairs into country codes (plus State and Counties within the US). Runs locally, with no external dependancies, and is fast enough for large batch jobs (10,000 reverse geocodes per minute using the JRuby extention).


gem install local-geocoder

Lib usage

require 'local_geocoder' 

geo =
result = geo.reverse_geocode( -122.4194155, 37.7749295 )
p, result.state, result.county

> United States of America (USA), California (CA), San Francisco

Command line usage

  local_geocode [options] file

> echo "-122.4194155, 37.7749295" | local_geocode 
> United States of America (USA), California (CA), San Francisco
  --template, -t <s>:   The regex used to parse lng,lat paris from the input
                        stream (default: (?<lng>\-?\d+.?\d+)[,\t
       --version, -v:   Print version and exit
          --help, -h:   Show this message


Why use gem this instead of geocoder X.

Most geocoder gems (actually all last time that I checked) use an external web service to do their reverse geocoding (such as Google, Yahoo!, etc). And all have some sort of limit on how many reverse geocodes you can do per day. Also calling an external web service is slow. This gem does everything locally, so it runs fast, and doesn't have any limits on how many reverse geocodes you can do. The tradeoff is that it only provides coarse results. So if you have a large number of lng, lats that need to be translated into countries, then this gem should work for you. Otherwise you're probably better off using another gem.

How do I get a street address?

You don't. See 'Why use gem this instead of geocoder X'.

JRuby extension

If you're running JRuby then a java native extension is used. No need to do anything - it should be picked up automatically. For large batch jobs performance will be ~10X faster. If performance is a concern (i.e. you're geocoding a large batch of lng, lats) then I suggest you use JRuby to run this gem, as performance should be in the ballpark of native code.

Contributing and issues

I expect there's still some issues with country borders (the dataset we've based our's off is fairly coarse for geocoder purposes). If you find a country (or state/county) that is being incorrectly geocoded then raise an issue on the github repo and provide the lng/lat along with what result you were expecting. Also please note that several of the borders are still disputed.

Other platforms

Richard Hopton has put together a .NET port here:


Country, State, and County boundaries are based on an original dataset at


Reverse geocodes lng,lat pairs into Country codes (plus State and County for the US only). Runs locally, with no dependancies, and is fast enough for large batch jobs




No releases published


No packages published
You can’t perform that action at this time.