:earth_asia: Python Geocoder

Related tags

Geolocation geocoder
Overview

Markdownify
Python Geocoder

Simple and consistent geocoding library written in Python.

RDT PyPi Snap Travis Codecov


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')
>>> 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 World yes yes
Baidu China API key yes
Bing World API key yes yes yes
CanadaPost Canada API key yes
FreeGeoIP This API endpoint is deprecated and will stop working on July 1st, 2018. 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
GeoOttawa Ottawa 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

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.

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 they are lacking 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 additionnal API). Documentation TBD
  • extend support of an existing API, i.e, support more (json) fields from the response, or more parameters. Documentation TBD

ChangeLog

See CHANGELOG.md

Comments
  • Cache / Memoization

    Cache / Memoization

    A useful addition, especially when converting a large number of strings, would be to store/cache the results to some common strings somewhere (memory, mongodb database, redis, ...). I'm not sure what's the best way to do this to be generic enough. I had used a mongodb in my old geocoder and it worked well https://gist.github.com/themiurgo/3136205

    However I'd like it to be more generic for this module. I'll think about it.

    opened by themiurgo 12
  • getting a sense of the lib: enriching a bit geonames

    getting a sense of the lib: enriching a bit geonames

    • added a test file for geonames
    • retrieved more attributes from results
    • added methods children and hierarchy
    • reviewed slightly doc

    question : how should be handled multiple results (e.g. the ones from hierarchy) ?

    opened by ebreton 11
  • Google requires API Key

    Google requires API Key

    Does your code supports Google's reverse geocoding since they require the use of an API key? I quickly browsed through your documentation but couldn't find anything on how to use Google API key. Please advise.

    opened by rgraulus 10
  • UnicodeEncodeError when geocoding result contains non-ASCII character

    UnicodeEncodeError when geocoding result contains non-ASCII character

    When trying to encode an address whose result would contain a non-ASCII character (e.g. Γ©, Γ‘, ΕΎ etc.), I get this error. Using iPython 2.7 in Anaconda on Windows 7. Any ideas? Thanks for the great library BTW!

    In [58]: s = geocoder.bing("Champs de Mars, Paris", proxies=proxies)
    
    In [59]: s
    Out[59]: <[OK] Bing - Geocode [Champ de Mars, Paris, France]>
    
    In [60]: s = geocoder.bing("Avenue Champs Elysees, Paris", proxies=proxies)
    ---------------------------------------------------------------------------
    UnicodeEncodeError                        Traceback (most recent call last)
    <ipython-input-60-62b4e3a20efb> in <module>()
    ----> 1 s = geocoder.bing("Avenue Champs Elysees, Paris", proxies=proxies)
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\api.pyc in bing(location, **kwargs)
        205         > reverse
        206     """
    --> 207     return get(location, provider='bing', **kwargs)
        208
        209
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\api.pyc in get(location, **kwargs)
        101                   '>>> g = geocoder.get([45.68, -75.15], method="reverse
    ")')
        102             sys.exit()
    --> 103     return options[provider][method](location, **kwargs)
        104
        105
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\bing.pyc in __init__(self, location, **kwargs)
         65             'maxResults': 1,
         66         }
    ---> 67         self._initialize(**kwargs)
         68         self._bing_catch_errors()
         69
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\base.pyc in _initialize(self, **kwargs)
         99         self._build_tree(self.content)
        100         self._exceptions()
    --> 101         self._json()
        102
        103     def _json(self):
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\base.pyc in _json(self)
        105             if bool(not key.startswith('_') and key not in self._exclude
    ):
        106                 self.fieldnames.append(key)
    --> 107                 value = getattr(self, key)
        108                 if value:
        109                     self.json[key] = value
    
    C:\Documents\SW\Anaconda\lib\site-packages\geocoder\bing.pyc in housenumber(self)
        105             expression = r'\d+'
        106             pattern = re.compile(expression)
    --> 107             match = pattern.search(str(self.street))
        108             if match:
        109                 return match.group(0)
    
    UnicodeEncodeError: 'ascii' codec can't encode character u'\xc9' in position 18:
     ordinal not in range(128)
    
    opened by Chartres 10
  • Add pep8 scanning to CI job

    Add pep8 scanning to CI job

    This patch enables Travis CI to automatically scan for pep8 violations and report back in the build. Uses flake8 to perform this task.

    One exception to the pep8 default rules is we allow 120 max line length instead of the default 79 characters.

    opened by zxiiro 10
  • Tests & encoding fixing

    Tests & encoding fixing

    Python 2 encoding issues are a living hell. Tried to do the best out of it, and it works well! πŸ™ƒ Thanks @ebreton for detecting these issues again!

    & bumped the version number

    opened by thomas-lab 9
  • ConnectionError error no 10054

    ConnectionError error no 10054

    Hi I am trying to get the city, state and country through the ip address.

    My data frame has 500,000 rows and I need to apply it on each of them.

    I am getting the the connection error after 200 records or so.

    I even tried using time.sleep(5) and it still stops after 500 records or so.

    Can you please provide alternates or solution to this.

    Thank you.

    opened by rishabhjhaveri10 9
  • Provide gisgraphy geocoder

    Provide gisgraphy geocoder

    David Masclet currently prepares gisgraphy geocoder V5. This PR provides a client implementation. API key policy still / test case handling needs to be clarified.

    opened by hbruch 8
  • Opencage lookup broken

    Opencage lookup broken

    Hi,

    The Opencage lookup seems to be broken again. I get the following error:

     File "..\lib\site-packages\geocoder\base.py", line 120, in _parse_json_with_fieldnames
        value = getattr(self, key)
      File "..\lib\site-packages\geocoder\opencage.py", line 359, in bbox
        south = self.raw['bounds']['southwest'].get('lat')
    

    I can solve it by putting a try, except around the bit:

                try:
                    value = getattr(self, key)
                    if value:
                        self.json[key] = value
                except Exception as e:
                    print(e)
    

    but I'm not sure that that is the best solution... :)

    I'm not sure how the new multiple search results have changed things and if it will be a general error, or only an error with opencage.

    opened by nyejon 8
  • Google client keys don't get picked up

    Google client keys don't get picked up

    We noticed that after upgrading geocoder from 1.25.0 to later versions, the Google environment variables when using a client account do not get picked up, here is the error:

    <ipython-input-3-4e48b1d75176> in <module>()
    ----> 1 geocoder.google(address)
    
    .../geocoder/api.py in google(location, **kwargs)
        193         > elevation
        194     """
    --> 195     return get(location, provider='google', **kwargs)
        196 
        197 
    
    .../geocoder/api.py in get(location, **kwargs)
        159         if method not in options[provider]:
        160             raise ValueError("Invalid method")
    --> 161     return options[provider][method](location, **kwargs)
        162 
        163 
    
    .../geocoder/base.py in __init__(self, location, **kwargs)
        706 
        707         # check validity of provider key
    --> 708         provider_key = self._get_api_key(kwargs.pop('key', None))
        709 
        710         # point to geocode, as a string or coordinates
    
    .../geocoder/base.py in _get_api_key(cls, key)
        685         # raise exception if not valid key found
        686         if not key:
    --> 687             raise ValueError('Provide API Key')
        688 
        689         return key
    
    ValueError: Provide API Key
    bug 
    opened by avanderm 8
  • Fix the Opencage error and add all of the other Opencage Aliases

    Fix the Opencage error and add all of the other Opencage Aliases

    Hi Denis,

    I have created this to address issue: #276 and add additional functionality.

    Added all of the aliases as defined in: https://github.com/OpenCageData/address-formatting/blob/master/conf/components.yaml

    Fixed the circular city lookup error and created a more robust lookup for the aliases if one does not exist.

    Updated tests to include country and country_code

    opened by nyejon 8
  • Quality/type tags in results by reverse geocoding

    Quality/type tags in results by reverse geocoding

    Hi,

    I am working on a project to identify the location type using reverse geocoding and I am using the below code to do that:

    g = geocoder.osm([x.lat,x.lng], method='reverse').json

    And i am getting the result, which is mentioned below, I am trying to find more information regarding the "quality" and "type" tags, also, i want to know what does "yes" means in this context. Any help is much appreciated.

    {
      "encoding": "utf-8",
      "status_code": 200,
      "place_id": "169621055",
      "county": "Suffolk County",
      "street": "Wall Street",
      "osm_id": "470231498",
      "lng": -73.42776365,
      "quality": "yes",
      "confidence": 10,
      "type": "yes",
      "state": "New York",
      "location": "11 Wall Street, New York",
      "provider": "osm",
      "housenumber": "11",
      "accuracy": 0.511,
      "status": "OK",
      "importance": 0.511,
      "bbox": {
        "northeast": [
          40.8716548,
          -73.4275981
        ],
        "southwest": [
          40.8715761,
          -73.4279292
        ]
      },
      "address": "11, Wall Street, Halesite, Suffolk County, New York, 11743, United States of America",
      "lat": 40.87161545,
      "postal": "11743",
      "ok": true,
      "country": "United States of America",
      "region": "New York",
      "osm_type": "way",
      "place_rank": "30"
    }
    
    opened by anurupsatyarth 0
  • ip.ok  is providing wrong value

    ip.ok is providing wrong value

    hey I was just doing stuff with geocoder and I reeally loved it. However I guess there is some issue in it here is the details: Screen Shot 2022-08-05 at 8 27 53 AM

    As you can see ip.ok is giving True but ip.json.["ok"] is returning False which doesnot satisfy this statement "If geocoder was able to contact the server, but no result could be found for the given search terms, the ok attribute on the returned object will be False." from the docs.

    opened by jabir-khan 2
  • Yandex does not work

    Yandex does not work

    Now Yandex API demands the key for use & it is not tolerant to the parameter "kind" without the value. I made a fork & did a couple of commits. You can use my correction or do it yourself. I have tested mine & it does work.

    opened by MordorianGuy 0
  • OpenCage Result Constructs BBox Incorrectly

    OpenCage Result Constructs BBox Incorrectly

    The OpenCageResult.bbox property is defined as:

    @property
    def bbox(self):
        south = self._bounds.get('southwest', {}).get('lat')
        north = self._bounds.get('northeast', {}).get('lat')
        west = self._bounds.get('southwest', {}).get('lng')
        east = self._bounds.get('northeast', {}).get('lng')
        if all([south, west, north, east]):
            return BBox.factory([south, west, north, east]).as_dict
    

    But the BBox initializer expects a list argument, in BBox.__init__ to be:

        elif bbox is not None and all(bbox):
            self.west, self.south, self.east, self.north = map(float, bbox)
    

    It looks like OpenCageResult.bbox should be changed to:

    return BBox.factory([west, south, east, north]).as_dict
    
    opened by ericbusboom 0
  • Error using the library

    Error using the library

    Hello, I am using Geocoder for an AI application, what happens is that when it ends it gives me this error:

    Exception ignored on calling ctypes callback function: <function catch_errors..call_with_this at 0x000001984ECBDF70>

    Traceback (most recent call last):

    File "C:\Users\diego\AppData\Local\Programs\Python\Python39\lib\site-packages\comtypes_comobject.py", line 91, in call_with_this

    File "C:\Users\diego\AppData\Local\Programs\Python\Python39\lib\logging_init_.py", line 1474, in error

    File "C:\Users\diego\AppData\Local\Programs\Python\Python39\lib\logging_init_.py", line 1699, in isEnabledFor

    TypeError: 'NoneType' object is not callable

    This error only occurs when I import the Geocoder library.

    opened by Magnarks 0
