#' Get a Google Map.
#'
#' \code{get_googlemap} accesses the Google Static Maps API version
#' 2 to download a static map. Note that in most cases by using
#' this function you are agreeing to the Google Maps API Terms of
#' Service at \url{https://developers.google.com/maps/terms}.
#'
#' @param center the center of the map. Either a longitude/latitude
#' numeric vector, a string address (note that the latter uses
#' \code{geocode} with \code{source = "google"}).
#' @param zoom map zoom, an integer from 3 (continent) to 21
#' (building), default value 10 (city)
#' @param size rectangular dimensions of map in pixels - horizontal
#' x vertical - with a max of c(640, 640). this parameter is
#' affected in a multiplicative way by scale.
#' @param scale multiplicative factor for the number of pixels
#' returned possible values are 1, 2, or 4 (e.g. size = c(640,640)
#' and scale = 2 returns an image with 1280x1280 pixels). 4 is
#' reserved for google business users only. scale also affects
#' the size of labels as well.
#' @param format character string providing image format - png,
#' jpeg, and gif formats available in various flavors
#' @param maptype character string providing google map theme.
#' options available are "terrain", "satellite", "roadmap", and
#' "hybrid"
#' @param language character string providing language of map labels
#' (for themes with them) in the format "en-EN". not all
#' languages are supported; for those which aren't the default
#' language is used
#' @param sensor specifies whether the application requesting the
#' static map is using a sensor to determine the user's location
#' @param messaging turn messaging on/off
#' @param urlonly return url only
#' @param filename destination file for download (file extension
#' added according to format)
#' @param color color or black-and-white
#' @param force if the map is on file, should a new map be looked
#' up?
#' @param where where should the file drawer be located (without
#' terminating "/")
#' @param archiving use archived maps. note: by changing to TRUE
#' you agree to the one of the approved uses listed in the Google
#' Maps API Terms of Service :
#' http://developers.google.com/maps/terms.
#' @param key an api_key for business users
#' @param region borders to display as a region code specified as a
#' two-character ccTLD ("top-level domain") value, see
#' \url{http://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains}
#'
#'
#' @param markers data.frame with first column longitude, second
#' column latitude, for which google markers should be embedded in
#' the map image, or character string to be passed directly to api
#' @param path data.frame (or list of data.frames) with first column
#' longitude, second column latitude, for which a single path
#' should be embedded in the map image, or character string to be
#' passed directly to api
#' @param visible a location as a longitude/latitude numeric vector
#' (or data frame with first column longitude, second latitude) or
#' vector of character string addresses which should be visible in
#' map extent
#' @param style character string to be supplied directly to the api
#' for the style argument or a named vector (see examples). this
#' is a powerful complex specification, see
#' \url{https://developers.google.com/maps/documentation/staticmaps/}
#'
#'
#' @return a ggmap object (a classed raster object with a bounding
#' box attribute)
#' @param ... ...
#' @author David Kahle \email{david.kahle@@gmail.com}
#' @seealso
#' \url{https://developers.google.com/maps/documentation/staticmaps/},
#' \code{\link{ggmap}}
#' @export
#' @examples
#'
#' \dontrun{ # to diminish run check time
#'
#'
#' get_googlemap(urlonly = TRUE)
#' ggmap(get_googlemap())
#'
#'
#' # markers and paths are easy to access
#' d <- function(x=-95.36, y=29.76, n,r,a){
#' round(data.frame(
#' lon = jitter(rep(x,n), amount = a),
#' lat = jitter(rep(y,n), amount = a)
#' ), digits = r)
#' }
#' df <- d(n=50,r=3,a=.3)
#' map <- get_googlemap(markers = df, path = df,, scale = 2)
#' ggmap(map)
#' ggmap(map, extent = "device") +
#' geom_point(aes(x = lon, y = lat), data = df, size = 3, colour = "black") +
#' geom_path(aes(x = lon, y = lat), data = df)
#'
#' gc <- geocode("waco, texas", source = "google")
#' center <- as.numeric(gc)
#' ggmap(get_googlemap(center = center, color = "bw", scale = 2), extent = "device")
#'
#' # the scale argument can be seen in the following
#' # (make your graphics device as large as possible)
#' ggmap(get_googlemap(center, scale = 1), extent = "panel") # pixelated
#' ggmap(get_googlemap(center, scale = 2), extent = "panel") # fine
#'
#' # archiving; note that you must meet google's terms for this condition
#' map <- get_googlemap(archiving = TRUE)
#' map <- get_googlemap()
#' ggmap(map)
#'
#'
#' # style
#' map <- get_googlemap(style = c(feature = "all", element = "labels", visibility = "off"))
#' ggmap(map)
#'
#'
#'
#'
#' }
#'
<- (
center = (lon = -95.3632715, lat = 29.7632836), zoom = 10, size = (640,640),
= 2, = ("png8", "gif", "jpg", "jpg-baseline","png32"),
maptype = ("terrain", "satellite", "roadmap", "hybrid"),
= "en-EN", sensor = ,
messaging = , urlonly = , filename = "ggmapTemp", color = ("color","bw"),
= , where = (), archiving = , key = "",
region, markers, path, visible, style,
){
# enumerate argument checking (added in lieu of checkargs function)
<- ((expand.dots = )-1])
argsgiven <- ()
("center" %in% argsgiven){
(!(
((center) && (center) == 2) ||
((center) && (center) == 1)
)){
("center of map misspecified, see ?get_googlemap.", call. = F)
}
(((center))){
lon <- center[1]; lat <- center[2]
(lon < -180 || lon > 180){
("longitude of center must be between -180 and 180 degrees.",
" note ggmap uses lon/lat, not lat/lon.", call. = F)
}
(lat < -90 || lat > 90){
("latitude of center must be between -90 and 90 degrees.",
" note ggmap uses lon/lat, not lat/lon.", call. = F)
}
}
}
("zoom" %in% argsgiven){
(!((zoom) && zoom == (zoom) && zoom > 0)){
("zoom must be a whole number between 1 and 21", call. = F)
}
}
("size" %in% argsgiven){
(((size)) && (size == (size)) && (size > 0))
}
("scale" %in% argsgiven) ( %in% (1,2,4))
# format arg checked by match.arg
# maptype arg checked by match.arg
("markers" %in% argsgiven){
markers_stop <-
((markers) && ((markers,1:2],2,))) markers_stop <-
(
(markers) == "list" &&
((markers, (elem){
(elem) && ((elem,1:2],2,))
}))
) markers_stop <-
((markers) && (markers) == 1) markers_stop <-
(markers_stop) ("improper marker specification, see ?get_googlemap.", call. = F)
}
("path" %in% argsgiven){
path_stop <-
((path) && ((path,1:2],2,))) path_stop <-
(
(path) == "list" &&
((path, (elem){
(elem) && ((elem,1:2],2,))
}))
) path_stop <-
((path) && (path) == 1) path_stop <-
(path_stop) ("improper path specification, see ?get_googlemap.", call. = F)
}
("visible" %in% argsgiven){
("visible argument untested.")
visible_stop <-
((visible) && ((visible,1:2],2,))) visible_stop <-
((visible)) visible_stop <-
(visible_stop) ("improper visible specification, see ?get_googlemap.", call. = F)
}
("style" %in% argsgiven){
style_stop <-
((style)) style <- (style)
((style)){
((style) > 1){
style <- (
((style), style, sep = ":"),
collapse = "|"
)
}
style_stop <-
}
(style_stop) ("improper style specification, see ?get_googlemap.", call. = F)
}
("sensor" %in% argsgiven) ((sensor))
("messaging" %in% argsgiven) ((messaging))
("urlonly" %in% argsgiven) ((urlonly))
("filename" %in% argsgiven){
filename_stop <-
((filename) && (filename) == 1) filename_stop <-
(filename_stop) ("improper filename specification, see ?get_googlemap.", call. = F)
}
("checkargs" %in% argsgiven){
(msg = "checkargs argument deprecated, args are always checked after v2.1.")
}
# argument checking (no checks for language, region, markers, path, visible, style)
#args <- as.list(match.call(expand.dots = TRUE)[-1])
#if(checkargs) get_googlemap_checkargs(args)
<- ()
( != "png8") ("currently only the png format is supported.", call. = F)
maptype <- (maptype)
color <- (color)
(!(markers) && (markers) == "list") markers <- list_to_dataframe(markers)
(!(path) && (path)) path <- (path)
# url segments
base_url <- "http://maps.googleapis.com/maps/api/staticmap?"
center_url <- (((center))){ # lon/lat specification
center <- (center, digits = 6)
lon <- center[1]; lat <- center[2]
("center=", (lat,lon,sep = ","))
} { # address specification
centerPlus <- (" ", "+", center)
("center=", centerPlus)
}
zoom_url <- ("zoom=", zoom)
size_url <- ("size=", (size, collapse="x"))
scale_url <- ("scale=", )
format_url <- (!() && != "png8"){ ("format=", ) } { "" }
maptype_url <- ("maptype=", maptype, sep = "")
language_url <- (!()){ ("language=", ) } { "" }
region_url <- (!(region)){ ("region=", region) } { "" }
markers_url <-
(!(markers)){
((markers)){
("markers=",
(
(markers, 1, (v) (((v,6)), collapse = ",")),
collapse = "|"),
sep = ""
)
} {
("markers=", markers, sep = "")
}
} { "" }
path_url <-
(!(path)){
((path)){
ps <- (path, (one_path){
("path=",
(
(one_path, 1, (v) (((v,6)), collapse = ",")),
collapse = "|"),
sep = ""
)
})
(ps, collapse = "&")
} {
("path=", path, sep = "")
}
} { "" }
visible_url <-
(!(visible)){
((visible)){
("visible=",
(
(visible, 1, (v) (((v,6)), collapse = ",")),
collapse = "|"),
sep = ""
)
} {
("visible=", (visible, collapse = "|"), sep = "")
}
} { "" }
style_url <- (!(style)){ ("style=", style, sep="") } { "" }
sensor_url <- ("sensor=", ((sensor)), sep="")
key_url <- (!(key)){("key=", key, sep="") } { "" }
# format url proper
post_url <- (center_url, zoom_url, size_url, scale_url,
format_url, maptype_url, language_url, region_url, markers_url,
path_url, visible_url, style_url, sensor_url, key_url, sep = "&")
<- (base_url, post_url, sep = "")
<- ("[&]+","&",) # removes missing arguments
((, (), ()) == "&"){ # if ends with &
<- (, 1, ()-1)
}
<- ()
(urlonly) ()
(() > 2048) ("max url length is 2048 characters.", call. = )
# check to see if url is on file
map <- file_drawer_get()
if (!(map) && !) (map)
# finalize filename
tmp <- ()
(, destfile = tmp, quiet = !messaging, = "wb")
(("Map from URL : ", ))
map <- readPNG(tmp)
map <- (map, (2, 1, 3))
# format file
(color == "color"){
map <- (map, 2, )
} (color == "bw"){
mapd <- (map)
map <- (.30 * map,,1] + .59 * map,,2] + .11 * map,,3])
(map) <- mapd[1:2]
}
map <- (map, = *size[2], = *size[1])
(map) <- ("ggmap","raster")
# plot(map)
# map spatial info
((center)) center <- ((center, = "google"))
ll <- XY2LatLon(
(lat = center[2], lon = center[1], zoom = zoom),
-size[1]/2 + 0.5,
-size[2]/2 - 0.5
)
ur <- XY2LatLon(
(lat = center[2], lon = center[1], zoom = zoom),
size[1]/2 + 0.5,
size[2]/2 - 0.5
)
(map, "bb") <- (
ll.lat = ll[1], ll.lon = ll[2],
ur.lat = ur[1], ur.lon = ur[2]
)
# additional map meta-data
(map, "source") <- "google"
(map, "maptype") <- maptype
(map, "zoom") <- zoom
# transpose
out <- map # t(map)
# archive map for future use
fileNameCenter <- (center)
fileNameCenter <- (("\\.", "_", fileNameCenter),collapse = "-")
if (archiving) file_drawer_set(, out)
# kick out
out
}
get_googlemap_checkargs <- (){
eargs <- (, )
argsgiven <- ()
(eargs,{
# center arg
("center" %in% argsgiven){
(!(
((center) && (center) == 2) ||
((center) && (center) == 1)
)){
("center of map misspecified, see ?get_googlemap.", call. = F)
}
(((center))){
lon <- center[1]; lat <- center[2]
(lon < -180 || lon > 180){
("longitude of center must be between -180 and 180 degrees.",
" note ggmap uses lon/lat, not lat/lon.", call. = F)
}
(lat < -90 || lat > 90){
("latitude of center must be between -90 and 90 degrees.",
" note ggmap uses lon/lat, not lat/lon.", call. = F)
}
}
}
# zoom arg
("zoom" %in% argsgiven){
(!((zoom) && zoom == (zoom) && zoom > 0)){
("zoom must be a whole number between 1 and 21", call. = F)
}
}
# size arg
("size" %in% argsgiven){
(((size)) && (size == (size)) && (size > 0))
}
# scale arg
("scale" %in% argsgiven) ( %in% (1,2,4))
# format arg checked by match.arg
# maptype arg checked by match.arg
# markers arg (optional)
("markers" %in% argsgiven){
markers_stop <-
((markers) && ((markers,1:2],2,))) markers_stop <-
(
(markers) == "list" &&
((markers, (elem){
(elem) && ((elem,1:2],2,))
}))
) markers_stop <-
((markers) && (markers) == 1) markers_stop <-
(markers_stop) ("improper marker specification, see ?get_googlemap.", call. = F)
}
# path arg (optional)
("path" %in% argsgiven){
path_stop <-
((path) && ((path,1:2],2,))) path_stop <-
(
(path) == "list" &&
((path, (elem){
(elem) && ((elem,1:2],2,))
}))
) path_stop <-
((path) && (path) == 1) path_stop <-
(path_stop) ("improper path specification, see ?get_googlemap.", call. = F)
}
# visible arg (optional)
("visible" %in% argsgiven){
("visible argument untested.")
visible_stop <-
((visible) && ((visible,1:2],2,))) visible_stop <-
((visible)) visible_stop <-
(visible_stop) ("improper visible specification, see ?get_googlemap.", call. = F)
}
# style arg (optional)
("style" %in% argsgiven){
("style argument untested.")
style_stop <-
((style) && (style) == 1) style_stop <-
(style_stop) ("improper style specification, see ?get_googlemap.", call. = F)
}
# sensor arg
("sensor" %in% argsgiven){
((sensor))
}
# messaging arg
("messaging" %in% argsgiven){
((messaging))
}
# urlonly arg
("urlonly" %in% argsgiven){
((urlonly))
}
# filename arg
("filename" %in% argsgiven){
filename_stop <-
((filename) && (filename) == 1) filename_stop <-
(filename_stop) ("improper filename specification, see ?get_googlemap.", call. = F)
}
# color arg checked by match.arg
}) # end with
}
