README.md

Geocoder

A complete geocoding solution for Ruby.

Key features:

• Forward and reverse geocoding, and IP address geocoding.
• Connects to more than 40 APIs worldwide.
• Performance-enhancing feaures like caching.
• Advanced configuration allows different parameters and APIs to be used in different conditions.
• Integrates with ActiveRecord and Mongoid.
• Basic geospatial queries: search within radius (or rectangle, or ring).

Compatibility:

• Supports multiple Ruby versions: Ruby 1.9.3, 2.x, and JRuby.
• Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher).
• Supports Rails 3, 4, and 5. If you need to use it with Rails 2 please see the rails2 branch (no longer maintained, limited feature set).
• Works very well outside of Rails, you just need to install either the json (for MRI) or json_pure (for JRuby) gem.

Table of Contents

Basic Features:

• Basic Search
• Geocoding Objects
• Geospatial Database Queries
• Geocoding HTTP Requests
• Geocoding Service ("Lookup") Configuration

Advanced Features:

• Performance and Optimization
• Advanced Model Configuration
• Advanced Database Queries
• Batch Geocoding
• Testing
• Error Handling
• Command Line Interface

The Rest:

• Technical Discussions
• Troubleshooting
• Known Issues
• Reporting Issues
• Contributing

See Also:

• Guide to Geocoding APIs (formerly part of this README)

Basic Search

In its simplest form, Geocoder takes an address and searches for its latitude/longitude coordinates:

results = Geocoder.search("Paris")
results.first.coordinates
=> [48.856614, 2.3522219]  # latitude and longitude

The reverse is possible too. Given coordinates, it finds an address: