geocode_url: Geocode an address vector using the Google Maps API.
In DerekYves/gcoder: Tools for accessing the Google Maps API

Description Usage Arguments Value Examples

View source: R/geocode_url.R

geocode_url uses the Google Maps API to estimate latitude and longitude coordinates for a character vector of physical addresses. Optionally, one may use their (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).

1 2	geocode_url(address, auth = "standard_api", privkey = NULL, clientid = NULL, clean = FALSE, verbose = FALSE, add_date = "none")

`address`	A 1xN vector of address(es) with "url-safe" characters. Enabling the "clean" parameter calls the `address_cleaner` function will strip or replace common character patterns in the vector that are incompatible with the Maps API. Note: addresses should be in raw form, not URL encoded (e.g., of the form: 123 Main Street, Somewhere, NY 12345, USA). Note: country is optional but recommended.
`auth`	character string; one of: "standard_api" (the default) or "work". Authentication via the standard API requires a (free) Google API key. Authentication via the "work" method requires the client ID and 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, these are 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 vector prior to URL encoding.
`verbose`	logical; when TRUE, displays additional output in the returns from Google.
`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 geocode estimations after a fixed period of time.

Geocode_url returns a data frame with (numeric) lat/long coordinates and two additional parameters from the response object (see this page for additional information):

location_type: an estimate of the response object's coordinate accuracy. Currently, possible response values are:
- ROOFTOP: indicates that the return is accurate to the level of a precise street address.
- RANGE_INTERPOLATED: indicates that the result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
- GEOMETRIC_CENTER: indicates that the result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
- APPROXIMATE: indicates that the result is approximate.
status: the geocode status of a response object. Currently, possible response values 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.

# Get coordinates for the White House and 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)

# View the returns
print(coordset[ , 1:5])