*! version 0.3.7 20.05.2020

Title

geocodehere -- Geocode locations using HERE maps (Nokia). It is required to obtain HERE maps API credentials, which will be cost-free and takes only a few seconds, provided that you stay below 250,000 monthly transactions.

Syntax

geocodehere
[if] [in], apikey( ... ) [options]

Main
replace replace existing geocode results

noisily produce more terminal output while running

Credentials (required)
apikey(...) HERE maps API key (see below)

Response switches
language(...) Specifies the language for returned string variables

Search specification
searchtext(...) HERE maps search text

country(...) HERE maps search key

countryfocus(...) HERE maps search key

state(...) HERE maps search key

county(...) HERE maps search key

district(...) HERE maps search key

city(...) HERE maps search key

street(...) HERE maps search key

housenumber(...) HERE maps search key

postalcode(...) HERE maps search key

Description

geocodehere uses HERE maps (Nokia) to find geographic coordinates and additional information on addresses/locations.

Options

Main

replace replace existing geocode results (all variables geocodehere_*). Even if the current round fails to geocode a certain observation old entries will be lost.

noisily produce more terminal output while running. Useful for debugging and for understanding issues with authentification.

Credentials

apikey(...) specify the HERE maps API key. Credentials can be obtained through the HERE maps website, takes about three minutes and will be free for the most common uses with Stata (e.g. geo locating several hundred municipalities).
More details are available under:
https://developer.here.com/pricing
(most likely you'd have to select the consumer plan "Freemium")

Response switches

language(...) Specifies the language for returned string variables. Language code must be provided according to RFC 4647 standard.

Search specification

Options for specifying search criteria behave as specified in the HERE maps API documentation. Details can be found here:
https://developer.here.com/rest-apis/documentation/geocoder/topics/resource-geocode.html.

searchtext(...) search text with flexible/fuzzy matching. See documentation for details.

[searchkey](...) search parameters with different effects. See documentation for details.

Output

The program generates several variables containting information on the found locality. Most importantly geocodehere_lat and geocodehere_lon contain coordinates.
Some variables vary in their definition depending on the country (e.g. postal code or county).
Other variables contain information that can be used to assess the quality of the match.
To interpret the results the HERE documentation is very helpful: https://developer.here.com/rest-apis/documentation/geocoder/topics/resource-type-response-geocode.html.

The generated variables are:

Variable name Content

(JSON Path)

geocodehere_country 3-digit country code

(Result:1:Location:Address:Country)

geocodehere_lon Longitude

(Result:1:Location:DisplayPosition:Longitude)

geocodehere_lat Latitude

(Result:1:Location:DisplayPosition:Latitude)

geocodehere_label Address label

(Result:1:Location:Address:Label)

geocodehere_match_level Match level

(Result:1:MatchLevel)

geocodehere_match_code Match code

(Result:1:MatchCode)

geocodehere_locationtype Location type

(Result:1:Location:LocationType)

geocodehere_county County

(Result:1:Location:Address:County)

geocodehere_city City

(Result:1:Location:Address:City)

geocodehere_district District

(Result:1:Location:Address:District)

geocodehere_street Street name

(Result:1:Location:Address:Street)

geocodehere_housenumber House number

(Result:1:Location:Address:HouseNumber)

geocodehere_postalcode Postal code

(Result:1:Location:Address:PostalCode)

Example

This example code creates a data set of three entirely different localites. Before the code is executable, it is required to obtain HERE maps API credentials (see above).

`"set obs 3"'

`"gen postalcode = "e26dx" in 1"'

`"replace postalcode = "37213" in 2"'

`"gen housenumber = "12" in 2"'

`"gen street = "weserstr" in 2"'

`"gen searchtext = "Elephant Walk, Accra, Ghana" in 3"'

`"geocodehere, apikey(Your HERE maps API key) postalcode(postalcode) street(street) housenumber(housenumber) searchtext(searchtext)"'

See also

geocode,
gcode,
geocodeopen,
geocode3

Required ssc package: insheetjson

Author

Simon Heß, Goethe University Frankfurt.

The latest version of geocodehere can always be obtained from https://github.com/simonheb/geocodehere or http://HessS.org.

I am happy to receive comments and suggestions regarding bugs or possibilites for improvements/extensions via https://github.com/simonheb/geocodehere/issues.

Known issues with geocodehere

Stata versions before Stata 14 are not able to handle unicode character encodings. As a result, response data from HERE containing special characters may appear partly
scrambled (e.g. "Straße" != "StraÃŸe"). In some cases it helps to specify the option language(EN).