:earth_asia: Python Geocoder

Related tags

Geolocationgeocoder
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
Logging the position of the car on an sdcard

audi-mmi-3g-gps-logging Logging the position of the car on an sdcard, startup script origin not clear to me, logging setup and time change is what I d

2 May 31, 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
framework for large-scale SAR satellite data processing

pyroSAR A Python Framework for Large-Scale SAR Satellite Data Processing The pyroSAR package aims at providing a complete solution for the scalable or

John Truckenbrodt 389 Dec 21, 2022
ArcGIS Python Toolbox for WhiteboxTools

WhiteboxTools-ArcGIS ArcGIS Python Toolbox for WhiteboxTools. This repository is related to the ArcGIS Python Toolbox for WhiteboxTools, which is an A

Qiusheng Wu 190 Dec 30, 2022
h3-js provides a JavaScript version of H3, a hexagon-based geospatial indexing system.

h3-js The h3-js library provides a pure-JavaScript version of the H3 Core Library, a hexagon-based geographic grid system. It can be used either in No

Uber Open Source 648 Jan 07, 2023
Expose a GDAL file as a HTTP accessible on-the-fly COG

cogserver Expose any GDAL recognized raster file as a HTTP accessible on-the-fly COG (Cloud Optimized GeoTIFF) The on-the-fly COG file is not material

Even Rouault 73 Aug 04, 2022
Daily social mapping project in November 2021. Maps made using PyGMT whenever possible.

Daily social mapping project in November 2021. Maps made using PyGMT whenever possible.

Wei Ji 20 Nov 24, 2022
This is the antenna performance plotted from tinyGS reception data.

tinyGS-antenna-map This is the antenna performance plotted from tinyGS reception data. See their repository. The code produces a plot that provides Az

Martin J. Levy 14 Aug 21, 2022
r.cfdtools 7 Dec 28, 2022
peartree: A library for converting transit data into a directed graph for sketch network analysis.

peartree 🍐 🌳 peartree is a library for converting GTFS feed schedules into a representative directed network graph. The tool uses Partridge to conve

Kuan Butts 183 Dec 29, 2022
Manage your XYZ Hub or HERE Data Hub spaces from Python.

XYZ Spaces for Python Manage your XYZ Hub or HERE Data Hub spaces and Interactive Map Layer from Python. FEATURED IN: Online Python Machine Learning C

HERE Technologies 30 Oct 18, 2022
Earthengine-py-notebooks - A collection of 360+ Jupyter Python notebook examples for using Google Earth Engine with interactive mapping

earthengine-py-notebooks A collection of 360+ Jupyter Python notebook examples for using Google Earth Engine with interactive mapping Contact: Qiushen

Qiusheng Wu 1.1k Dec 29, 2022
Tile Map Service and OGC Tiles API for QGIS Server

Tiles API Add tiles API to QGIS Server Tiles Map Service API OGC Tiles API Tile Map Service API - TMS The TMS API provides these URLs: /tms/? to get i

3Liz 6 Dec 01, 2021
Processing and interpolating spatial data with a twist of machine learning

Documentation | Documentation (dev version) | Contact | Part of the Fatiando a Terra project About Verde is a Python library for processing spatial da

Fatiando a Terra 468 Dec 20, 2022
A short term landscape evolution using a path sampling method to solve water and sediment flow continuity equations and model mass flows over complex topographies.

r.sim.terrain A short-term landscape evolution model that simulates topographic change for both steady state and dynamic flow regimes across a range o

Brendan Harmon 7 Oct 21, 2022
Geographic add-ons for Django REST Framework. Maintained by the OpenWISP Project.

django-rest-framework-gis Geographic add-ons for Django Rest Framework - Mailing List. Install last stable version from pypi pip install djangorestfra

OpenWISP 981 Jan 03, 2023
Focal Statistics

Focal-Statistics The Focal statistics tool in many GIS applications like ArcGIS, QGIS and GRASS GIS is a standard method to gain a local overview of r

Ifeanyi Nwasolu 1 Oct 21, 2021
A Django application that provides country choices for use with forms, flag icons static files, and a country field for models.

Django Countries A Django application that provides country choices for use with forms, flag icons static files, and a country field for models. Insta

Chris Beaven 1.2k Jan 03, 2023
Advanced raster and geometry manipulations

buzzard In a nutshell, the buzzard library provides powerful abstractions to manipulate together images and geometries that come from different kind o

Earthcube Lab 30 Jun 20, 2022
Track International space station with python

NASA-ISS-tracker Track International space station with python Modules import json import turtle import urllib.request import time import webbrowser i

Nikhil Yadav 8 Aug 12, 2021