Stata Geocoding Tutorial

Before we dive in to the tutorial ...

This is a tutorial for using the OpenCage Geocoding API in Stata. 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:

Ok, ready?

opencagegeo is a Stata module written by Lars Zeigermann to access the OpenCage Geocoding API. You can find the newest version here.

Install (or update) opencagegeo

* Install the Stata module and two required user-written stata libraries from SSC:
. ssc install opencagegeo
. ssc install libjson
. ssc install insheetjson

* If you already have opencagegeo installed make sure you have the newest version
. adoupdate opencagegeo, update

Batch geocode addresses (forward geocoding)

* If you have a dataset of addresses stored in a single string variable 'address'
. opencagegeo, key(YOUR-API-KEY) fulladdress(address)

* If your addresses are stored in separate variables, e.g. house number in 'num', street name in 'str', city in 'city', and country in 'ctry':
. opencagegeo, key(YOUR-API-KEY) number(num) street(str) city(city) country(ctry)

Batch geocode coordinates (reverse geocoding)

* To geocode coordinates stored in a single variable 'coords' in the following format: latitude,longitude
. opencagegeo, key(YOUR-API-KEY) coordinates(coords)

* If your coordinates are stored in two separate variables 'lat' and 'lng'
. opencagegeo, key(YOUR-API-KEY) latitude(lat) longitude(lng)

Geocoding a single address or pair of coordinates

To geocode a single address or coordinates, you can use opencagegeoi the immediate version of opencagegeo
* First you need to save your API key to a global macro 'mykey'
. global mykey YOUR-API-KEY
. opencagegeoi YOUR-ADDRESS-HERE

Learn more

. help opencagegeo


  • In older versions of this software there is an optional parameter paidkey which needs to be set if you are an OpenCage customer, so that the software can deal with the slight difference in format between free trial and paid responses. This is not needed in the newest version.

  • Unfortunately Stata does not do well with parsing responses that contain place names with apostrophes in the place name. This seems to kill Stata's JSON parsing engine. Sorry. We welcome all suggestions as to how to fix this.
Start your free trial

2,500 API requests per day.

No credit card required.