drive_time: Get travel time and distance between two point using the...

In DerekYves/gcoder: Tools for accessing the Google Maps API

Description

This function uses the Google Maps API to estimate travel time and distance between two physical addresses. Optionally, one may use a (paid) Google for Work API key to sign the request with the hmac sha1 algorithm. For smaller batch requests, it is also possible to access Google's "standard API" with this function (see this page to obtain a free API key).

Usage

drive_time(address, dest, auth = "standard_api", privkey = NULL,
  clientid = NULL, clean = "TRUE", travel_mode = "driving",
  units = "metric", verbose = FALSE, add_date = "none",
  language = "en-EN")

Arguments

address	A 1xN vector of locations. These may be either (1) latitude and longitude coordinates (formatted as "lat,long" with no spaces) or physical addresses that contain "url-safe" UTF-8 characters. Enabling the "clean" parameter (see below) attempts to strip or replace common character patterns from physical addresses that are incompatible with the Maps API key. This vector becomes the starting point of the distance calculation. If the length of this parameter is 1 and destination's length is greater than 1, address is replicated to match the length of destination (e.g., when you are calculating distances between one specific location and two or more destinations). Note: addresses should be in raw form, not URL encoded (e.g., of the form: 123 Main Street, Somewhere, NY 12345 USA)(country is optional but recommended).
dest	A 1xN vector of destinations. These may be either (1) latitude and longitude coordinates (formatted as "lat,long" with no spaces) or physical addresses that contain "url-safe" UTF-8 characters.
auth	character string; one of: "work" (the default), or "standard_api". While you may specify and empty string for privkey when using the standard API, for some direction types (e.g., transit) a (free) API key from Google is required (see this page. Authentication via the "work" method requires the private API key associated with your (paid) Google for Work account.
privkey	character string; your Google API key (whether of the "work" or "standard_api" variety).
clientid	character string; your Google for Work client id (generally of the form 'gme-[company]') This parameter should not be set when authenticating through the standard API.
clean	logical; when TRUE, applies address_cleaner to the address and destination vectors.
travel_mode	character string; currently, valid values include (see this page for details): driving (the default): indicates standard driving directions using the road network. transit: requests directions via public transit routes (requires and API key). walking: requests walking directions via pedestrian paths & sidewalks (where available). bicycling: requests bicycling directions via bicycle paths & preferred streets (currently only available in the US and some Canadian cities).
units	character string; must be either "metric" (the default) or "imperial". Specifying "metric" will return distance between origin and destination as kilometers, whereas "imperial" returns distance in miles. For geocode requests this parameter is ignorned if non-null.
verbose	logical; when TRUE, displays additional progress output.
add_date	character string; one of: "none" (the default), "today", or "fuzzy". When set to "today", a column with today's calendar date is added to the returned data frame. When set to "fuzzy", a random positive number of days between 1 and 30 is added to this date column. "Fuzzy" date values can be useful to avoid sending large batches of geocode requests on the same day if your scripts recertify/retry distance calculations after a fixed period of time.
language	character string; localization of the returned object. This set to "en-EN" by default, but refer to this page for an up-to-date list of all supported languages.

Value

#' Drive_time returns a data frame with the following parameters stored from the response object:

• distance: The distance between address[i] and dest[i] in kilometers.

• travel_time: The estimated travel time given the specified mode of transportation.

• status: The status field of the response object. Currently, these are:

  • OK: Indicates that no errors occurred; the address was successfully parsed and at least one geocode was returned.

  • ZERO_RESULTS: Indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.

  • OVER_QUERY_LIMIT: Indicates that you are over your quota.

  • REQUEST_DENIED: Indicates that your request was denied.

  • INVALID_REQUEST: Indicates that some part of the query (address, URL components, etc.) is missing.

  • UNKNOWN_ERROR: indicates that the request could not be processed due to a server error. The request may succeed if you try again.

Examples

# Bike from the White House to Google!
address <- c("1600 Pennsylvania Ave NW, Washington, DC 20500, USA",
			 "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA")

coordset <- geocode_url(address, auth="standard_api", privkey="",
            clean=TRUE, add_date='today', verbose=TRUE)

# Save coordinates. Google requires a format of: "lat,lng" (with no spaces)
from <- paste(coordset$lat[1],coordset$lng[1], sep=",")
dest <- paste(coordset$lat[2],coordset$lng[2], sep=",")

# Get the travel time by bike (a mere 264 hours!) and distance in miles:
howfar_miles <- drive_time(address=from, dest=dest, auth="standard_api",
						   privkey="", clean=FALSE, add_date='today',
						   verbose=FALSE, travel_mode="bicycling",
						   units="imperial")

# Get the distance in kilometers using physical addresses instead of lat/lng:
howfar_kms <- drive_time(
     address="1600 Pennsylvania Ave NW, Washington, DC 20500, USA",
		dest="1600 Amphitheatre Pkwy, Mountain View, CA 94043",
		auth="standard_api", privkey="", clean=FALSE,
		add_date='today', verbose=FALSE, travel_mode="bicycling",
		units="metric"
		)

with(howfar_kms, cat("Travelling from the White House to ", destination,
					 ":\n", dist_txt, "\n", time_txt, sep=""))

DerekYves/gcoder documentation built on May 6, 2019, 2:10 p.m.