#' Google geocoding
#'
#' Geocoding is the process of converting addresses (like "1600 Amphitheatre
#' Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021
#' and longitude -122.083739), which you can use to place markers on a map, or position the map.
#'
#' @param address \code{string}. The street address that you want to geocode, in the
#' format used by the national postal service of the country concerned
#' @param bounds list of two, each element is a vector of lat/lon coordinates
#' representing the south-west and north-east bounding box
#' @param language \code{string}. Specifies the language in which to return the results.
#' See the list of supported languages:
#' \url{https://developers.google.com/maps/faq#using-google-maps-apis}. If no
#' langauge is supplied, the service will attempt to use the language of the domain
#' from which the request was sent
#' @param region \code{string}. Specifies the region code, specified as a ccTLD
#' ("top-level domain"). See region basing for details
#' \url{https://developers.google.com/maps/documentation/directions/overview#RegionBiasing}
#' @param key \code{string}. A valid Google Developers Geocode API key
#' @param components \code{data.frame} of two columns, component and value. Restricts
#' the results to a specific area. One or more of "route","locality","administrative_area",
#' "postal_code","country"
#' @param simplify \code{logical} - TRUE indicates the returned JSON will be coerced into a list. FALSE indicates the returend JSON will be returned as a string
#' @param curl_proxy a curl proxy object
#' @return Either list or JSON string of the geocoded address
#'
#' @section API use and limits:
#'
#' The amount of queries you can make to Google's APIs is dependent on both the service
#' and the API you are using.
#'
#' Each API has specific quotas and limits. Check Google's API documentation for details.
#'
#' View your usage at the Google Cloud Console \url{https://console.cloud.google.com/}
#'
#' Each API can only accept and return one request at a time. If you write a loop
#' to make multiple API calls you should ensure you don't go over your quota / limits
#' during the loop.
#'
#'
#'
#' @examples
#' \dontrun{
#'
#' set_key("YOUR_GOOGLE_API_KEY")
#' df <- google_geocode(address = "MCG, Melbourne, Australia",
#' simplify = TRUE)
#'
#' df$results$geometry$location
#' lat lng
#' 1 -37.81659 144.9841
#'
#' ## using bounds
#' bounds <- list(c(34.172684,-118.604794),
#' c(34.236144,-118.500938))
#'
#' js <- google_geocode(address = "Winnetka",
#' bounds = bounds,
#' simplify = FALSE)
#'
#' ## using components
#' components <- data.frame(component = c("postal_code", "country"),
#' value = c("3000", "AU"))
#'
#' df <- google_geocode(address = "Flinders Street Station",
#' components = components,
#' simplify = FALSE)
#'
#' }
#' @export
google_geocode <- function(address,
bounds = NULL,
key = get_api_key("geocode"),
language = NULL,
region = NULL,
components = NULL,
simplify = TRUE,
curl_proxy = NULL
){
## parameter check - key
if(is.null(key))
stop("A Valid Google Developers API key is required")
logicalCheck(simplify)
address <- check_address(address)
address <- tolower(address)
bounds <- validateBounds(bounds)
language <- validateLanguage(language)
region <- validateRegion(region)
components <- validateComponents(components)
map_url <- "https://maps.googleapis.com/maps/api/geocode/json?"
map_url <- constructURL(map_url, c("address" = address,
"bounds" = bounds,
"language" = language,
"region" = region,
"components" = components,
"key" = key))
return(downloadData(map_url, simplify, curl_proxy))
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.