*! version 1.2.0 10.02.2018

*! Lars Zeigermann

help opencagegeo

Title

opencagegeo -- (Forward and reverse) geocode locations using the OpenCage Geocoder API.

Syntax

opencagegeo
[if] [in]
,
key(API key)[options]

opencagegeoi
#location

opencagegeo_options

General
key(API key) specifies the OpenCage Geocoder API key

countrycode(varname or string) specifies the countrycode of the location

language(varname or string) specifies the response language

resume resume after the query limit was exceeded

replace replace existing results

Forward geocoding
street(varname) specifies the variable containing the street name

number(varname) specifies the variable containing the house number

postcode(varname) specifies the variable containing the postal code

city(varname) specifies the variable containing the city (town,village)

county(varname) specifies the variable containing the county

state(varname) specifies the variable containing the state

country(varname) specifies the variable containing the country

fulladdress(varname) specifies the variable containing the full address

Reverse geocoding
latitude(varname) specifies the variable containing the latiude

longitude(varname) specifies the variable containing the longitude

coordinates(varname) specifies the variable containing latitude longitude pairs

Note: for opencagegeoi, the immediate version of opencagegeo, the user needs to define a global macro mykey containing the OpenCage Geocoder API key.

Description

opencagegeo uses the OpenCage Geocoder API (application programming interface) to obtain geographic coordinates for addresses (forward geocoding) and to retrieve postal addresses from latitude longitude pairs (reverse geocoding). opencagegeo takes its inputs from data in the memory and stores the results returned from the OpenCage Geocoder API in a set of variables. It allows the user to geocode many locations.

opencagegeoi is the immediate version of opencagegeo for geocoding a single location. The location address to be geocoded is typed directly into the command window. The results are directly displayed in the output window and stored in r().

opencagegeo requires an OpenCage Data API key which can be obtained by signing up at https://geocoder.opencagedata.com/users/sign_up. The user can choose among a number of customer plans with different daily rate limits. The free trial plan allows 2.500 requests per day. If the rate limit is hit, opencagegeo will issue an error message and exit. To continue the task on the following day, the user may simply add the resume option to the orignal specification. opencagegeo will automatically detect which observations are still to be geocoded. The user is strongly advised not to make any changes to the data until geocoding of all observations is completed. A new day begins at 00:00:00 Coordinated Universal Time (UTC).

Contrary to other geocoders routines available in Stata, OpenCage Data does not restrict data usage and explicitly allows storage. All geocoded data obtained from opencagegeo is jointly licensed under ODbL and CC-BY-SA licenses.

opencagegeo uses two user-written Stata libraries, insheetjson and libjson, for processing the JavaScript Object Notation (JSON) objects returned by the OpenCage Geocoder API.
They are available via Statistical Software Components.

Options for opencagegeo

Main

key(API key) specifies the OpenCage Geocoder API key.

countrycode(varname or string) allows the user to specify the country code of the location.
Providing a country code will restrict the results to the respective country. If all locations are in the same country, simply input the country code as a string.
If the locations are in two or more countries, specify a variable containing the respective country codes.
opencagegeo takes two character country codes as defined by the ISO 3166-1 Alpha 2 standard.

language(varname or string) allows the user to specify the language in which the results are returned. As with countrycode(), either a string or a string variable can be specified.
opencagegeo takes language codes as defined by the
IETF standard.
User of Stata 13 or older are advised to use the language carefully as many languages contain special characters which cannot be displayed properly.

replace instructs opencagegeo to overwrite existing geocoded results. If either in or if are specified, only selected observations will be replaced.

resume allows the user to continue geocoding on the following day if the rate limit was hit. The user is strongly advised not to make any changes to the data set before geocoding of all observations is completed.

Forward Geocoding

number(varname) specifies the variable containing the house number.

street(varname) specifies the variable containing the street name. Varname must be string.

postcode(varname) specifies the variable containing the postal code.

city(varname) specifies the variable containing the city, town or village. Varname must be string.

county(varname) specifies the variable containing the county. Varname must be string.

state(varname) specifies the variable containing the state. Varname must be string.

country(varname) specifies the variable containing the country. Varname must be string.

fulladdress(varname) specifies the variable containing the full address. Varname must be string. For the format, see below. fulladdress() may not be combined with any of the above options.

Reserve Geocoding

latitude(varname) specifies the variable containing the latitude. Values must lie between -90 and 90.

longitude(varname) specifies the variable containing the longitude. Values must lie between -180 and 180.

coordinates(varname) specifies the variable containing latitude longitude pairs. Values for latitudes and longitudes must be in the range of -90 to 90 and -180 to 180 respectively.
Both values must be separated by a comma. Varname must be string.

Remarks for opencagegeo

Not all options for forward geocoding have to be specified at the same time; any meaningful combination is possible. To obtain geocodes of cities you may use city(), state() and country().
Addresses in a single string variable are entered into fulladdress() and should follow the local convention, although the OpenCage Geocoder API allows for some flexibility. A well-formatted address might take the following formats:

"number street, city postal code, county, state, country"

"street number, postal code city, county, state, country"

Generally, the OpenCage Geocoder is not case sensitive and can deal with commonly used abbreviations. Running opencagegeo in Stata 14 (or newer) allows Unicode (UTF-8) inputs. That is address names may contain accented characters, symbols and non-latin characters. For older releases, the input variables may only contain printable ASCII characters, i.e. character codes 32 to 127. Otherwise, opencagegeo will issue an error message and exit. opencagegeo is sensitive to spelling mistakes and will return empty strings for misspelled location addresses.

Remarks for opencagegeoi