Releases(1.17.3)
Owner
Denis
Co-Founder and CTO @EOS-Nation πŸš€πŸŒŸ
Denis
GeoIP Legacy Python API

MaxMind GeoIP Legacy Python Extension API Requirements Python 2.5+ or 3.3+ GeoIP Legacy C Library 1.4.7 or greater Installation With pip: $ pip instal

MaxMind 230 Nov 10, 2022
Python bindings and utilities for GeoJSON

geojson This Python library contains: Functions for encoding and decoding GeoJSON formatted data Classes for all GeoJSON Objects An implementation of

Jazzband 765 Jan 6, 2023
Geocoding library for Python.

geopy geopy is a Python client for several popular geocoding web services. geopy makes it easy for Python developers to locate the coordinates of addr

geopy 3.8k Dec 30, 2022
Python Data. Leaflet.js Maps.

folium Python Data, Leaflet.js Maps folium builds on the data wrangling strengths of the Python ecosystem and the mapping strengths of the Leaflet.js

null 6k Jan 2, 2023
Python tools for geographic data

GeoPandas Python tools for geographic data Introduction GeoPandas is a project to add support for geographic data to pandas objects. It currently impl

GeoPandas 3.5k Jan 3, 2023
Python interface to PROJ (cartographic projections and coordinate transformations library)

