README

The function gmapsdistance uses the Google Maps Distance Matrix API to compute the distance(s) and time(s) between two points or two vectors of points using one of the four defined modes of transportation: bicycling, walking, driving, transit. The distance is returned in meters and the time in seconds.

An API key is necessary to perform the query. Google maps must be able to find both the origin and the destination in order for the function to run.

While the R package is open source the Distance Matrix API itself is a commercial service, requiring registration in all cases.

A free tier is provided - $200 monthly credit. This is enough for 40,000 Distance Matrix calls or 20,000 Distance Matrix Advanced calls – more than sufficient for most R package users.

Installation

# CRAN install / stable version 
install.packages("gmapsdistance")

# Github installation / current dev version
remotes::install_github("jlacko/gmapsdistance")

Examples of use

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).

results <- gmapsdistance(origin = "Washington DC", 
                        destination = "New York City NY", 
                        mode = "driving",
                        key = Sys.getenv("GOOGLE_API_KEY")) # your actual API key comes here...
results
# $Time
# [1] 14523
# 
# $Distance
# [1] 367656
# 
# $Status
# [1] "OK"

This example computes distance matrix between two vectors of cities at a specific departure time. The code displays resulting distance matrices using time (in seconds) and travel distance (in meters) as metrics.

results <- gmapsdistance(origin = c("Washington DC", "New York NY", "Seattle WA", "Miami FL"), 
                         destination = c("Washington DC", "New York NY", "Seattle WA", "Miami FL"), 
                         mode = "bicycling",
                         dep_date = "2022-05-31", # provided as string in ISO 8601 format
                         dep_time = "12:00:00", # provided as string in HH:MM:SS format
                         key = Sys.getenv("GOOGLE_API_KEY")) # your actual API key comes here...
                        
results$Time
#               Washington DC New York NY Seattle WA Miami FL
# Washington DC             0       76753     893416   353377
# New York NY           76537           0     917724   429533
# Seattle WA           890818      922255          0  1045150
# Miami FL             350851      427721    1048150        0

results$Distance
#               Washington DC New York NY Seattle WA Miami FL
# Washington DC             0      388695    4762468  1919628
# New York NY          384224           0    5028313  2303263
# Seattle WA          4754835     5049618          0  5638340
# Miami FL            1909272     2298117    5651681        0

Usage limits

There are a set of limits to the number of calls that can be done. These limits are established by the Google Maps Distance Matrix API

License

How to contribute

We encourage any kind of suggestions to improve the quality of this code. You can submit pull requests indicating clearly what is the purpose of the change and why we should accept such pull request. Although not necessary, we encourage you to verify that your suggestions are in accordance with the general guidelines established in the CRAN repository by running the R CMD check command.

Code of conduct

Please see the file CODE_OF_CONDUCT.md for the Code of Conduct for the Contributor Covenant Code of Conduct.

Authors

Where has gmapsdistance be used/mentioned.

We like to keep track of the projects where gmapsdistance has been used. This will help us identify how to better improve the code. Let us know if you use gmapsdistance! Below you will find links to some of the projects and some of the references to gmapsdistance that we have found.

gmapsdistance

Interface Between R and Google Maps