@spec get_elevation(latitude(), longitude(), keyword()) ::
  {:ok, elevation() | nil} | {:error, SRTM.Error.t()}

Queries locations on the earth for elevation data.

If the corresponding file can't be found in the cache, it will be retrieved online and stored in the caches. A cache that fails to store it fails the lookup, so that a cache which can no longer be written to — an unwritable :disk_cache_path, say — surfaces instead of quietly turning every lookup into a download.

Returns the elevation in meters, or nil where the dataset holds no measurement for the coordinate: SRTM has voids where the radar returned no usable signal, and the raw tiles carry no samples at all over open water.

The elevation is the sample the coordinate falls into rather than an interpolation between the surrounding samples, so it describes a grid cell of roughly 30 m (1 arc-second) or 90 m (3 arc-seconds) across, depending on the dataset.

Examples

iex> SRTM.get_elevation(36.455556, -116.866667)
{:ok, -51}

iex> SRTM.get_elevation(2.984654, 59.686144)
{:ok, nil}

Configuration

Unknown options raise an ArgumentError.

• :disk_cache_enabled (boolean/0) - whether the disk cache is enabled. Defaults to true.

• :disk_cache_path (Path.t/0) - the path to the directory where the downloaded HGT files are stored. Defaults to ./srtm_cache.

• :in_memory_cache_enabled (boolean/0) - whether the in-memory cache is enabled. Defaults to true.

  Note

  See SRTM.Cache.PersistentTerm for the implications on system performance.

• :in_memory_cache_module (module/0) - a module that implements the SRTM.Cache behaviour. Defaults to SRTM.Cache.PersistentTerm.

• :sources (list of module/0 or {module, keyword}) - a list of modules that implement the SRTM.Source behaviour, tried in order. Defaults to [SRTM.Source.AWS, SRTM.Source.ESA]. See the source modules for the options they accept.

With both caches disabled, every lookup downloads the HGT file.