pyproj Python interface to PROJ (cartographic projections and coordinate transformations library). Documentation Stable: http://pyproj4.github.io/pypr

null 832 Dec 31, 2022
Python bindings and utilities for GeoJSON

geojson This Python library contains: Functions for encoding and decoding GeoJSON formatted data Classes for all GeoJSON Objects An implementation of

Jazzband 763 Dec 26, 2022
Documentation and samples for ArcGIS API for Python

ArcGIS API for Python ArcGIS API for Python is a Python library for working with maps and geospatial data, powered by web GIS. It provides simple and

Esri 1.4k Dec 30, 2022
PySAL: Python Spatial Analysis Library Meta-Package

Python Spatial Analysis Library PySAL, the Python spatial analysis library, is an open source cross-platform library for geospatial data science with

Python Spatial Analysis Library 1.1k Dec 18, 2022
Simple, concise geographical visualization in Python

Geographic visualizations for HoloViews. Build Status Coverage Latest dev release Latest release Docs What is it? GeoViews is a Python library that ma

HoloViz 445 Jan 2, 2023
A package built to support working with spatial data using open source python

EarthPy EarthPy makes it easier to plot and manipulate spatial data in Python. Why EarthPy? Python is a generic programming language designed to suppo

Earth Lab 414 Dec 23, 2022
pure-Python (Numpy optional) 3D coordinate conversions for geospace ecef enu eci

