RAmap: Bring the Amap LBS api to R

#' Get JSON of matching points from Amap LBS API
#'
#' This function gets JSON of matching points from Amap Map Matching API. According to the official policy,
#' at most 20 points at a time.
#'
#' @param point_df a data frame store the raw GPS points.
#' @param field_name the required fields name in point_df, which in sequence are datetime, longitude, latitude, speed and direction.
#' @param carid an ID indicate the owner/generator of the points.
#' @param key Amap API access key. We provide a default one, but we strongly recommend you to use yours because the quota is limited.
#' @return JSON containing the matched road names and matched points.
#' @export
#' @examples
#' points <- "20150418194859,116.5439960,39.9127330,95.00,356.35:20150418194904,116.5439160,39.9139890,101.00,355.16:20150418194909,116.5438090,39.9152530,97.00,356.56:20150418194914,116.5437340,39.9165030,98.00,356.33:20150418194919,116.5436590,39.9176730,90.00,355.74:20150418194924,116.5435690,39.9188820,99.00,358.47:20150418194929,116.5435390,39.9200060,90.01,357.75:20150418194934,116.5435050,39.9208710,65.00,356.30:20150418194939,116.5434590,39.9215820,58.00,357.66:20150418194944,116.5434300,39.9222920,59.00,353.52:20150418194949,116.5433260,39.9232080,74.00,352.84:20150418194954,116.5432080,39.9241480,74.00,352.00:20150418194959,116.5431280,39.9251490,85.00,356.43:20150418195004,116.5430550,39.9263200,96.00,356.92:20150418195009,116.5429920,39.9274920,90.00,356.85:20150418195014,116.5429300,39.9286200,92.00,359.39:20150418195019,116.5429180,39.9297540,89.00,354.80:20150418195024,116.5428170,39.9308650,85.00,356.46:20150418195029,116.5427520,39.9319150,83.00,356.41:20150418195034,116.5426830,39.9330150,89.00,357.66:20150418195039,116.5426360,39.9341660,93.00,356.51:20150418195044,116.5425690,39.9352640,89.00,357.26:20150418195049,116.5425140,39.9364140,89.00,355.83:20150418195054,116.5424300,39.9375660,94.00,358.00:20150418195059,116.5422840,39.9387690,98.00,350.81:20150418195104,116.5420890,39.9399750,98.00,343.63:20150418195109,116.5417370,39.9411740,97.00,337.45:20150418195114,116.5412510,39.9423450,98.00,331.31:20150418195119,116.5406520,39.9434400,95.00,325.99:20150418195124,116.5399290,39.9445120,94.00,320.57:20150418195129,116.5390770,39.9455490,99.00,318.25:20150418195134,116.5381700,39.9465660,94.00,316.15:20150418195139,116.5372340,39.9475410,99.00,315.78:20150418195144,116.5362130,39.9485910,108.00,315.64:20150418195149,116.5351510,39.9496780,108.00,316.57:20150418195154,116.5341200,39.9507680,104.00,322.00:20150418195159,116.5332030,39.9518200,99.00,321.82:20150418195204,116.5323960,39.9528470,94.00,325.41:20150418195209,116.5316840,39.9538800,93.00,328.90:20150418195214,116.5310510,39.9549300,92.00,332.34:20150418195219,116.5304810,39.9560180,94.00,335.09:20150418195224,116.5299570,39.9571470,95.00,336.55:20150418195229,116.5294650,39.9582820,97.00,337.16"
#' point_df <- data.frame(V1=unlist(stringr::str_split(stringr::str_trim(points), ":"))) %>%
#'  tidyr::separate(V1, c("time", "lng", "lat", "speed", "direction"), ",")
#' match_json <- getMatchingJSON(point_df)
#' print(match_json)
getMatchingJSON <- function(point_df, field_name = c("time", "lng", "lat", "speed", "direction"), carid="RAmap", key="bab9a1f7c090c37ccda0c566a0f8cd55") {
  url <- "http://restapi.amap.com/v3/autograsp"
  time_str <- stringr::str_c(as.numeric(lubridate::ymd_hms(point_df[, field_name[1]], tz="Asia/Shanghai")), collapse=",")
  dir_str <- stringr::str_c(point_df[, field_name[5]], collapse=",")
  speed_str <- stringr::str_c(point_df[, field_name[4]], collapse=",")
  loc_str <- stringr::str_c(as.matrix(point_df[, field_name[2:3]]  %>% tidyr::unite_("loc", field_name[2:3], sep=",")), collapse=";")
  params <- list(time=time_str, direction=dir_str, speed=speed_str, locations = loc_str, output="json",
                 key=key, carid=carid)
  r <- httr::GET(url, query=params)
  if(r$status_code == 200) {
    return(httr::content(r, 'text', encoding = 'utf-8'))
  }
  else {
    return(NULL)
  }
}