API reference · v1

Marine data, one HTTP call away.

Aronnax aggregates and normalizes public + licensed marine datasets — bathymetry first — and exposes them through a small, stable JSON API. This page documents every endpoint of v1.

Base URL & conventions

All endpoints live under:

https://aronnax.ai

All responses are application/json; charset=utf-8.
Coordinates are decimal degrees in WGS 84. Longitude in [-180, 180], latitude in [-90, 90].
Elevations are metres, negative below sea level — see Datums & sign convention.
Timestamps are Unix seconds (integer) unless suffixed _iso.

Authentication

Every /v1/* route requires a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

/health is public — use it for liveness checks without burning a token round-trip.

Tokens are issued out-of-band. Treat the token as a secret; rotate by replacing the server-side value.

Errors

Errors return a JSON body of the form { "error": "<message>" } with one of:

Status	When
`400`	A required query parameter is missing or out of range (bad coordinate, bad bbox, samples out of bounds, etc.).
`401`	Missing or incorrect bearer token.
`404`	Either the path is unknown, or — for depth queries — no dataset in the catalog covers the requested point.
`503`	The server is missing required configuration (e.g. `API_TOKEN` not provisioned). Transient; retry after operator action.

`GET /health`

GET/health

Liveness probe. Public, unauthenticated, no database access. Returns the service identity and a server-side timestamp.

Response 200

{
  "status": "ok",
  "service": "aronnax",
  "api": "v1",
  "timestamp": "2026-05-31T21:02:45.106Z"
}

Example

curl https://aronnax.ai/health

`GET /v1/catalog`

GET/v1/catalog

Lists every dataset the API can serve: source, coverage bbox, resolution, vertical datum, vintage, and licensing posture. Use this to decide whether a region is covered before issuing a depth query, or to discover what's been ingested.

Response 200

{
  "datasets": [
    {
      "id": "gebco_2024",
      "source": "GEBCO",
      "kind": "bathymetry",
      "name": "GEBCO 2024 Grid",
      "resolution_m": 463,
      "vertical_datum": "MSL",
      "vintage": "2024",
      "license": "CC-BY-4.0",
      "redistributable": true,
      "commercial_use": true,
      "attribution": "GEBCO Compilation Group (2024)",
      "bbox": [-180.0, -90.0, 180.0, 90.0],
      "ingested_at": 1748726400
    }
  ]
}

Fields

Field	Meaning
`id`	Stable identifier used by depth-query responses in `dataset_id`.
`source`	Upstream provider name (e.g. `GEBCO`, `SHOM`).
`kind`	Data product category. Today: `bathymetry`.
`resolution_m`	Nominal native cell size in metres at the equator.
`vertical_datum`	What "zero" means for elevations from this dataset (e.g. `MSL`, `LAT`). See Datums.
`vintage`	Free-form publication year/edition string.
`redistributable`	`true` if downstream callers may republish raw values.
`commercial_use`	`true` if commercial use is permitted under the upstream licence.
`attribution`	Exact attribution string to display when republishing.
`bbox`	`[minLon, minLat, maxLon, maxLat]` covered by the dataset.
`ingested_at`	Unix seconds; when Aronnax last ingested this dataset.

Example

curl -H "Authorization: Bearer $TOKEN" \
  https://aronnax.ai/v1/catalog

`GET /v1/depth`

GET/v1/depth?lat=&lon=

Elevation at a single point, sampled bilinearly from the best-available dataset covering that location. The response carries provenance (which dataset answered, its resolution, vertical datum, vintage) so downstream tooling can present or audit the value.

Query parameters

Name	Required	Range	Notes
`lat`	yes	`[-90, 90]`	Decimal degrees, WGS 84.
`lon`	yes	`[-180, 180]`	Decimal degrees, WGS 84.

Response 200

{
  "lat": 43.5,
  "lon": 7.1,
  "elevation_m": -1842.4,
  "datum": "MSL",
  "source": "GEBCO",
  "dataset_id": "gebco_2024",
  "resolution_m": 463,
  "vintage": "2024",
  "attribution": "GEBCO Compilation Group (2024)"
}

Errors

400 — lat or lon missing / out of range.
404 — no dataset in the catalog covers the requested point.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://aronnax.ai/v1/depth?lat=43.5&lon=7.1"

`GET /v1/depth/profile`

GET/v1/depth/profile?path=…&samples=N

Elevation sampled along a polyline. Useful for cable routes, draft / under-keel planning, and cross-sections. With samples greater than the number of supplied vertices, the path is densified evenly by planar (lon/lat) distance. Each sample is resolved against the best dataset for that point, so one profile can span sources.

Query parameters

Name	Required	Format	Notes
`path`	yes	`lon,lat;lon,lat;…`	≥ 2 vertices, each within global lon/lat bounds.
`samples`	no	integer, `[2, 512]`	Defaults to the vertex count. If higher, the path is densified by even planar spacing.

Response 200

{
  "datum": "MSL",
  "datasets_used": ["gebco_2024", "shom_medit_2023"],
  "points": [
    { "lat": 43.50, "lon": 7.10, "elevation_m": -1842.4, "dataset_id": "gebco_2024",     "source": "GEBCO" },
    { "lat": 43.52, "lon": 7.15, "elevation_m": -1881.7, "dataset_id": "gebco_2024",     "source": "GEBCO" },
    { "lat": 43.54, "lon": 7.20, "elevation_m": null,    "dataset_id": null,             "source": null }
  ]
}

A point's elevation_m, dataset_id, and source are all null when no dataset covers that location (or the underlying value is nodata).

Errors

400 — path missing, malformed, or has fewer than two valid vertices.
400 — samples outside [2, 512] or not an integer.

Example — cable route, 64 samples

curl -H "Authorization: Bearer $TOKEN" \
  "https://aronnax.ai/v1/depth/profile?path=7.10,43.50;7.40,43.65;7.80,43.90&samples=64"

`GET /v1/depth/area`

GET/v1/depth/area?bbox=…&cols=&rows=

Regular grid of elevations sampled at cell centres across a bbox. Useful for thumbnail rendering, coarse exports, and any case where you want a small raster window in one round trip. Each request is capped at 4 096 cells total (e.g. 64 × 64). For larger windows, split the bbox client-side and call in parallel.

Query parameters

Name	Required	Format	Notes
`bbox`	yes	`minLon,minLat,maxLon,maxLat`	Must be a valid, non-degenerate window inside global bounds.
`cols`	yes	integer, `[1, 256]`	Columns in the output grid.
`rows`	yes	integer, `[1, 256]`	Rows. `cols * rows` must be ≤ 4 096.

Response 200

{
  "bbox": [7.0, 43.5, 7.5, 44.0],
  "cols": 4,
  "rows": 3,
  "datum": "MSL",
  "datasets_used": ["gebco_2024"],
  "values": [
    [-1842.4, -1881.7, -1903.1, -1925.6],   // row 0 — north edge
    [-1798.2, -1820.5, -1844.0, -1868.4],
    [-1750.1, -1772.6, -1795.3, -1819.7]    // row N-1 — south edge
  ]
}

values is row-major and north-up: values[0] is the row closest to maxLat. Each cell is sampled at its centre, not its corner. A cell is null when no dataset covers it (or the underlying value is nodata).

Mixed sources. A single area request can return cells from multiple datasets — Aronnax picks the best-resolution covered dataset per cell. datasets_used lists every dataset that contributed at least one cell, so you can compose attribution.

Errors

400 — bbox missing, malformed, degenerate (minLon >= maxLon, etc.), or outside global bounds.
400 — cols / rows outside [1, 256], or cols*rows exceeds the 4 096-cell cap.

Example — 64×64 grid over a 0.5° × 0.5° window

curl -H "Authorization: Bearer $TOKEN" \
  "https://aronnax.ai/v1/depth/area?bbox=7.0,43.5,7.5,44.0&cols=64&rows=64"

Datums & sign convention

Elevations are returned in metres. Negative values are below the vertical datum. For bathymetry that's the seafloor; for topography it'd be a continental depression.

The datum field on each response identifies what "zero" means for the values in that response. Aronnax does not perform inter-datum corrections — if you mix sources with different datums (e.g. MSL vs LAT), expect small but real offsets in coastal zones. The datasets_used field on multi-sample responses helps audit this.