Skip to content

Latest commit

 

History

History
330 lines (267 loc) · 13 KB

README.md

File metadata and controls

330 lines (267 loc) · 13 KB

Markdownify
Python Geocoder

Simple and consistent geocoding library written in Python.

Tests RDT PyPi Codecov Code Style


Table of content

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', key='YOUR_GOOGLE_API_KEY')
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', key='YOUR_GOOGLE_API_KEY')
g.geojson
g.object_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

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

House Addresses

import geocoder

g = geocoder.google("453 Booth Street, Ottawa ON", key='YOUR_GOOGLE_API_KEY')
g.house_number
g.postal
g.street
g.street_long

IP Addresses

import geocoder
g = geocoder.freegeoip('199.7.157.0')
g.latlng
# [43.7154, -79.3896]
g.city
# Toronto

Bounding Box

Accessing the JSON & GeoJSON attributes will be different

import geocoder
g = geocoder.osm("Ottawa")
g.bbox
# {'northeast': [45.5569506, -75.5251593], 'southwest': [45.2369506, -75.8451593]}

g.southwest
# [45.2369506, -75.8451593]

Command Line Interface

geocode "Ottawa, ON"  >> ottawa.geojson
geocode "Ottawa, ON" --provider osm --output geojson --method geocode

Providers

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

Installation

PyPi Install

To install Geocoder3, simply:

pip install geocoder3

GitHub Install

Installing the latest version from Github:

git clone https://github.com/insspb/geocoder3
cd geocoder3
python setup.py install

Feedback

Please feel free to give any feedback on this module. just create an issue on GitHub

Contribution

If you find any bugs or any enhancements to recommend please send some of your comments/suggestions to the Github Issues Page.

Some way to contribute, from the most generic to the most detailed:

Documenting

If you are not comfortable with development, you can still contribute with the documentation.

  • Review the documentation of a specific provider. Most of the time it require more details.
  • Review the parameters for a specific method, compared to what is supported by the provider
  • Review documentation for command line

If you miss any feature, just create an issue accordingly. Be sure to describe your use case clearly, and to provide links to the correct sources.

Coding

  • Add support for a new provider. Documentation TBD, starting point possible with
  • wip_guide.
  • Extend methods for an existing support, i.e support an additional API).
  • Extend support of an existing API, i.e, support more (json) fields from the response, or more parameters.

ChangeLog

See Releases