Python 3-D coordinate conversions Pure Python (no prerequistes beyond Python itself) 3-D geographic coordinate conversions and geodesy. API similar to

Geospace code 292 Dec 29, 2022
Python package for earth-observing satellite data processing

Satpy The Satpy package is a python library for reading and manipulating meteorological remote sensing data and writing it to various image and data f

PyTroll 882 Dec 27, 2022
Use Mapbox GL JS to visualize data in a Python Jupyter notebook

Location Data Visualization library for Jupyter Notebooks Library documentation at https://mapbox-mapboxgl-jupyter.readthedocs-hosted.com/en/latest/.

Mapbox 620 Dec 15, 2022
python toolbox for visualizing geographical data and making maps

geoplotlib is a python toolbox for visualizing geographical data and making maps data = read_csv('data/bus.csv') geoplotlib.dot(data) geoplotlib.show(

Andrea Cuttone 976 Dec 11, 2022
geemap - A Python package for interactive mapping with Google Earth Engine, ipyleaflet, and ipywidgets.

A Python package for interactive mapping with Google Earth Engine, ipyleaflet, and folium

Qiusheng Wu 2.4k Dec 30, 2022
Python interface to PROJ (cartographic projections and coordinate transformations library)

pyproj Python interface to PROJ (cartographic projections and coordinate transformations library). Documentation Stable: http://pyproj4.github.io/pypr

null 832 Dec 31, 2022
OSMnx: Python for street networks. Retrieve, model, analyze, and visualize street networks and other spatial data from OpenStreetMap.

OSMnx OSMnx is a Python package that lets you download geospatial data from OpenStreetMap and model, project, visualize, and analyze real-world street

Geoff Boeing 4k Jan 8, 2023
Pure Python NetCDF file reader and writer

Pyncf Pure Python NetCDF file reading and writing. Introduction Inspired by the pyshp library, which provides simple pythonic and dependency free data

Karim Bahgat 14 Sep 30, 2022