dataset_suggest.r
#' Suggest datasets in GBIF.
#'
#' Search that returns up to 20 matching datasets. Results are ordered by relevance.
#'
#' @export
#' @template otherlimstart
#' @template occ
#' @template dataset
#'
#' @param subtype NOT YET IMPLEMENTED. Will allow filtering of datasets by their
#' dataset subtypes, DC or EML.
#' @param continent Not yet implemented, but will eventually allow filtering datasets
#' by their continent(s) as given in our Continent enum.
#' @param description Return descriptions only (TRUE) or all data (FALSE, default)
#'
#' @references \url{http://www.gbif.org/developer/registry#datasetSearch}
#'
#' @examples \dontrun{
#' # Suggest datasets of type "OCCURRENCE".
#' dataset_suggest(query="Amazon", type="OCCURRENCE")
#'
#' # Suggest datasets tagged with keyword "france".
#' dataset_suggest(keyword="france")
#'
#' # Suggest datasets owned by the organization with key
#' # "07f617d0-c688-11d8-bf62-b8a03c50a862" (UK NBN).
#' head(dataset_suggest(owningOrg="07f617d0-c688-11d8-bf62-b8a03c50a862"))
#'
#' # Fulltext search for all datasets having the word "amsterdam" somewhere in
#' # its metadata (title, description, etc).
#' head(dataset_suggest(query="amsterdam"))
#'
#' # Limited search
#' dataset_suggest(type="OCCURRENCE", limit=2)
#' dataset_suggest(type="OCCURRENCE", limit=2, start=10)
#'
#' # Return just descriptions
#' dataset_suggest(type="OCCURRENCE", description=TRUE)
#'
#' # Return metadata in a more human readable way (hard to manipulate though)
#' dataset_suggest(type="OCCURRENCE", pretty=TRUE)
#'
#' # Search by country code. Lookup isocodes first, and use US for United States
#' isocodes[agrep("UNITED", isocodes$gbif_name),]
#' head(dataset_suggest(country="US"))
#'
#' # Search by decade
#' head(dataset_suggest(decade=1980))
#'
#' # httr options
#' library('httr')
#' dataset_suggest(type="OCCURRENCE", limit=2, config=verbose())
#' }
dataset_suggest <- function(query = NULL, country = NULL, type = NULL, subtype = NULL,
keyword = NULL, owningOrg = NULL, publishingOrg = NULL, hostingOrg = NULL,
publishingCountry = NULL, decade = NULL, continent = NULL, limit=100, start=NULL,
pretty=FALSE, description=FALSE, ...)
{
url <- paste0(gbif_base(), '/dataset/suggest')
args <- rgbif_compact(list(q=query,type=type,keyword=keyword,owningOrg=owningOrg,
publishingOrg=publishingOrg,
hostingOrg=hostingOrg,publishingCountry=publishingCountry,
decade=decade,limit=limit,offset=start))
tt <- gbif_GET(url, args, FALSE, ...)
if(description){
out <- sapply(tt, "[[", "description")
names(out) <- sapply(tt, "[[", "title")
out <- rgbif_compact(out)
} else
{
if(length(tt)==1){
out <- parse_suggest(x=tt$results)
} else
{
out <- do.call(rbind_fill, lapply(tt, parse_suggest))
}
}
if(pretty){
if(length(tt)==1){
invisible(print_suggest(tt))
} else
{
invisible(lapply(tt, print_suggest)[[1]])
}
} else
{
return( out )
}
}
parse_suggest <- function(x){
tmp <- rgbif_compact(list(
key=x$key,
type=x$type,
title=x$title
))
data.frame(tmp, stringsAsFactors=FALSE)
}
print_suggest <- function(x){
cat(
paste("datasetKey:", x$key),
paste("type:", x$type),
paste("datasetTitle:", x$title),
paste("description:", x$description),
"\n", sep="\n")
}