# Andy Eggers, April 15, 2008
# R API for map function of google charts 
# see http://code.google.com/apis/chart/#maps

##### quick docs:
## Arguments:
# x   --  a vector of values to plotted, one for each state/country that should have a non-default color
# codes -- a vector of string state/country codes, based on http://code.google.com/apis/chart/#state_codes, http://code.google.com/apis/chart/#iso_codes
# location -- one of africa, asia, europe, middle_east, south_america, usa, world
# color_range -- optional vector indicating the hex colors at the extremes of the color range. see http://code.google.com/apis/chart/#maps for details on passing more than two values. By default we choose light and dark green
# default color -- optional hex color indicating what color to make the non-specified areas (ie the states/countries in the map that are not specified in the x and codes vectors
# width/height -- optional, the size of the image, in pixels. If you pass just a width the 2:1 aspect ratio is maintained
# file -- an optional character string indicating the location in which to save the PNG file.
## Values:
# returns a url at which you can retrieve the PNG from Google's web service

source("http://people.fas.harvard.edu/~aeggers/google_chart_utils.R")

googlemap = function(x, codes, location, color_range = c("edf0d4","13390a"), default_color = "ffffff", width = 440, height = NULL, file = NULL){
  if(!(location %in% c("africa", "asia", "europe", "middle_east", "south_america", "usa", "world"))){stop("Location must be one of: africa, asia, europe, middle_east, south_america, usa, world)")}
  if(length(x) != length(codes)){stop(paste("You provided ", length(x), " datapoints and ", length(codes), " geocodes.", sep =""))}
  url_preamble = "http://chart.apis.google.com/chart?cht=t"
  location = paste("chtm=", location, sep ="")
  chart_data = paste("chd=s:", join_string(simple_encode(x)), sep = "")
  # geographical codes: http://code.google.com/apis/chart/#state_codes, http://code.google.com/apis/chart/#iso_codes
  # codes that don't exist will be ignored
  geo_codes = paste("chld=", join_string(codes), sep = "")
  color_codes = paste("chco=", join_string(c(default_color, color_range), ","), sep = "")
  if(width>440){print("I think Google won't make a plot wider than 440px. Setting to 440."); width = 440}
  if(is.null(height)){height = ceiling(width/2)} # this is the aspect ratio used in the examples.
  chart_size = paste("chs=", width, "x", height, sep = "")
  background = "chf=bg,s,EAF7FE" # doign the pale blue ocean by default, could change this
  the_url = paste(url_preamble, location, chart_data, geo_codes, color_codes, chart_size, background, sep = "&")
  if (!is.null(file)){
    download.file(url = the_url, destfile = file, mode = "wb")
    }
  the_url 
  }
# some simple testing
stopifnot(googlemap(x = c(1,10,100), codes = c("NY", "PA", "NV"), location = "usa") == "http://chart.apis.google.com/chart?cht=t&chtm=usa&chd=s:AF8&chld=NYPANV&chco=ffffff,edf0d4,13390a&chs=440x220&chf=bg,s,EAF7FE")
stopifnot(googlemap(x = c(1,10,100), codes = c("TZ", "MG", "SA"), location = "africa", width = 400, default_color = "ffff00") == "http://chart.apis.google.com/chart?cht=t&chtm=africa&chd=s:AF8&chld=TZMGSA&chco=ffff00,edf0d4,13390a&chs=400x200&chf=bg,s,EAF7FE")
stopifnot(googlemap(x = c(1,10,100), codes = c("TZ", "MG", "SA"), location = "africa", width = 400, height = 220, default_color = "ffff00") == "http://chart.apis.google.com/chart?cht=t&chtm=africa&chd=s:AF8&chld=TZMGSA&chco=ffff00,edf0d4,13390a&chs=400x220&chf=bg,s,EAF7FE")
stopifnot(googlemap(x = c(1), codes = c("TZ"), location = "africa", width = 400, height = 200, default_color = "ffff00") == "http://chart.apis.google.com/chart?cht=t&chtm=africa&chd=s:o&chld=TZ&chco=ffff00,edf0d4,13390a&chs=400x200&chf=bg,s,EAF7FE")