--- 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" ```