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:

playing with the demo page, so that you see the actual response the API returns.
browsing the API documentation, so you understand the various optional parameters, possible response codes, and the rate limiting on free trial accounts

Install the OpenCage Python module¶

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

% pip install opencage

Initialize geocoder¶

from opencage.geocoder import OpenCageGeocode
from pprint import pprint

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

key = 'YOUR-API-KEY'
geocoder = OpenCageGeocode(key)

Geocode coordinate¶

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': '&#x20AC;',
                               '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¶

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¶

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

from ipyleaflet import *

results = geocoder.geocode(u'Brussels, Belgium')
center = (results[0]['geometry']['lat'], results[0]['geometry']['lng'])

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.