# `Astro.Ephemeris.Downloader`
[🔗](https://github.com/kipcole9/astro/blob/v2.1.0/lib/astro/ephemeris/downloader.ex#L1)

Downloads JPL DE-series SPK binary ephemeris files from NASA NAIF.

The default ephemeris file (`de440s.bsp`, ~32 MB) is not bundled with
the hex package. It is downloaded automatically at application start
the first time `Astro` is run, and cached on disk for subsequent runs.

### Cache location

By default the file is cached under the user cache directory as
resolved by `:filename.basedir(:user_cache, "astro")`. The location
can be overridden by setting the `:ephemeris` application environment
key:

    config :astro,
      ephemeris: "/path/to/de440s.bsp"

When the configured path already contains a valid ephemeris file no
download is performed.

### Source URL

The default download source is the NASA NAIF generic kernels archive:

    https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de440s.bsp

This can be overridden by setting the `:ephemeris_url` application
environment key (for example, when mirroring the file inside an
air-gapped environment).

# `download`

```elixir
@spec download(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Downloads the ephemeris file to `path`.

The destination directory is created if it does not already exist.
On HTTP error or network failure the partial file (if any) is removed.

### Arguments

* `path` is the destination file path.

### Returns

* `{:ok, path}` on success.

* `{:error, reason}` if the download failed. `reason` is a tuple
  describing the failure, e.g. `{:http_status, 404}` or an `:httpc`
  error term.

# `ensure_ephemeris`

```elixir
@spec ensure_ephemeris(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Ensures the ephemeris file is available on disk, downloading it if necessary.

### Arguments

* `path` is the destination file path.

### Returns

* `{:ok, path}` if the file already exists or was downloaded successfully.

* `{:error, reason}` if the file is missing and the download failed.

# `ephemeris_path`

```elixir
@spec ephemeris_path() :: String.t()
```

Returns the resolved ephemeris file path.

Resolution order:

* The `:ephemeris` application environment key, if set.

* `priv/de440s.bsp` if it exists (used during library development
  and when running from a checkout).

* The user cache directory as resolved by
  `:filename.basedir(:user_cache, "astro")`.

### Returns

* A binary path string.

---

*Consult [api-reference.md](api-reference.md) for complete listing*