geocoder

Geocoder
========

**Complete geocoding solution for Ruby.**

[![Gem Version](https://badge.fury.io/rb/geocoder.svg)](http://badge.fury.io/rb/geocoder)

Key features:

* Forward and reverse geocoding.
* IP address geocoding.
* Connects to more than 40 APIs worldwide.
* Performance-enhancing features like caching.
* Integrates with ActiveRecord and Mongoid.
* Basic geospatial queries: search within radius (or rectangle, or ring).

Compatibility:

* Ruby versions: 2.5+ and JRuby.
* Databases: MySQL, PostgreSQL, SQLite, and MongoDB.
* Rails: 5.x, 6.x, 7.x and 8.x.
* Works outside of Rails with the `json` (for MRI) or `json_pure` (for JRuby) gem.


Table of Contents
-----------------

Basic Features:

* [Basic Search](#basic-search)
* [Geocoding Objects](#geocoding-objects)
* [Geospatial Database Queries](#geospatial-database-queries)
* [Geocoding HTTP Requests](#geocoding-http-requests)
* [Geocoding Service ("Lookup") Configuration](#geocoding-service-lookup-configuration)

Advanced Features:

* [Performance and Optimization](#performance-and-optimization)
* [Advanced Model Configuration](#advanced-model-configuration)
* [Advanced Database Queries](#advanced-database-queries)
* [Geospatial Calculations](#geospatial-calculations)
* [Batch Geocoding](#batch-geocoding)
* [Testing](#testing)
* [Error Handling](#error-handling)
* [Command Line Interface](#command-line-interface)

The Rest:

* [Technical Discussions](#technical-discussions)
* [Troubleshooting](#troubleshooting)
* [Known Issues](#known-issues)
* [Reporting Issues](https://github.com/alexreisner/geocoder/blob/master/CONTRIBUTING.md#reporting-bugs)
* [Contributing](https://github.com/alexreisner/geocoder/blob/master/CONTRIBUTING.md#making-changes)

See Also:

* [Guide to Geocoding APIs](https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md) (formerly part of this README)


Basic Search
------------

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

```ruby
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:

```ruby
results = Geocoder.search([48.856614, 2.3522219])
results.first.address
# => "Hôtel de Ville, 75004 Paris, France"
```

You can also look up the location of an IP address:

```ruby
results = Geocoder.search("172.56.21.89")
results.first.coordinates
# => [30.267153, -97.7430608]
results.first.country
# => "United States"
```

**The success and accuracy of geocoding depends entirely on the API being used to do these lookups.** Most queries work fairly well with the default configuration, but every application has different needs and every API has its particular strengths and weaknesses. If you need better coverage for your application you'll want to get familiar with the large number of supported APIs, listed in the [API Guide](https://github.com/alexreisner/geocoder/blob/master