*! version 4.2 18jun2024
help georoute (SJ22-1: dm0092_1)

Title

georoute -- Calculate travel distance and travel time
between two addresses or two points identified by their
geographical coordinates

Syntax

georoute
[if] [in],
herekey(api_key)
{startaddress(varlist) | startxy(xvar yvar)}
{endaddress(varlist) | endxy(xvar yvar)}
[options]

Command with immediate arguments:

georoutei,
herekey(api_key)
{startaddress(string) | startxy(#x, #y)}
{endaddress(string) | endxy(#x, #y)}
[options]

Compulsory arguments
herekey(api_key) API KEY of the HERE application to be used

* startaddress(varlist) address of departure

* startxy(xvar yvar) coordinates of departure

* endaddress(varlist) address of destination

* endxy(xvar yvar) coordinates of destination

Routing options
* tmode(string|varname) transport mode

* rtype(string|varname) routing type

* dtime({string,mask}|varname|"now"|"any") date and time of departure

avoid(string) avoid specific routing features

New variables
° distance(newvar) new variable to record travel distance

° time(newvar) new variable to record travel time

° diagnostic(newvar) new variable to record diagnostic code

° coordinates(str1 str2) prefixes of new variables to record coordinates and query score

° replace overwrite existing variables

Reporting
km return travel distance in kilometers rather than the default miles

° timer print a timer to indicate evolution of geocoding

° pause pause for 30 seconds after every 100th observation is geocoded

° observations print a detailed observation account

nosettings suppress settings report

* These options only accept string arguments (no variables) when used with the
immediate command georoutei.

° These options are not available (irrelevant) with the immediate command
georoutei.

Description

georoute calculates the georouting distance between two addresses or two
points identified by their geographical coordinates. It uses the HERE API
(https://developer.here.com) to retrieve distances in two steps.
In the first step, addresses are geocoded and their geographical coordinates
(latitude and longitude) are obtained. In the second step, the georouting
distance between the two points is calculated. The user can also directly
provide geographical coordinates, which will bypass the first step. Most
features offered by the HERE API are available as options.

georoutei is an immediate version of georoute, that is, a command
in which all arguments must be typed in rather than included in variables (see
immed). georoutei is useful for quick interactive requests and
preliminary checks.

Requirements

Before using georoute, the user must register for a HERE account at
https://developer.here.com and create an application that can be
used with HERE APIs. The API key of the application must be provided via
herekey().

georoute requires a connection to the Internet.

georoute uses the community-contributed commands insheetjson and
libjson. Type ssc install insheetjson and
ssc install libjson to load the necessary packages.

Options

Main (compulsory)

herekey(api_key) provides the credentials of the HERE application to be
used. herekey() is required. See https://developer.here.com
to create an application and obtain its API key.

startaddress(varlist) and endaddress(varlist) specify the
addresses of departure and destination, respectively. Addresses can be
inserted as a single variable or a variable list. Alternatively,
startxy() and endxy() can be used. Either startaddress() or
startxy() is required; either endaddress() or endxy() is
required.

Note: Special characters (for example, French accents) in addresses may cause
the geocoding process to fail. Such characters should be transformed before
running georoute, for example, by using subinstr().

startxy(xvar yvar) and endxy(xvar yvar) specify the geographical
coordinates (in decimal degrees) of the departure and destination points,
respectively. xvar and yvar must be numeric variables containing
latitude (x) and longitude (y) coordinates of the starting and
ending points. Alternatively, startaddress() and endaddress() can
be used. Either startxy() or startaddress() is required; either
endxy() or endaddress() is required.

Note: Latitude (x) must be between -90 and 90, and longitude (y)
must be between -180 and 180. Examples of coordinates:

- United States Capitol: 38.8897, -77.0089

- Eiffel Tower: 48.8584, 2.2923

- Cape Horn: -55.9859, -67.2743

- Pearl Tower: 31.2378, 121.5225

Routing options

tmode(string|varname) specifies the transport mode. The following
strings are available transport modes (see also
HERE documentation
for details):

- "car" (default)

- "publicTransit"

- "pedestrian"

- "bicycle"

The transport mode can be specified either via a string (for instance,
tmode("car")) or via a variable (for instance, tmode(vehicle)).
When a string is used, all observations will use the same transport mode.
When a variable is used, it is possible to specify the transport mode at the
observation level, in which case the variable must be a string variable
composed of the transport modes exactly as above (including capitalization).
Any missing values will be assigned the default transport mode ("car").

rtype(string|varname) specifies the routing type. The following
strings are available routing types (see also
HERE documentation
for details):

- "fast" (default)

- "short"

Routing types can be specified either via a string (for instance,
rtype("fast")) or via a variable (for instance, rtype(routing)).
When a string is used, all observations will use the same routing type. When
a variable is used, it is possible to specify the routing type at the
observation level, in which case the variable must be a string variable
composed of the routing types exactly as above (possibly abbreviated). Any
missing values will be assigned the default routing type ("fast").

dtime({string,mask}|varname|"now"|"any")
specifies the date and time travel is expected to start (see also
HERE documentation
for details). The default is dtime("now"), that is, the current time as
of running the calculation. It is also possible to use dtime("any") to specify a route without a specific departure time.
Note that sending the same request with departure time set to dtime("any") at different times may result in different responses.

Departure time can be specified either via a string and a mask (for instance,
dtime("01Nov2020 08:00:00", "DMYhms"); see clock) or via a
variable (for instance, dtime(t)). When a string is used, all
observations will use the same departure time. When a variable is used, it is
possible to specify the departure time at the observation level, in which case
the format of the variable must be %tc or %tC. Any missing values
will be assigned the default departure time ("now").

dtime() has no impact for transport modes "pedestrian" and
"bicycle". The extent to which it is possible to calculate travel times
in the past depends on other parameters, in particular, the transport mode
specified in tmode(). Moreover, it seems that historical traffic data
are only available from the HERE API for a few months back, resulting in a
travel time independent of departure time for older time periods.

avoid(string) can be used to specify routing features to be avoided.
The following strings are available routing features (see also
HERE documentation
for details):

- "tollRoad"

- "ferry"

- "tunnel"

- "dirtRoad"

New variables

distance(newvar) creates the new variable containing the travel
distance between the departure and destination points. By default, travel
distance will be stored in a variable named travel_distance.

time(newvar) creates the new variable containing the travel time
between the departure and destination points. By default, travel time will be
stored in a variable named travel_time.

diagnostic(newvar) creates the new variable containing a diagnostic
code for the geocoding and georouting outcome of each observation in the
database: 0 = OK, 1 = No route found, 2 =
Start and/or end not geocoded, 3 =
Start and/or end coordinates missing, and 4 =
No route searched. By default, the codes will be stored in a variable
named georoute_diagnostic.

coordinates(str1 str2) creates new variables
str1_x, str1_y, str1_score,
str2_x, str2_y, and str2_score, which contain
the coordinates and the query score of the starting (str1_x,
str1_y, str1_score) and ending (str2_x,
str2_y, str2_score) addresses. This option is
irrelevant if geographical coordinates (rather than addresses) are provided.
By default, coordinates and query score are not saved. The query score is a value
from 0 to 1 representing the percentage of the input that matched the returned address.

replace specifies that the variables in distance(), time(),
diagnostic(), and coordinates() be replaced if they already exist
in the database. replace should be used cautiously because it might
definitively drop some data.

Reporting

km specifies that distances be returned in kilometers. The default is
to return distances in miles.

timer requests that a timer be printed while geocoding. If specified, a
dot is printed for every centile of the dataset that has been geocoded, and a
number is printed every 10%.

pause slows the geocoding process by asking Stata to sleep for 30
seconds every 100th observation. This could be useful for large databases,
which might overload the HERE API and result in missing values for batches of
observations.

observations prints a detailed observation account, showing how many
observations were discarded and why.

nosettings suppresses display of the settings report.

Examples

Input some data

. input str60 address1 str60 address2 str20 vehicle

. "Rue de la Tambourine 17, 1227 Carouge, Switzerland" "Rue Abram-Louis Breguet 2, 2000 Neuchatel, Switzerland" "car"

. "Rue de la Tambourine 17, 1227 Carouge, Switzerland" "Rue Abram-Louis Breguet 2, 2000 Neuchatel, Switzerland" "publicTransit"

. "Rue de la Tambourine 17, 1227 Carouge, Switzerland" "Rue Abram-Louis Breguet 2, 2000 Neuchatel, Switzerland" "bicycle"

. "1003 Lausanne, Switzerland" "74500 Evian, France" "car"

. "Paris, France" "New York, USA" "car"

. "1003 Lausanne, Switzerland" "1203 Geneva, Switzerland" "car"

. end

Compute travel distances and travel times (use your own API key to run this example)

. global apikey 0wxsecZz7uLgpLTMuO5ae19dPx0RwparL1U91yxQOVE

. georoute, herekey("$apikey") startad(address1) endad(address2) km di(dist) ti(time) co(p1 p2)

. georoute, herekey("$apikey") startad(address1) endad(address2) km tmode(vehicle) observations

Use the immediate command

. georoutei, herekey("$apikey") startad("Rue de la Tambourine 17, 1227 Carouge, Switzerland") endad("Rue Abram-Louis Breguet 2, 2000 Neuchatel, Switzerland") km

. georoutei, herekey("$apikey") startxy(46.1761413, 6.1393099) endxy(46.99382, 6.94049) km

Stored results

georoute stores results in different variables (see section
New variables above).

georoutei stores the following in r():

Scalars

r(dist) travel distance

r(time) travel time

r(startx) x coordinate (latitude) of departure point

r(starty) y coordinate (longitude) of departure point

r(endx) x coordinate (latitude) of destination point

r(endy) y coordinate (longitude) of destination point

Authors

Sylvain Weber

University of Applied Sciences Western Switzerland (HES-SO)

Geneva, Switzerland

sylvain.weber@hesge.ch

Martin Péclat

Romande Energie

Morges, Switzerland

martin.peclat@bluewin.ch

August Warren

Office of the State Superintendent of Education

Washington, DC

augustjwarren@gmail.com

Also see

Article: Stata Journal, volume 22, number 1: dm0092_1,

Stata Journal, volume 17, number 4: dm0092