prettymapr (version 0.2.5)

geocode: Geocode Locations

Description

Geocode locations using the Google Web API, the PickPoint.io API, or the Data Science Toolkit API. For large requests you should really use your own API key if you are using the default (pickpoint). Note that the Google Terms seem to indicate that you cannot place locations obtained from their API on non-google maps. Locations are all geocoded with erorrs kept quiet, which may result in list output containing items with a $status element describing the error message, or data frame output containing a non-OK status in the status column.

Usage

geocode(
  location,
  output = c("data.frame", "list"),
  source = "default",
  messaging = NULL,
  limit = 1,
  key = NULL,
  quiet = TRUE,
  cache = NA,
  progress = c("time", "text", "none"),
  ...
)

Value

A list or data.frame; see documentation for

output argument.

Arguments

location

A character vector (or an object that can be coerced to one) of locations to pass to the geocoding API.

output

One of data.frame or list. If data.frame, the results are distilled into columns: query, source, status, rank, lon, lat, address, bbox_n, bbox_e, bbox_s, and bbox_w. Other columns may also exist for certain API types. The data frame will have the same number of rows as the length of the input vector, and will always have the columns query, source, status, lon and lat. If output='list', the raw JSON output from the geocoding API is returned as a list (containing lists). The list output of a failed geocode return varies by API type, but the length of the output list is guaranteed to be the same as the input vector.

source

One of "default", "google", "pickpoint", or "dsk". If "default", the function calls getOption("prettymapr.geosource") or chooses "pickpoint" if none is set. If using "pickpoint", please sign up for your own (free) API key to avoid using the default excessively.

messaging

TRUE if verbose messaging is desired (now deprecated, use 'quiet = FALSE' instead.

limit

The number of results to return per query. This refers to individual locations, for which ambiguous queries may return multiple results (e.g. Halifax, Nova Scotia; Halifax, United Kingdom, etc.). The default is 1. Pass 0 if no limit on queries is desired.

key

API key if source="pickpoint".

quiet

By default, error messages are suppressed, and are instead included in the output as objects with a $status describing the error (list output) or the appropriate value in the 'status' column (data frame output).

cache

The cache to use. Use NA for the internal cache (keeps first 1000 results), or a directory name (e.g. 'geo.cache'), which keeps an unlimited number of results. Use clear_geocode_cache to clear the cache.

progress

A plyr status bar, one of "time", "text", or "none". Passing quiet = FALSE will also disable the progress bar.

...

A number of key/value pairs to append to the URL, specifying further options specific to each API. Google users may wish to provide sensor, client and signature arguments for use with the enterprise version with the API, or to specify additional constraints on geocoding.

Examples

if (FALSE) { # identical(Sys.getenv("R_PRETTYMAPR_HAS_API_KEY"), "true")
# don't test to speed up checking time
# \donttest{
geocode("wolfville, ns")
geocode("wolfville, ns", output="list")
geocode("halifax", limit=0)
geocode("Paddy's Pub Wolfville NS", source="google")
geocode(c("Houston, TX", "San Antonio TX", "Cleavland OH"), source="google")

#fails quietly
geocode("don't even think about geocoding this")
geocode("don't even think about geocoding this", output="list")
# }
}