Jupyter Notebook Geocoding Tutorial

This is a tutorial for using the OpenCage Geocoding API in a Python Jupyter Notebook.

Before you can query the API you will need to sign up for an OpenCage API key.

Once you've done that we recommend you spend five minutes on:

Install the OpenCage Python module

Install with pip, compatible with Python version 2 and 3.

% pip install opencage

Initialize geocoder

In [28]:
from opencage.geocoder import OpenCageGeocode
from pprint import pprint

Replace YOUR-API-KEY below with the OpenCage API key for your account.

In [8]:
key = 'YOUR-API-KEY'
geocoder = OpenCageGeocode(key)

Geocode coordinate

In [10]:
results = geocoder.reverse_geocode(44.8303087, -0.5761911)
pprint(results)
[{'annotations': {'DMS': {'lat': "44° 49' 49.11132'' N",
                          'lng': "0° 34' 34.28796'' E"},
                  'MGRS': '30TXQ9159666958',
                  'Maidenhead': 'IN94rt09ug',
                  'Mercator': {'x': -64141.3, 'y': 5564710.789},
                  'OSM': {'edit_url': 'https://www.openstreetmap.org/edit?node=2754853042#map=16/44.83031/-0.57619',
                          'url': 'https://www.openstreetmap.org/?mlat=44.83031&mlon=-0.57619#map=16/44.83031/-0.57619'},
                  'callingcode': 33,
                  'currency': {'alternate_symbols': [],
                               'decimal_mark': ',',
                               'html_entity': '€',
                               'iso_code': 'EUR',
                               'iso_numeric': 978,
                               'name': 'Euro',
                               'smallest_denomination': 1,
                               'subunit': 'Cent',
                               'subunit_to_unit': 100,
                               'symbol': '€',
                               'symbol_first': 1,
                               'thousands_separator': '.'},
                  'flag': '🇫🇷',
                  'geohash': 'ezzx4ch7mz0zbyftcpdf',
                  'qibla': 111.75,
                  'roadinfo': {'drive_on': 'right',
                               'road': 'Rue Sauteyron',
                               'speed_in': 'km/h'},
                  'sun': {'rise': {'apparent': 1556686320,
                                   'astronomical': 1556679300,
                                   'civil': 1556684400,
                                   'nautical': 1556682000},
                          'set': {'apparent': 1556737680,
                                  'astronomical': 1556744700,
                                  'civil': 1556739600,
                                  'nautical': 1556742000}},
                  'timezone': {'name': 'Europe/Paris',
                               'now_in_dst': 1,
                               'offset_sec': 7200,
                               'offset_string': 200,
                               'short_name': 'CEST'},
                  'what3words': {'words': 'advice.quiet.surveyed'}},
  'bounds': {'northeast': {'lat': 44.8304087, 'lng': -0.5760911},
             'southwest': {'lat': 44.8302087, 'lng': -0.5762911}},
  'components': {'ISO_3166-1_alpha-2': 'FR',
                 'ISO_3166-1_alpha-3': 'FRA',
                 '_type': 'building',
                 'city': 'Bordeaux',
                 'continent': 'Europe',
                 'country': 'France',
                 'country_code': 'fr',
                 'county': 'Bordeaux',
                 'house_number': '11',
                 'political_union': 'European Union',
                 'postcode': '33000',
                 'road': 'Rue Sauteyron',
                 'state': 'New Aquitaine',
                 'state_district': 'Gironde',
                 'suburb': 'Bordeaux Sud'},
  'confidence': 10,
  'formatted': '11 Rue Sauteyron, 33000 Bordeaux, France',
  'geometry': {'lat': 44.8303087, 'lng': -0.5761911}}]

Set output language, error handling

In [13]:
from opencage.geocoder import InvalidInputError, RateLimitExceededError, UnknownError

try:
    results = geocoder.reverse_geocode(44.8303087, -0.5761911, language='de', no_annotation='1')
    if results and len(results):
        print(results[0]['formatted'])
except RateLimitExceededError as ex:
    print(ex)
    # Your rate limit has expired. It will reset to 2500 on 2018-10-08T00:00:00
    # Upgrade on https://opencagedata.com/pricing
11 Rue Sauteyron, 33000 Bordeaux, Frankreich

Lookup coordinates from postal address

In [15]:
query = u'Bosutska ulica 10, Trnje, Zagreb, Croatia'
results = geocoder.geocode(query)

print(u'%f;%f;%s;%s' % (results[0]['geometry']['lat'], 
                        results[0]['geometry']['lng'],
                        results[0]['components']['country_code'],
                        results[0]['annotations']['timezone']['name']))
45.796937;15.981895;hr;Europe/Belgrade

Plot geocoded address on a map

Install ipyleaflet

% pip install ipyleaflet

In [20]:
from ipyleaflet import *
In [23]:
results = geocoder.geocode(u'Brussels, Belgium')
center = (results[0]['geometry']['lat'], results[0]['geometry']['lng'])
In [27]:
map = Map(center=center, zoom=6)
marker = Marker(location=center, draggable=False)
map.add_layer(marker)

map

Alternative Python modules

You can also access the OpenCage geocoder via Denis Carriere's geocoder library. Here is a code sample showing how to query our API using python geocoder.