---
title: "gmapsdistance package in use"
author: "Jindra Lacko"
date: "2023-08-04"
output:
  rmarkdown::html_vignette:
    toc: true
self_contained: no
vignette: >
  %\VignetteIndexEntry{Examples of using `{gmapsdistance}` package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



## Setting up API key
The [Google Distance Matrix API](https://mapsplatform.google.com/) requires registration, and an API key is required in each function call. It is possible to store the key for duration of a R session by using `gmapsdistance::set.api.key()` call.

Note that in order to keep the maintainers API key private it has been stored locally in an environment variable; in the most frequent use cases it can be used in plain text.


```r
library(gmapsdistance)
set.api.key(Sys.getenv("GOOGLE_API_KEY"))
```

## Distance between cities
In this example we will compute the driving distance between Washington DC, and New York City. The code returns the `Time`, the `Distance` and the `Status` of the query (`OK` if it was successful). The calculation will be made using the "driving" method, which is the default.


```r
results = gmapsdistance(origin = "Washington DC",
                        destination = "New York City NY")
results
## $Distance
## [1] 367228
## 
## $Time
## [1] 14226
## 
## $Status
## [1] "OK"
```

## Walking distance between GPS coordinates
In this example we will compute the driving distance between the Greek cities of
Marathon and Athens. We show that the function is able to handle LAT-LONG coordinates.


```r
results = gmapsdistance(origin = "38.1621328 24.0029257",
                        destination = "37.9908372 23.7383394",
                        mode = "walking")
results
## $Distance
## [1] 39461
## 
## $Time
## [1] 30005
## 
## $Status
## [1] "OK"
```

## Distance matrix at a specific departure time
This example computes the travel distance and time matrices between two vectors of cities at a specific departure time

```r
results = gmapsdistance(origin = c("Washington DC", "New York NY",
                                   "Seattle WA", "Miami FL"),
                        destination = c("Los Angeles CA", "Austin TX",
                                        "Chicago IL", "Philadelphia PA"),
                        mode = "bicycling",
                        # departure time as seconds from Unix Epoch (1970-01-01)
                        departure = 1700000000)
results
## $Distance
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC        4957002   3061364    1282178          243903
## New York NY          5197630   3301993    1496610          161365
## Seattle WA           2005074   3882730    3693196         5073667
## Miami FL             4884238   2506490    2464451         2250540
## 
## $Time
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC         926961    582890     251682           48884
## New York NY           973247    629175     294187           32036
## Seattle WA            381741    724448     695072          968045
## Miami FL              903097    460103     468328          427070
## 
## $Status
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC "OK"           "OK"      "OK"       "OK"           
## New York NY   "OK"           "OK"      "OK"       "OK"           
## Seattle WA    "OK"           "OK"      "OK"       "OK"           
## Miami FL      "OK"           "OK"      "OK"       "OK"
# Equivalently
results = gmapsdistance(origin = c("Washington DC", "New York NY",
                                   "Seattle WA", "Miami FL"),
                        destination = c("Los Angeles CA", "Austin TX",
                                        "Chicago IL", "Philadelphia PA"),
                        mode = "bicycling",
                        dep_date = "2023-11-14",
                        dep_time = "23:13:20")

results
## $Distance
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC        4957002   3061364    1282178          243903
## New York NY          5197630   3301993    1496610          161365
## Seattle WA           2005074   3882730    3693196         5073667
## Miami FL             4884238   2506490    2464451         2250540
## 
## $Time
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC         926961    582890     251682           48884
## New York NY           973247    629175     294187           32036
## Seattle WA            381741    724448     695072          968045
## Miami FL              903097    460103     468328          427070
## 
## $Status
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC "OK"           "OK"      "OK"       "OK"           
## New York NY   "OK"           "OK"      "OK"       "OK"           
## Seattle WA    "OK"           "OK"      "OK"       "OK"           
## Miami FL      "OK"           "OK"      "OK"       "OK"
```

## Long format of distance matrix
This example computes the travel distance and time matrices between two vectors of cities and return the results in long format

```r
origin = c("Washington DC", "New York NY", "Seattle WA", "Miami FL")
destination = c("Los Angeles CA", "Austin TX", "Chicago IL")

results = gmapsdistance(origin,
                        destination,
                        mode = "driving",
                        shape = "long")

results
## $Distance
##               or             de Distance
## 1  Washington DC Los Angeles CA  4295163
## 2    New York NY Los Angeles CA  4488402
## 3     Seattle WA Los Angeles CA  1829326
## 4       Miami FL Los Angeles CA  4401120
## 5  Washington DC      Austin TX  2451233
## 6    New York NY      Austin TX  2804800
## 7     Seattle WA      Austin TX  3409450
## 8       Miami FL      Austin TX  2171268
## 9  Washington DC     Chicago IL  1120330
## 10   New York NY     Chicago IL  1271030
## 11    Seattle WA     Chicago IL  3329491
## 12      Miami FL     Chicago IL  2222034
## 
## $Time
##               or             de   Time
## 1  Washington DC Los Angeles CA 139080
## 2    New York NY Los Angeles CA 146528
## 3     Seattle WA Los Angeles CA  62510
## 4       Miami FL Los Angeles CA 140812
## 5  Washington DC      Austin TX  80342
## 6    New York NY      Austin TX  92688
## 7     Seattle WA      Austin TX 116746
## 8       Miami FL      Austin TX  69791
## 9  Washington DC     Chicago IL  39529
## 10   New York NY     Chicago IL  43252
## 11    Seattle WA     Chicago IL 107630
## 12      Miami FL     Chicago IL  72296
## 
## $Status
##               or             de status
## 1  Washington DC Los Angeles CA     OK
## 2    New York NY Los Angeles CA     OK
## 3     Seattle WA Los Angeles CA     OK
## 4       Miami FL Los Angeles CA     OK
## 5  Washington DC      Austin TX     OK
## 6    New York NY      Austin TX     OK
## 7     Seattle WA      Austin TX     OK
## 8       Miami FL      Austin TX     OK
## 9  Washington DC     Chicago IL     OK
## 10   New York NY     Chicago IL     OK
## 11    Seattle WA     Chicago IL     OK
## 12      Miami FL     Chicago IL     OK
```

## Distance matrix between GPS coordinates
This example computes the travel distance and time between two vectors of cities defined as LAT-LONG coordinates.


```r
origin = c("40.431478 -80.0505401", "33.7678359 -84.4906438")
destination = c("43.0995629 -79.0437609", "41.7096483 -86.9093986")

results = gmapsdistance(origin,
                        destination,
                        mode="bicycling",
                        shape="long")

results
## $Distance
##                       or                     de Distance
## 1  40.431478 -80.0505401 43.0995629 -79.0437609   406350
## 2 33.7678359 -84.4906438 43.0995629 -79.0437609  1616369
## 3  40.431478 -80.0505401 41.7096483 -86.9093986   715128
## 4 33.7678359 -84.4906438 41.7096483 -86.9093986  1178992
## 
## $Time
##                       or                     de   Time
## 1  40.431478 -80.0505401 43.0995629 -79.0437609  83792
## 2 33.7678359 -84.4906438 43.0995629 -79.0437609 322432
## 3  40.431478 -80.0505401 41.7096483 -86.9093986 136114
## 4 33.7678359 -84.4906438 41.7096483 -86.9093986 235381
## 
## $Status
##                       or                     de status
## 1  40.431478 -80.0505401 43.0995629 -79.0437609     OK
## 2 33.7678359 -84.4906438 43.0995629 -79.0437609     OK
## 3  40.431478 -80.0505401 41.7096483 -86.9093986     OK
## 4 33.7678359 -84.4906438 41.7096483 -86.9093986     OK
```

## Combination of distances
This example computes the travel distance and time between two vectors of cities using the 'combinations' option.


```r
# 1. Pairwise

or = c("Washington DC", "New York NY", "Seattle WA", "Miami FL")
des = c("Los Angeles CA", "Austin TX", "Chicago IL", "Philadelphia PA")

results = gmapsdistance(origin = or,
                        destination = des,
                        mode = "bicycling",
                        combinations = "pairwise")
results
## $Distance
##              or              de Distance
## 1 Washington DC  Los Angeles CA  4957002
## 2   New York NY       Austin TX  3301993
## 3    Seattle WA      Chicago IL  3693196
## 4      Miami FL Philadelphia PA  2250540
## 
## $Time
##              or              de   Time
## 1 Washington DC  Los Angeles CA 926961
## 2   New York NY       Austin TX 629175
## 3    Seattle WA      Chicago IL 695072
## 4      Miami FL Philadelphia PA 427070
## 
## $Status
##              or              de status
## 1 Washington DC  Los Angeles CA     OK
## 2   New York NY       Austin TX     OK
## 3    Seattle WA      Chicago IL     OK
## 4      Miami FL Philadelphia PA     OK

# 2. All combinations of origins and destinations in wide format
results = gmapsdistance(origin = or,
                        destination = des,
                        mode = "bicycling",
                        combinations = "all",
                        shape = "wide")
results
## $Distance
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC        4957002   3061364    1282178          243903
## New York NY          5197630   3301993    1496610          161365
## Seattle WA           2005074   3882730    3693196         5073667
## Miami FL             4884238   2506490    2464451         2250540
## 
## $Time
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC         926961    582890     251682           48884
## New York NY           973247    629175     294187           32036
## Seattle WA            381741    724448     695072          968045
## Miami FL              903097    460103     468328          427070
## 
## $Status
##               Los Angeles CA Austin TX Chicago IL Philadelphia PA
## Washington DC "OK"           "OK"      "OK"       "OK"           
## New York NY   "OK"           "OK"      "OK"       "OK"           
## Seattle WA    "OK"           "OK"      "OK"       "OK"           
## Miami FL      "OK"           "OK"      "OK"       "OK"

results = gmapsdistance(origin = or,
                        destination = des,
                        mode = "bicycling",
                        combinations = "all",
                        shape = "long")
results
## $Distance
##               or              de Distance
## 1  Washington DC  Los Angeles CA  4957002
## 2    New York NY  Los Angeles CA  5197630
## 3     Seattle WA  Los Angeles CA  2005074
## 4       Miami FL  Los Angeles CA  4884238
## 5  Washington DC       Austin TX  3061364
## 6    New York NY       Austin TX  3301993
## 7     Seattle WA       Austin TX  3882730
## 8       Miami FL       Austin TX  2506490
## 9  Washington DC      Chicago IL  1282178
## 10   New York NY      Chicago IL  1496610
## 11    Seattle WA      Chicago IL  3693196
## 12      Miami FL      Chicago IL  2464451
## 13 Washington DC Philadelphia PA   243903
## 14   New York NY Philadelphia PA   161365
## 15    Seattle WA Philadelphia PA  5073667
## 16      Miami FL Philadelphia PA  2250540
## 
## $Time
##               or              de   Time
## 1  Washington DC  Los Angeles CA 926961
## 2    New York NY  Los Angeles CA 973247
## 3     Seattle WA  Los Angeles CA 381741
## 4       Miami FL  Los Angeles CA 903097
## 5  Washington DC       Austin TX 582890
## 6    New York NY       Austin TX 629175
## 7     Seattle WA       Austin TX 724448
## 8       Miami FL       Austin TX 460103
## 9  Washington DC      Chicago IL 251682
## 10   New York NY      Chicago IL 294187
## 11    Seattle WA      Chicago IL 695072
## 12      Miami FL      Chicago IL 468328
## 13 Washington DC Philadelphia PA  48884
## 14   New York NY Philadelphia PA  32036
## 15    Seattle WA Philadelphia PA 968045
## 16      Miami FL Philadelphia PA 427070
## 
## $Status
##               or              de status
## 1  Washington DC  Los Angeles CA     OK
## 2    New York NY  Los Angeles CA     OK
## 3     Seattle WA  Los Angeles CA     OK
## 4       Miami FL  Los Angeles CA     OK
## 5  Washington DC       Austin TX     OK
## 6    New York NY       Austin TX     OK
## 7     Seattle WA       Austin TX     OK
## 8       Miami FL       Austin TX     OK
## 9  Washington DC      Chicago IL     OK
## 10   New York NY      Chicago IL     OK
## 11    Seattle WA      Chicago IL     OK
## 12      Miami FL      Chicago IL     OK
## 13 Washington DC Philadelphia PA     OK
## 14   New York NY Philadelphia PA     OK
## 15    Seattle WA Philadelphia PA     OK
## 16      Miami FL Philadelphia PA     OK
```

## Using optional parameters - traffic model and avoidance
This example show the use of traffic model and avoidance parameters, while setting the API key directly in function call.
Note that in order to keep the maintainers API key private it has been stored locally in an environment variable; in the most frequent use cases it can be used in plain text.


```r
APIkey <- Sys.getenv("GOOGLE_API_KEY") # your actual API key would go here...

# Time and distance using a 'pessimistic' traffic model.
results = gmapsdistance(origin = c("Washington DC", "New York NY"),
                        destination = c("Los Angeles CA", "Austin TX"),
                        mode = "driving",
                        dep_date = "2023-11-14",
                        dep_time = "23:13:20",
                        traffic_model = "pessimistic",
                        shape = "long",
                        key=APIkey)
results
## $Distance
##              or             de Distance
## 1 Washington DC Los Angeles CA  4295037
## 2   New York NY Los Angeles CA  4488684
## 3 Washington DC      Austin TX  2450825
## 4   New York NY      Austin TX  2802486
## 
## $Time
##              or             de   Time
## 1 Washington DC Los Angeles CA 139116
## 2   New York NY Los Angeles CA 146584
## 3 Washington DC      Austin TX  80322
## 4   New York NY      Austin TX  92625
## 
## $Status
##              or             de status
## 1 Washington DC Los Angeles CA     OK
## 2   New York NY Los Angeles CA     OK
## 3 Washington DC      Austin TX     OK
## 4   New York NY      Austin TX     OK

# Time and distance avoiding 'tolls'.
results = gmapsdistance(origin = c("Washington DC", "New York NY"),
                        destination = c("Los Angeles CA", "Austin TX"),
                        mode = "driving",
                        avoid = "tolls",
                        key=APIkey)

results
## $Distance
##               Los Angeles CA Austin TX
## Washington DC        4302413   2458491
## New York NY          4605786   2799342
## 
## $Time
##               Los Angeles CA Austin TX
## Washington DC         139703     80953
## New York NY           151405     93119
## 
## $Status
##               Los Angeles CA Austin TX
## Washington DC "OK"           "OK"     
## New York NY   "OK"           "OK"
```

## Using "foreign" place names
It is perfectly possible to use names in non-ASCII characters; care must be however made that all characters are encoded in UTF-8 though. This may not be the obvious first choice of encoding, especially in Windows environments.


```r
results = gmapsdistance(origin = "вулиця Хрещатик, Київ",
                        destination = "Майдан Незалежності, Київ",
                        mode = "walking")
results
## $Distance
## [1] 488
## 
## $Time
## [1] 390
## 
## $Status
## [1] "OK"
```
