Topographic data are downloaded from a data server that holds the ETOPO1 dataset (Amante, C. and B.W. Eakins, 2009), and saved as a netCDF file whose name specifies the data request, if a file of that name is not already present on the local file system. The return value is the name of the data file, and it's typical use is as the filename for a call to read.topo(). Given the rules on file naming, subsequent calls to download.topo() with identical parameters will simply return the name of the cached file, assuming the user has not deleted it in the meantime.

  resolution = 4,
  destdir = ".",
  server = "",
  debug = getOption("oceDebug")


west, east

Longitudes of the western and eastern sides of the box.

south, north

Latitudes of the southern and northern sides of the box.


numeric value of grid spacing, in geographical minutes. The default value of 4 minutes corresponds to 4 nautical miles, or 7.4km.


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


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.


Deprecated, and ignored, as of June 2020.


character value specifying the base from which a download URL will be constructed. It is unlikely that any value other than the default will work, unless it is a similarly-constructed mirrored site.


an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many oce functions. Generally, setting 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 debug first, so that a user can often obtain deeper debugging by specifying higher debug values.


String indicating the full pathname to the downloaded file.


For years, the server used by download.topo() was capable of returning netCDF files, but this was found to fail in late May of 2020. Luckily, the marmap::getNOAA.bathy() function in the marmap package was updated to handle the changes in the server, and download.topo() was able to pattern its URL construction on that function. The server also now has an API, which might suggest it will be less subject to change in the future.


  • Amante, C. and B.W. Eakins, 2009. ETOPO1 1 Arc-Minute Global Relief Model: Procedures, Data Sources and Analysis. NOAA Technical Memorandum NESDIS NGDC-24. National Geophysical Data Center, NOAA. doi:10.7289/V5C8276M

See also

Other functions that download files: download.amsr(), download.coastline(), download.met()

Other things related to topo data: [[,topo-method, [[<-,topo-method, as.topo(), plot,topo-method, read.topo(), subset,topo-method, summary,topo-method, topo-class, topoInterpolate(), topoWorld


if (FALSE) { library(oce) topoFile <- download.topo(west=-66, east=-60, south=43, north=47, resolution=1, destdir="~/data/topo") topo <- read.topo(topoFile) imagep(topo, zlim=c(-400, 400), drawTriangles=TRUE) if (requireNamespace("ocedata", quietly=TRUE)) { data(coastlineWorldFine, package="ocedata") lines(coastlineWorldFine[["longitude"]], coastlineWorldFine[["latitude"]]) } }