% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/met.R
\name{download.met}
\alias{download.met}
\title{Download and Cache a met File}
\usage{
download.met(
  id,
  year,
  month,
  deltat,
  type = "xml",
  destdir = ".",
  destfile,
  force = FALSE,
  quiet = FALSE,
  debug = getOption("oceDebug")
)
}
\arguments{
\item{id}{A number giving the "Station ID" of the station of interest. If not
provided, \code{id} defaults to 6358, for Halifax International Airport. See
\dQuote{Details}.}

\item{year}{A number giving the year of interest. Ignored unless \code{deltat}
is \code{"hour"}. If \code{year} is not given, it defaults to the present year.}

\item{month}{A number giving the month of interest. Ignored unless \code{deltat}
is \code{"hour"}. If \code{month} is not given, it defaults to the present
month.}

\item{deltat}{Optional character string indicating the time step of the
desired dataset. This may be \code{"hour"} or \code{"month"}.
If \code{deltat} is not given, it defaults to \code{"hour"}.}

\item{type}{String indicating which type of file to download, either
\code{"xml"} (the default) for an XML file or \code{"csv"} for a CSV file.}

\item{destdir}{Optional string indicating the directory in which to store
downloaded files. If not supplied, \code{"."} is used, i.e. the data file
is stored in the present working directory.}

\item{destfile}{Optional string indicating the name of the file.
If not supplied, the file name is constructed from the other
parameters of the function call, so subsequent calls with the same
parameters will yield the same result, thus providing the key
to the caching scheme.}

\item{force}{Logical value indicating whether to force a download, even
if the file already exists locally.}

\item{quiet}{Logical value passed to \code{\link[=download.file]{download.file()}}; a \code{TRUE} value
silences output.}

\item{debug}{an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many \code{oce} functions. Generally, setting \code{debug=0}
turns off the printing, while higher values suggest that more information
be printed. If one function calls another, it usually reduces the value of
\code{debug} first, so that a user can often obtain deeper debugging
by specifying higher \code{debug} values.}
}
\value{
String indicating the full pathname to the downloaded file.
}
\description{
\code{\link[=download.met]{download.met()}} attempts to download data from Environment Canada's
historical-data website, and to cache the files locally. Lacking a published
API, this function must rely on reverse-engineering of queries handled by
that web server.  For that reason, it is brittle.
}
\details{
If this function fails, users might try using Gavin Simpson's \code{canadaHCD}
package (reference 2). This package maintains a copy of the Environment
Canada listing of stations, and its \code{find_station()} function provides an easy
way to determine Station IDs.  After that, its \code{hcd_hourly} function (and
related functions) make it easy to read data. These data can then be
converted to the \code{met} class with \code{\link[=as.met]{as.met()}}, although doing so leaves many
important metadata blank.
}
\section{Sample of Usage}{

\preformatted{
library(oce)
# Download data for Halifax International Airport, in September
# of 2003. This dataset is used for data(met) provided with oce.
# Note that requests for data after 2012 month 10 yield all
# missing values, for reasons unknown to the author.
metFile <- download.met(8202250, 2003, 9, destdir=".")
met <- read.met(metFile)
}
}

\references{
\enumerate{
\item Environment Canada website for Historical Climate Data
\verb{https://climate.weather.gc.ca/index_e.html}
\item Gavin Simpson's \code{canadaHCD} package on GitHub
\verb{https://github.com/gavinsimpson/canadaHCD}
}
}
\seealso{
The work is done with \code{\link[utils:download.file]{utils::download.file()}}.

Other functions that download files: 
\code{\link{download.amsr}()},
\code{\link{download.coastline}()},
\code{\link{download.topo}()}

Other things related to met data: 
\code{\link{[[,met-method}},
\code{\link{[[<-,met-method}},
\code{\link{as.met}()},
\code{\link{met}},
\code{\link{met-class}},
\code{\link{plot,met-method}},
\code{\link{read.met}()},
\code{\link{subset,met-method}},
\code{\link{summary,met-method}}
}
\author{
Dan Kelley and Emily O'Grady
}
\concept{functions that download files}
\concept{things related to met data}
