geocoder3
Python Geocoder3
MIT License
Table of content
- Table of content
- Overview
- A glimpse at the API
- Command Line Interface
- Providers
- Installation
- Feedback
- Contribution
- 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', 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 | ||
| 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 | ||
| 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