For opencagegeoi the API key must be stored in a global macro mykey. The user may further specify a global macro language containing the language in which the results shall be returned. The default is English. If the user sets the language to native, the results will be in the native language of the location - provided the underlying OpenStreetMap (OSM) data is available in that language.

For forward geocoding, addresses should be well-formatted as described above. For reverse geocoding, opencagegeoi takes a latitude longitude pair as input. The latitude must be stated first and both values need to be separated by a comma.

Output of opencagegeo

opencagegeo creates a set of variables which are described below.

Variable name Variable content

g_latitude latitude

g_longitude longitude

g_street street name

g_number house number

g_postcode postal code

g_city city,town or village

g_county county

g_state state

g_country country

g_formatted well-formated version of the place name (see below)

g_confidence confidence level (see below)

g_quality quality level (see below)

If the information is missing (e.g. the house number is not known) or not requested (number() was not specified
or no information on the house number was contained in address variable fed into the fulladdress() option), missing values will be returned.

g_formatted is a string variable containing a well-formatted place name generated by the OpenCage Geocoder API.
It addition to the address, it might have information such as the building name, building type (shopping mall, church etc.), the name of the shop etc.

g_confidence provides a measure of precision of the match. The confidence levels is calculated as the distance in kilometres between the South-East and the North-West corners of the bounding box. Confidence levels are defined as follows:

Value Definition

0 not defined

1 25km or more

2 less than 25km

3 less than 20km

4 less than 15km

5 less than 10km

6 less than 7.5km

7 less than 5km

8 less than 1km

9 less than 0.5km

10 less than 0.25km

The variable g_quality contains the accuracy level of the returned results and is defined as follows:

Value (label) Definition

0 (not found) location not found

1 (country) country level accuracy

2 (state) state level accuracy

3 (county) county level accuracy

4 (city) city (town, village) level accuracy

5 (postcode) postal code level accuracy

6 (street) street level accuracy

7 (number) house number level accuracy

The highest quality level to be reached is hence determined by the inputs;
if number() is not specified or no information on the house number is contained in the variable fed into fulladdress(), the highest quality level to be achieved is street.

Stored results of opencagegeoi

opencagegeoi saves the following results to r():

Macros

r(input) address as typed by user

r(formatted) well-formatted address returned from OpenCage Geocoder

r(lat) latitude

r(lon) longitude

r(conf) confidence level of result

Examples for opencagegeo

The following examples shall demonstrate how opencagegeo is used. For execution, an Opencage Geocoder API key is required.

We first generate two location addresses where the address components are contained in separate variables.

`"set obs 2"'

`"gen STREET = "Wittenbergerstrasse" in 1"'

`"replace STREET = "Denkmalsplatz" in 2"'

`"gen HOUSENUMBER = "14" in 1"'

`"gen POSTCODE = "26188" in 1"'

`"replace POSTCODE = "26180" in 2"'

`"gen CITY = "Edewecht" in 1"'

`"replace CITY = "Rastede" in 2"'

To forward geocode the two locations generated above, we type:

`"opencagegeo, key(YOUR-KEY-HERE) street(STREET) number(HOUSENUMBER) city(CITY)"'

For the fulladdress() option, the location address must be contained in a single string variable.

`"gen ADDRESS = "Wittenbergerstrasse 14,26188 Edewecht,Germany" in 1"'

`"replace ADDRESS = "Denkmalsplatz,26180 Rastede,Germany" in 2"'

To obtain geocodes using the fulladdress() option, we specify opencagegeo as following:

`"opencagegeo, key(YOUR-KEY-HERE) fulladdress(ADDRESS) replace"'

Now, we generate to variables containing latitudes and longitudes.

`"gen LATITUDE = "53.1479943" in 1"'

`"replace LATITUDE = "53.2450876" in 2"'

`"gen LONGITUDE = "7.8664466" in 1"'

`"replace LONGITUDE = "8.1992326" in 2"'

To retrieve the postal address, we type:

`"opencagegeo, key(YOUR-KEY-HERE) latitude(LATITUDE) longitude(LONGITUDE) replace"'

Alternatively, we might have geographic coordinates saved as comma-separated latitude longitude pairs in a single string variable.

`"gen COORDINATES = "53.1479943,7.8664466" in 1"'

`"replace COORDINATES = "53.2450876,8.1992326" in 2"'

To reserve geocoding the geocodes using the coordinates option, we type:

`"opencagegeo, key(YOUR-KEY-HERE) coordinates(COORDINATES) replace"'

Examples for opencagegeoi

First, we generate the global macro mykey (required) and set the output language (optional), in our case to German:

`"global mykey YOUR-KEY-HERE"'

`"global language DE"'

To forward geocode an address, we specify opencagegeoi as following:

`"opencagegeoi Wittenbergerstrasse 14, 26188 Edewecht, Germany"'

To retrieve the address from a latitude longitude pair, we type:

`"opencagegeoi 53.1479943,7.8664466"'

See also

geocode,
geocode3,
gcode,
geocodeopen,
geocodehere

Required ssc packages: insheetjson, libjson

Author

Lars Zeigermann, Düsseldorf Institute for Competition Economics (DICE) & Monopolies Commission, (lars.zeigermann@monopolkommission.bund.de)

Acknowledgements

Thanks to Ed Freyfolge of OpenCage Data for his support and Achim Ahrens for testing and helping improve opencagegeo.
I also thank the authors of existing geocoding routines, especially Adam Ozimek and Daniel Miles (geocode). Parts of opencagegeo build upon their code. The immediate version was added at Kit Baum's suggestion. All remaining errors are my own. Comments and suggestions are highly appreciated.