Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thebuoy.app/llms.txt

Use this file to discover all available pages before exploring further.

​
What are satellite observations?

Satellite radar instruments — altimeters on most missions, a Ku-band scatterometer (SWIM) on CFOSAT — measure significant wave height along their orbital tracks, extending coverage to open ocean where no buoy reaches. Each satellite overpass is grouped into a pass — one orbital segment over the network, with its own time window, geographic bounds, and a count of the observations it produced. Passes are attributed to the mission that produced them (e.g. CFOSAT), so you can filter to a single satellite.
Satellite observations surface through the buoy-namespaced endpoints below.

​
Available missions

Each pass is linked to one mission. The current set:
MissionAgencyInstrument
CFOSATCNES / CNSASWIM
Jason-3NASA / CNES / EUMETSAT / NOAAPoseidon-3B
Sentinel-3AESA / CopernicusSRAL
Sentinel-3BESA / CopernicusSRAL
Sentinel-6AESA / EUMETSAT / NASA / NOAAPoseidon-4
SWOT nadirNASA / CNESNadir altimeter
Saral/AltiKaISRO / CNESAltiKa
CryoSat-2ESASIRAL
HaiYang-2BCNSA / NSOASRadar altimeter
HaiYang-2CCNSA / NSOASRadar altimeter
Fetch the live list from the discovery endpoint below.

​
Discover missions

GET /buoys/satellites lists every mission with its metadata and a count of recorded passes. Use a returned slug as the filter value for satellite passes. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys/satellites"

{
  "status": "success",
  "data": {
    "satellites": [
      {
        "slug": "cfosat",
        "name": "CFOSAT",
        "agency": "CNES / CNSA",
        "instrument": "SWIM",
        "description": "Joint French–Chinese mission measuring ocean surface wind and directional wave spectra with the SWIM scatterometer.",
        "image_url": null,
        "pass_count": 220
      }
    ],
    "count": 12
  },
  "meta": { "timestamp": "2026-05-27T09:00:00Z" }
}

​
Localized descriptions

Mission description is available in English and French. Select the language with ?locale= (or the Accept-Language header); it defaults to English. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys/satellites?locale=fr"

{
  "slug": "cfosat",
  "name": "CFOSAT",
  "description": "Mission franco-chinoise mesurant le vent de surface et les spectres directionnels des vagues à l'aide du diffusiomètre SWIM."
}

​
Filter passes by mission

GET /buoys/satellite_passes returns recent passes. Pass mission (a slug from the discovery endpoint) to get only that satellite’s passes. 
# Only CFOSAT passes
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys/satellite_passes?mission=cfosat"
An unknown slug returns 404 resource_not_found. Omit mission to get passes from all satellites.

​
Parameters

ParameterTypeDefaultDescription
missionstring—Filter to one mission, by slug (see /buoys/satellites)
active_onlybooleantrueOnly passes that have fresh, displayable buoy readings
sincestring (ISO 8601)—Only passes at or after this timestamp
limitinteger20Max passes to return (max 100)

​
Response

{
  "status": "success",
  "data": {
    "satellite_passes": [
      {
        "id": 1842,
        "name": "Bay of Biscay pass · CFOSAT · 14 May 10:00 UTC",
        "external_id": "cfosat-...",
        "satellite_pass_id": "cfosat-...",
        "platform": "CFOSAT",
        "mission": { "slug": "cfosat", "name": "CFOSAT" },
        "started_at": "2026-05-14T10:00:00Z",
        "ended_at": "2026-05-14T10:20:00Z",
        "buoy_count": 6,
        "observation_count": 18,
        "bounds": { "south": 43.0, "west": -5.0, "north": 47.0, "east": -1.0 }
      }
    ],
    "count": 1
  },
  "meta": { "timestamp": "2026-05-27T09:00:00Z" }
}
Each pass embeds a compact mission reference (slug + name); platform is the raw label stored on the pass. Use bounds to place the pass on a map and buoy_count / observation_count to gauge its density.

​
Typical flow

1

Discover missions

Call GET /buoys/satellites once to learn the available slugs and pass counts.
2

Filter passes

Call GET /buoys/satellite_passes?mission=<slug> to pull that satellite’s recent passes.
3

Map or chart

Use each pass’s bounds, time window, and counts to render coverage or feed a dashboard.