diff --git a/R/homr.R b/R/homr.R index 79fb9e27..c6084819 100644 --- a/R/homr.R +++ b/R/homr.R @@ -2,49 +2,57 @@ #' #' @export #' -#' @param qid One of COOP, FAA, GHCND, ICAO, NCDCSTNID, NWSLI, TRANS, WBAN, or WMO, or any +#' @param qid One of COOP, FAA, GHCND, ICAO, NCDCSTNID, NWSLI, TRANS, WBAN, or +#' WMO, or any #' of those plus \code{[a-z0-9]}, or just \code{[a-z0-9]}. (qid = qualified ID) -#' @param qidMod (character) One of: is, starts, ends, contains. Specifies how the ID portion of -#' the qid parameter should be applied within the search. If a qid is passed but the qidMod -#' parameter is not used, qidMod is assumed to be IS. +#' @param qidMod (character) One of: is, starts, ends, contains. Specifies +#' how the ID portion of the qid parameter should be applied within the search. +#' If a qid is passed but the qidMod parameter is not used, qidMod is +#' assumed to be IS. #' @param station (character) A station id. -#' @param state (character) A two-letter state abbreviation. Two-letter code for US states, -#' Canadian provinces, and other Island areas. -#' @param county (character) A two letter county code. US county names, best used with a state -#' identifier. -#' @param country (character) A two letter country code. See here for a list of valid country -#' names. -#' @param name (character) One of name=[0-9A-Z]+. Searches on any type of name we have for the -#' station. -#' @param nameMod (character) [is|starts|ends|contains]. Specifies how the name parameter should -#' be applied within the search. If a name is passed but the nameMod parameter is not used, -#' nameMod is assumed to be IS. -#' @param platform (character) (aka network) [ASOS|USCRN|USHCN|NEXRAD|AL USRCRN|USRCRN|COOP]. -#' Limit the search to stations of a certain platform/network type. -#' @param date (character) [YYYY-MM-DD|all] Limits values to only those that occurred on a -#' specific date. Alternatively, date=all will return all values for matched stations. If this -#' field is omitted, the search will return only the most recent values for each field. -#' @param begindate,enddate [YYYY-MM-DD]. Limits values to only those that occurred within a -#' date range. -#' @param headersOnly (logical) Returns only minimal information for each station found (NCDC -#' Station ID, Preferred Name, Station Begin Date, and Station End Date), but is much quicker than a -#' full query. If you are performing a search that returns a large number of stations and intend -#' to choose only one from that list to examine in detail, headersOnly may give you enough -#' information to find the NCDC Station ID for the station that you actually want. -#' @param phrData (logical) The HOMR web service now includes PHR (element-level) data when -#' available, in an elements section. Because of how this data is structured, it can substantially -#' increase the size of any result which includes it. If you don't need this data you can omit it -#' by including phrData=false. If the parameter is not set, it will default to phrData=true. +#' @param state (character) A two-letter state abbreviation. Two-letter code +#' for US states, Canadian provinces, and other Island areas. +#' @param county (character) A two letter county code. US county names, best +#' used with a state identifier. +#' @param country (character) A two letter country code. See here for a list +#' of valid country names. +#' @param name (character) One of name=[0-9A-Z]+. Searches on any type of +#' name we have for the station. +#' @param nameMod (character) [is|starts|ends|contains]. Specifies how the +#' name parameter should be applied within the search. If a name is passed but +#' the nameMod parameter is not used, nameMod is assumed to be IS. +#' @param platform (character) (aka network) [ASOS|USCRN|USHCN|NEXRAD|AL +#' USRCRN|USRCRN|COOP]. Limit the search to stations of a certain +#' platform/network type. +#' @param date (character) [YYYY-MM-DD|all] Limits values to only those that +#' occurred on a specific date. Alternatively, date=all will return all values +#' for matched stations. If this field is omitted, the search will return only +#' the most recent values for each field. +#' @param begindate,enddate [YYYY-MM-DD]. Limits values to only those that +#' occurred within a date range. +#' @param headersOnly (logical) Returns only minimal information for each +#' station found (NCDC Station ID, Preferred Name, Station Begin Date, and +#' Station End Date), but is much quicker than a full query. If you are +#' performing a search that returns a large number of stations and intend to +#' choose only one from that list to examine in detail, headersOnly may give +#' you enough information to find the NCDC Station ID for the station that +#' you actually want. +#' @param phrData (logical) The HOMR web service now includes PHR +#' (element-level) data when available, in an elements section. Because of +#' how this data is structured, it can substantially increase the size of any +#' result which includes it. If you don't need this data you can omit it +#' by including phrData=false. If the parameter is not set, it will default +#' to phrData=true. #' @param combine (logical) Combine station metadata or not. #' @param ... Curl options passed on to \code{\link[httr]{GET}} (optional) #' -#' @details Since the definitions for variables are always the same, we don't include the ability -#' to get description data in this function. Use \code{link[rnoaa]{homr_descriptions}} to get -#' descriptions information. +#' @details Since the definitions for variables are always the same, we don't +#' include the ability to get description data in this function. Use +#' \code{link[rnoaa]{homr_descriptions}} to get descriptions information. #' #' @return A list, with elements named by the station ids. #' -#' @references \url{http://www.ncdc.noaa.gov/homr/api} +#' @references \url{https://www.ncdc.noaa.gov/homr/api} #' #' @examples \dontrun{ #' homr(qid = 'COOP:046742') @@ -66,24 +74,33 @@ #' homr(state='DE', headersOnly=TRUE) #' homr(station=20002078) #' homr(station=20002078, date='all', phrData=FALSE) -#' +#' #' # Optionally pass in curl options #' homr(headersOnly=TRUE, state='NC', county='BUNCOMBE', config=verbose()) #' } -homr <- function(qid=NULL, qidMod=NULL, station=NULL, state=NULL, county=NULL, country=NULL, - name=NULL, nameMod=NULL, platform=NULL, date=NULL, begindate=NULL, enddate=NULL, headersOnly=FALSE, - phrData=NULL, combine=FALSE, ...) { +homr <- function(qid=NULL, qidMod=NULL, station=NULL, state=NULL, county=NULL, + country=NULL, name=NULL, nameMod=NULL, platform=NULL, date=NULL, + begindate=NULL, enddate=NULL, headersOnly=FALSE, phrData=NULL, + combine=FALSE, ...) { + + args <- noaa_compact( + list( + qid=qid, qidMod=qidMod, state=state, county=county, + country=country, name=name, nameMod=nameMod, platform=platform, + date=date, begindate=begindate, enddate=enddate, + headersOnly=tl(headersOnly), phrData=tl(phrData), definitions = 'false' + ) + ) - args <- noaa_compact(list(qid=qid, qidMod=qidMod, state=state, county=county, country=country, - name=name, nameMod=nameMod, platform=platform, date=date, begindate=begindate, - enddate=enddate, headersOnly=tl(headersOnly), phrData=tl(phrData), definitions = 'false')) if (length(args) == 0) args <- NULL - url <- if (is.null(station)) paste0(homr_base(), "search") else paste0(homr_base(), station) + url <- if (is.null(station)) paste0(homr_base(), "search") else + paste0(homr_base(), station) res <- GET(url, query = args, ...) out <- utcf8(res) json <- jsonlite::fromJSON(out, FALSE) - sts <- lapply(json$stationCollection$stations, parse_stations, headersOnly = headersOnly) + sts <- lapply(json$stationCollection$stations, parse_stations, + headersOnly = headersOnly) names(sts) <- sapply(sts, "[[", "id") if (!combine) { structure(sts, class = "homr", combined = FALSE) @@ -153,8 +170,6 @@ combine_stations <- function(w){ remarks=remarks, updates=updates, elements=elements, location=location) } -homr_base <- function() 'http://www.ncdc.noaa.gov/homr/services/station/' - tl <- function(x) if (is.null(x)) NULL else tolower(x) todf <- function(x) ifn_null(x, lapply(x, data.frame, stringsAsFactors = FALSE)) rbf <- function(x, name = FALSE){ @@ -163,10 +178,13 @@ rbf <- function(x, name = FALSE){ } else { x <- noaa_compact(x) nmz <- names(x) - tmp <- Map(function(a, b) data.frame(id = b, a, stringsAsFactors = FALSE), x, nmz) + tmp <- Map(function(a, b) data.frame(id = b, a, stringsAsFactors = FALSE), + x, nmz) ifn_null(tmp, dplyr::bind_rows(tmp)) } } ifn_null <- function(x, y) if (is.null(x)) x else y ifn_na <- function(x) if (is.null(x)) NA else x na2null <- function(x) if (all(is.na(x))) NULL else x + +homr_base <- function() 'https://www.ncdc.noaa.gov/homr/services/station/' diff --git a/cran-comments.md b/cran-comments.md index 2e69025b..65fb4819 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -17,7 +17,8 @@ ## Reverse dependencies -Checked on the 1 reverse dependency - no problems were found. +Checked on the 1 reverse dependency - no problems were found + ----- diff --git a/man/homr.Rd b/man/homr.Rd index 06156a72..4823667a 100644 --- a/man/homr.Rd +++ b/man/homr.Rd @@ -10,51 +10,59 @@ homr(qid = NULL, qidMod = NULL, station = NULL, state = NULL, headersOnly = FALSE, phrData = NULL, combine = FALSE, ...) } \arguments{ -\item{qid}{One of COOP, FAA, GHCND, ICAO, NCDCSTNID, NWSLI, TRANS, WBAN, or WMO, or any +\item{qid}{One of COOP, FAA, GHCND, ICAO, NCDCSTNID, NWSLI, TRANS, WBAN, or +WMO, or any of those plus \code{[a-z0-9]}, or just \code{[a-z0-9]}. (qid = qualified ID)} -\item{qidMod}{(character) One of: is, starts, ends, contains. Specifies how the ID portion of -the qid parameter should be applied within the search. If a qid is passed but the qidMod -parameter is not used, qidMod is assumed to be IS.} +\item{qidMod}{(character) One of: is, starts, ends, contains. Specifies +how the ID portion of the qid parameter should be applied within the search. +If a qid is passed but the qidMod parameter is not used, qidMod is +assumed to be IS.} \item{station}{(character) A station id.} -\item{state}{(character) A two-letter state abbreviation. Two-letter code for US states, -Canadian provinces, and other Island areas.} +\item{state}{(character) A two-letter state abbreviation. Two-letter code +for US states, Canadian provinces, and other Island areas.} -\item{county}{(character) A two letter county code. US county names, best used with a state -identifier.} +\item{county}{(character) A two letter county code. US county names, best +used with a state identifier.} -\item{country}{(character) A two letter country code. See here for a list of valid country -names.} +\item{country}{(character) A two letter country code. See here for a list +of valid country names.} -\item{name}{(character) One of name=[0-9A-Z]+. Searches on any type of name we have for the -station.} +\item{name}{(character) One of name=[0-9A-Z]+. Searches on any type of +name we have for the station.} -\item{nameMod}{(character) [is|starts|ends|contains]. Specifies how the name parameter should -be applied within the search. If a name is passed but the nameMod parameter is not used, -nameMod is assumed to be IS.} +\item{nameMod}{(character) [is|starts|ends|contains]. Specifies how the +name parameter should be applied within the search. If a name is passed but +the nameMod parameter is not used, nameMod is assumed to be IS.} -\item{platform}{(character) (aka network) [ASOS|USCRN|USHCN|NEXRAD|AL USRCRN|USRCRN|COOP]. -Limit the search to stations of a certain platform/network type.} +\item{platform}{(character) (aka network) [ASOS|USCRN|USHCN|NEXRAD|AL +USRCRN|USRCRN|COOP]. Limit the search to stations of a certain +platform/network type.} -\item{date}{(character) [YYYY-MM-DD|all] Limits values to only those that occurred on a -specific date. Alternatively, date=all will return all values for matched stations. If this -field is omitted, the search will return only the most recent values for each field.} +\item{date}{(character) [YYYY-MM-DD|all] Limits values to only those that +occurred on a specific date. Alternatively, date=all will return all values +for matched stations. If this field is omitted, the search will return only +the most recent values for each field.} -\item{begindate, enddate}{[YYYY-MM-DD]. Limits values to only those that occurred within a -date range.} +\item{begindate, enddate}{[YYYY-MM-DD]. Limits values to only those that +occurred within a date range.} -\item{headersOnly}{(logical) Returns only minimal information for each station found (NCDC -Station ID, Preferred Name, Station Begin Date, and Station End Date), but is much quicker than a -full query. If you are performing a search that returns a large number of stations and intend -to choose only one from that list to examine in detail, headersOnly may give you enough -information to find the NCDC Station ID for the station that you actually want.} +\item{headersOnly}{(logical) Returns only minimal information for each +station found (NCDC Station ID, Preferred Name, Station Begin Date, and +Station End Date), but is much quicker than a full query. If you are +performing a search that returns a large number of stations and intend to +choose only one from that list to examine in detail, headersOnly may give +you enough information to find the NCDC Station ID for the station that +you actually want.} -\item{phrData}{(logical) The HOMR web service now includes PHR (element-level) data when -available, in an elements section. Because of how this data is structured, it can substantially -increase the size of any result which includes it. If you don't need this data you can omit it -by including phrData=false. If the parameter is not set, it will default to phrData=true.} +\item{phrData}{(logical) The HOMR web service now includes PHR +(element-level) data when available, in an elements section. Because of +how this data is structured, it can substantially increase the size of any +result which includes it. If you don't need this data you can omit it +by including phrData=false. If the parameter is not set, it will default +to phrData=true.} \item{combine}{(logical) Combine station metadata or not.} @@ -67,9 +75,9 @@ A list, with elements named by the station ids. Historical Observing Metadata Repository (HOMR) station metadata } \details{ -Since the definitions for variables are always the same, we don't include the ability -to get description data in this function. Use \code{link[rnoaa]{homr_descriptions}} to get -descriptions information. +Since the definitions for variables are always the same, we don't +include the ability to get description data in this function. Use +\code{link[rnoaa]{homr_descriptions}} to get descriptions information. } \examples{ \dontrun{ @@ -98,6 +106,6 @@ homr(headersOnly=TRUE, state='NC', county='BUNCOMBE', config=verbose()) } } \references{ -\url{http://www.ncdc.noaa.gov/homr/api} +\url{https://www.ncdc.noaa.gov/homr/api} }