Metadata-Version: 2.0
Name: geocoder
Version: 1.31.0
Summary: Geocoder is a simple and consistent geocoding library.
Home-page: https://github.com/DenisCarriere/geocoder
Author: Denis Carriere
Author-email: carriere.denis@gmail.com
License: The MIT License
Download-URL: https://github.com/DenisCarriere/geocoder
Keywords: geocoder arcgis tomtom opencage google bing here
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: click
Requires-Dist: ratelim
Requires-Dist: requests
Requires-Dist: six

# Python Geocoder

[![](https://img.shields.io/pypi/v/geocoder.svg)](https://pypi.python.org/pypi/geocoder)
[![Snap Status](https://build.snapcraft.io/badge/DenisCarriere/geocoder.svg)](https://build.snapcraft.io/user/DenisCarriere/geocoder)
[![](https://travis-ci.org/DenisCarriere/geocoder.svg?branch=master)](https://travis-ci.org/DenisCarriere/geocoder)

Simple and consistent geocoding library written in Python.

Many online providers such as Google & Bing have geocoding services,
these providers do not include Python libraries and have different
JSON responses between each other.

It can be very difficult sometimes to parse a particular geocoding provider
since each one of them have their own JSON schema.

Here is a typical example of retrieving a Lat & Lng from Google using Python,
things shouldn't be this hard.

```python
>>> import requests
>>> url = 'https://maps.googleapis.com/maps/api/geocode/json'
>>> params = {'sensor': 'false', 'address': 'Mountain View, CA'}
>>> r = requests.get(url, params=params)
>>> results = r.json()['results']
>>> location = results[0]['geometry']['location']
>>> location['lat'], location['lng']
(37.3860517, -122.0838511)
```

Now lets use Geocoder to do the same task

```python
>>> import geocoder
>>> g = geocoder.google('Mountain View, CA')
>>> g.latlng
(37.3860517, -122.0838511)
```

A Work is In Progress to support multiple results

```python
>>> import geocoder
>>> g = geocoder.geonames('Mountain View, CA', maxRows=5)
>>> print(len(g))
5
>>> for result in g:
...   print(result.address, result.latlng)
...
Mountain View ['37.38605', '-122.08385']
Mountain View Elementary School ['34.0271', '-117.59116']
Best Western Plus Mountainview Inn and Suites ['51.79516', '-114.62793']
Best Western Mountainview Inn ['49.3338', '-123.1446']
Mountain View Post Office ['37.393', '-122.07774']
```

More details are available in [the documentation](http://geocoder.readthedocs.io/results.html)

## Documentation

[geocoder.readthedocs.org](https://geocoder.readthedocs.org/)

## API Overview

Many properties are available once the geocoder object is created.

### Forward

```python
>>> import geocoder
>>> g = geocoder.google('Mountain View, CA')
>>> g.geojson
>>> g.json
>>> g.wkt
>>> g.osm
```

> WIP SideNote / multiple results**
>
> For the providers currently supporting multiple results (see table below), the `geojson` property called on `g` will not apply to the best match but to all results. See documentation for more details on this.

### Reverse

```python
>>> g = geocoder.google([45.15, -75.14], method='reverse')
>>> g.city
>>> g.state
>>> g.state_long
>>> g.country
>>> g.country_long
```

### House Addresses

```python
>>> g = geocoder.google("453 Booth Street, Ottawa ON")
>>> g.housenumber
>>> g.postal
>>> g.street
>>> g.street_long
```

### IP Addresses

```python
>>> g = geocoder.ip('199.7.157.0')
>>> g = geocoder.ip('me')
>>> g.latlng
>>> g.city
```

### Bounding Box

Accessing the JSON & GeoJSON attributes will be different

```python
>>> g = geocoder.google("Ottawa")
>>> g.bbox
{"northeast": [45.53453, -75.2465979], "southwest": [44.962733, -76.3539158]}

>>> g.geojson['bbox']
[-76.3539158, 44.962733, -75.2465979, 45.53453]

>>> g.southwest
[44.962733, -76.3539158]
```

## Command Line Interface

```bash
$ geocode "Ottawa, ON"  >> ottawa.geojson
$ geocode "Ottawa, ON" \
    --provide google \
    --out geojson \
    --method geocode
```

## Providers

| Provider                       | Optimal   | Usage Policy                    | Mutiple results | Reverse | Proximity |
|:-------------------------------|:----------|:--------------------------------|:----------------|:--------|:----------|
| [ArcGIS][ArcGIS]               | World     |                                 | yes             | yes     |           |
| [Baidu][Baidu]                 | China     | API key                         |                 | yes     |           |
| [Bing][Bing]                   | World     | API key                         | yes             | yes     |           |
| [CanadaPost][CanadaPost]       | Canada    | API key                         |                 |         |           |
| [FreeGeoIP][FreeGeoIP]         | World     |                                 | N.A             |         |           |
| [Gaode][Gaode]                 | China     | API key                         |                 | yes     |           |
| [Geocoder.ca][Geocoder.ca] (Geolytica) | CA & US | Rate Limit                | N.A             |         |           |
| [GeocodeFarm][GeocodeFarm]     | World     | [Policy][GeocodeFarm-Policy]    | yes             | yes     |           |
| [GeoNames][GeoNames]           | World     | Username                        | yes             |         | yes       |
| [GeoOttawa][GeoOttawa]         | Ottawa    |                                 |                 |         |           |
| [Google][Google]               | World     | Rate Limit, [Policy][Google-Policy] | yes         | yes     | yes       |
| [HERE][HERE]                   | World     | API key                         | yes             | yes     |           |
| [IPInfo][IPInfo]               | World     | Rate Limit, [Paid Plans][IPinfo-paidPlans] | N.A  |         |           |
| [Mapbox][Mapbox]               | World     | API key                         | yes             | yes     | yes       |
| [MapQuest][MapQuest]           | World     | API key                         | yes             | yes     |           |
| [Mapzen][Mapzen]               | World     | API key                         |                 | yes     |           |
| [MaxMind][MaxMind]             | World     |                                 |                 |         |           |
| [OpenCage][OpenCage]           | World     | API key                         |                 | yes     |           |
| [OpenStreetMap][OpenStreetMap] | World     | [Policy][OpenStreetMap-Policy]  | yes             | yes     |           |
| [Tamu][Tamu]                   | US        | API key                         | N.A             |         |           |
| [TomTom][TomTom]               | World     | API key                         |                 |         |           |
| [What3Words][What3Words]       | World     | API key                         | N.A             | yes     |           |
| [Yahoo][Yahoo]                 | World     |                                 |                 |         |           |
| [Yandex][Yandex]               | Russia    |                                 |                 | yes     |           |
| [TGOS][TGOS]                   | Taiwan    |                                 |                 |         |           |

## Installation

### PyPi Install

To install Geocoder, simply:

```bash
$ pip install geocoder
...
```

### GitHub Install

Installing the latest version from Github:

```bash
$ git clone https://github.com/DenisCarriere/geocoder
...
$ cd geocoder
$ python setup.py install
...
```

### Snap Install

To install the stable geocoder [snap](https://snapcraft.io) in any of the [supported Linux distros](https://snapcraft.io/docs/core/install):

```bash
$ sudo snap install geocoder
...
```

If you want to help testing the latest changes from the master branch, you can install it from the edge channel:

```bash
$ sudo snap install geocoder --edge
...
```

The installed snap will be updated automatically every time a new version is pushed to the store.

## Twitter

Speak up on Twitter [@DenisCarriere](https://twitter.com/DenisCarriere) and tell me how you use this Python Geocoder. New updates will be pushed to Twitter Hashtags [#python](https://twitter.com/search?q=%23python).

## Feedback

Please feel free to give any feedback on this module. If you find any bugs or any enhancements to recommend please send some of your comments/suggestions to the [Github Issues Page](https://github.com/DenisCarriere/geocoder/issues).

[TGOS]: http://geocoder.readthedocs.org/providers/TGOS.html
[Mapbox]: http://geocoder.readthedocs.org/providers/Mapbox.html
[Google]: http://geocoder.readthedocs.org/providers/Google.html
[Google-Policy]: https://developers.google.com/maps/documentation/geocoding/usage-limits
[Bing]: http://geocoder.readthedocs.org/providers/Bing.html
[OpenStreetMap]: http://geocoder.readthedocs.org/providers/OpenStreetMap.html
[OpenStreetMap-Policy]: https://wiki.openstreetmap.org/wiki/Nominatim_usage_policy
[HERE]: http://geocoder.readthedocs.org/providers/HERE.html
[TomTom]: http://geocoder.readthedocs.org/providers/TomTom.html
[MapQuest]: http://geocoder.readthedocs.org/providers/MapQuest.html
[OpenCage]: http://geocoder.readthedocs.org/providers/OpenCage.html
[Yahoo]: http://geocoder.readthedocs.org/providers/Yahoo.html
[ArcGIS]: http://geocoder.readthedocs.org/providers/ArcGIS.html
[Yandex]: http://geocoder.readthedocs.org/providers/Yandex.html
[Geocoder.ca]: http://geocoder.readthedocs.org/providers/Geocoder-ca.html
[Baidu]: http://geocoder.readthedocs.org/providers/Baidu.html
[GeoOttawa]: http://geocoder.readthedocs.org/providers/GeoOttawa.html
[FreeGeoIP]: http://geocoder.readthedocs.org/providers/FreeGeoIP.html
[MaxMind]: http://geocoder.readthedocs.org/providers/MaxMind.html
[Mapzen]: http://geocoder.readthedocs.org/providers/Mapzen.html
[What3Words]: http://geocoder.readthedocs.org/providers/What3Words.html
[CanadaPost]: http://geocoder.readthedocs.org/providers/CanadaPost.html
[GeoNames]: http://geocoder.readthedocs.org/providers/GeoNames.html
[IPInfo]: http://geocoder.readthedocs.org/providers/IPInfo.html
[Tamu]: http://geoservices.tamu.edu/Services/Geocode/WebService/
[GeocodeFarm]: https://geocode.farm/
[GeocodeFarm-Policy]: https://geocode.farm/geocoding/free-api-documentation/
[Gaode]: http://geocoder.readthedocs.org/providers/Gaode.html
[IPinfo-paidPlans]: http://ipinfo.io/pricing

