<h1 align="center" style="margin:1em"> <a href="https://geocoder.readthedocs.org/"> <img src="https://github.com/DenisCarriere/geocoder/raw/master/docs/_static/geocoder.png" alt="Markdownify" width="200"></a> <br /> Python Geocoder </h1> <h4 align="center"> Simple and consistent geocoding library written in Python. </h4> <p align="center"> <a href="http://geocoder.readthedocs.io/?badge=master"> <img src="https://readthedocs.org/projects/geocoder/badge/?version=master" alt="RDT"> </a> <a href="https://pypi.python.org/pypi/geocoder"> <img src="https://img.shields.io/pypi/v/geocoder.svg" alt="PyPi"> </a> <a href="https://build.snapcraft.io/user/DenisCarriere/geocoder"> <img src="https://build.snapcraft.io/badge/DenisCarriere/geocoder.svg" alt="Snap"> </a> <a href="https://travis-ci.org/DenisCarriere/geocoder"> <img src="https://travis-ci.org/DenisCarriere/geocoder.svg?branch=master" alt="Travis"> </a> <a href="https://codecov.io/gh/DenisCarriere/geocoder"> <img src="https://codecov.io/gh/DenisCarriere/geocoder/branch/master/graph/badge.svg" alt="Codecov" /> </a> </p> <br>

Table of content

Overview
A glimpse at the API
Command Line Interface
Providers
Installation
Feedback
Contribution
- Documenting
- Coding
ChangeLog

Overview

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.

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

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

A glimpse at the API

Many properties are available once the geocoder object is created.

Forward

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

Multiple queries ('batch' geocoding)

>>> import geocoder
>>> g = geocoder.mapquest(['Mountain View, CA', 'Boulder, Co'], method='batch')
>>> for result in g:
...   print(result.address, result.latlng)
...
('Mountain View', [37.39008, -122.08139])
('Boulder', [40.015831, -105.27927])

Multiple results

>>> 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']

The providers currently supporting multiple results are listed in the table below.

Reverse

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

House Addresses

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

IP Addresses

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

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

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

Providers

Provider	Optimal	Usage Policy	Multiple results	Reverse	Proximity	Batch
[ArcGIS][ArcGIS]	World		yes	yes
[Baidu][Baidu]	China	API key		yes
[Bing][Bing]	World	API key	yes	yes		yes
[CanadaPost][CanadaPost]	Canada	API key	yes
[FreeGeoIP][FreeGeoIP]	World
[Gaode][Gaode]	China	API key		yes
[Geocoder.ca][Geocoder.ca] (Geolytica)	CA & US	Rate Limit
[GeocodeFarm][GeocodeFarm]	World	[Policy][GeocodeFarm-Policy]	yes	yes
[GeoNames][GeoNames]	World	Username	yes		yes
[GeoOttawa][GeoOttawa]	Ottawa		yes
[Gisgraphy][Gisgraphy]	World	API key	yes	yes	yes
[Google][Google]	World	Rate Limit, [Policy][G-Policy]	yes	yes	yes
[HERE][HERE]	World	API key	yes	yes
[IPInfo][IPInfo]	World	Rate Limit, [Plans][IP-Plans]
[Komoot][Komoot] (OSM powered)	World		yes	yes
[LocationIQ][LocationIQ]	World	API Key	yes	yes
[Mapbox][Mapbox]	World	API key	yes	yes	yes
[MapQuest][MapQuest]	World	API key	yes	yes		yes
[~~Mapzen~~][Mapzen]	Shutdown	API key	yes	yes
[MaxMind][MaxMind]	World
[OpenCage][OpenCage]	World	API key	yes	yes
[OpenStreetMap][OpenStreetMap]	World	[Policy][OpenStreetMap-Policy]	yes	yes
[Tamu][Tamu]	US	API key
[TGOS][TGOS]	Taiwan
[TomTom][TomTom]	World	API key	yes
[USCensus][USCensus]	US			yes		yes
[What3Words][What3Words]	World	API key		yes
[Yahoo][Yahoo]	World
[Yandex][Yandex]	Russia		yes	yes

Installation

PyPi Install

To install Geocoder, simply:

$ pip install geocoder
...

GitHub Install

Installing the latest version from Github:

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

Snap Install

To install the stable geocoder snap in any of the supported Linux distros:

$ 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:

$ sudo snap install geocoder --edge
...

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

Feedback

Please feel free to give any feedback on this module.

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

geocoder

Description