(GET) Historical Data

Retrieve data from a Spotter for a specified time window.

GET https://api.sofarocean.com/api/wave-data?spotterId=:spotterId

Returns waves and sensor data collected and transmitted by a Spotter, specified by spotterId, between startDate and endDate.

For Spotters shared, but not registered, to your account, your access will be limited to data collected within the past 30 days.

Query Parameters

Name	Type	Description
spotterId	string	The identifier of the device you wish to retrieve data from.
limit	integer	Default: 20 Maximum: 500 * The maximum amount of data to be included in the response. *100 if frequencyData is included in the response
startDate	string	Default: null ISO 8601-formatted timestamp indicating the start date for data inclusion. e.g., 2021-01-01T07:00:00Z
endDate	string	Default: now() ISO 8601-formatted timestamp indicating the end date for data inclusion. e.g., 2021-01-02T07:00:00Z
includeWaves	boolean	Default: true Set false to omit waves data.
includeWindData	boolean	Default: false Set true to return wind data.
includeSurfaceTempData	boolean	Default: false Set true to return surface temperature data from Spotters equipped with SST sensors.
includeFrequencyData	boolean	Default: false Set true to return frequency data (i.e., spectral data) for samples collected in Waves: Spectrum mode or HDR mode. processingSources must also be set to hdr or all.
includeDirectionalMoments	boolean	Default: false Set true to return directional moments data for samples collected in Waves: Spectrum mode. includeFrequencyData must also be set to true.
includePartitionData	boolean	Default: false Set true to return partition data from Spotters in Waves: Partition mode or HDR mode.
includeBarometerData	boolean	Default: false Set true to return barometer data from Spotters equipped with barometers.
includeTrack	boolean	Default: false Set true to return location tracking data.
processingSources	string	Default: embedded The data processing source, which can be embedded, hdr*, or all. *hdr is only applicable to Spotters in HDR mode with cellular enabled.

Response Description

The response body includes general device information and a data stream of samples transmitted during the specified time window, grouped by data type and ordered by timestamp. The maximum number of data samples returned per data type is capped at the set limit.

For more information on the data collected by Spotters, refer to the product documentation.

Name	Type	Description
spotterId	string	The Spotter's identifier.
limit	integer	The maximum amount of data included in the response.
waves	array	Waves data if includeWaves is set to true.
wind	array	Wind data if includeWindData is set to true.
surfaceTemp	array	Surface temperature data from Spotters equipped with SST sensors if includeSurfaceTempData is set to true.
frequencyData	array	Frequency data (i.e., spectral data) from Spotters in Waves: Spectrum (Full) mode or HDR mode if includeFrequencyData is set to true. Includes directional moments data if includeDirectionalMoments is set to true.
partitionData	array	Partition data from Spotters in Waves: Partition mode or HDR mode if includePartitionData is set to true.
barometerData	array	Barometer data from Spotters equipped with barometers if includeBarometerData is set to true.
track	array	Tracking data.

Data Samples

The returned data types depend on your set query parameters as well as your Spotter's configured data mode at the time of collection.

Regardless, all data samples will include the location (latitude, longitude) when the report was encoded and transmitted, the processing_source (embedded or hdr) and an ISO 8601-formatted timestamp, indicating the end of the sample collection period.

waves

Name	Type	Description
significantWaveHeight	number	Bulk significant wave height in meters (m).
peakPeriod	number	Peak wave period in seconds (s).
meanPeriod	number	Mean wave period in seconds (s).
peakDirection	number	Peak wave direction in degrees (°).
peakDirectionalSpread	number	Peak wave directional spreading in degrees (°).
meanDirection	number	Mean wave direction in degrees (°).
meanDirectionalSpread	number	Mean wave directional spreading in degrees (°).

wind

Name	Type	Description
speed	number	Wind speed in meters per second (m/s).
direction	number	Wind direction in degrees (°).
seasurfaceId	integer	Classification of the sea surface, with 1 meaning glassy, 2 meaning choppy, and 3 meaning rough.

surfaceTemp

Name	Type	Description
degrees	number	The surface temperature in degrees (°).

frequencyData

Name	Type	Description
frequency	array	Center frequency in hertz (Hz).
df	array	Spectral width in hertz (Hz).
a1	array	First component of first directional movement. Returned if includeDirectionalMomentsis set to true.
b1	array	Second component of first directional movement. Returned if includeDirectionalMomentsis set to true.
a2	array	First component of second directional movement. Returned if includeDirectionalMomentsis set to true.
b2	array	Second component of second directional movement. Returned if includeDirectionalMomentsis set to true.
varianceDensity	array	Surface variance density in meters squared per hertz (m2/Hz).
direction	array	Wave direction.
directionalSpread	array	Wave directional spread.

partitionData

Name	Type	Description
startFrequency	number	Starting frequency of the partition in hertz (Hz).
endFrequency	number	Ending frequency of the partition in hertz (Hz).
significantWaveHeight	number	Significant wave height of the partition in meters (m).
meanPeriod	number	Mean wave period of the partition in meters (m).
meanDirection	number	Mean wave direction of the partition in degrees (°).
meanDirectionalSpread	number	Mean wave directional spread of the partition in degrees (°).

barometerData

Name	Type	Description
value	number	The measured value.
units	string	The units of measurement. e.g., hPa
unit_type	string	A contextual description of what is being measured. e.g., barometric_pressure
data_type_name	string	The type of information being sent by a sensor, as ingested by the API. e.g., sofar_meanbaropressure_13bits

track

The track array only contains the location (latitude, longitude) when the report was encoded and transmitted as well as an ISO 8601-formatted timestamp, indicating the end of the sample collection period.

Examples

Example Request

curl "https://api.sofarocean.com/api/wave-data?spotterId=SPOT-0222&limit=20" -H 'token: YOUR_API_TOKEN'

Example Responses

200

frequencyData is only transmitted in Waves: Spectrum mode or HDR mode, and partitionData is only transmitted in Waves: Partition mode or HDR mode.

{
    "data": {
        "spotterId": "SPOT-30973C",
        "limit": 20,
        "waves": [
            {
                "significantWaveHeight": 6.055,
                "peakPeriod": 25.602,
                "meanPeriod": 15.842,
                "peakDirection": 73.88,
                "peakDirectionalSpread": 74.645,
                "meanDirection": 34.712,
                "meanDirectionalSpread": 69.768,
                "timestamp": "2026-02-09T21:00:00.000Z",
                "latitude": 37.78838,
                "longitude": -122.3873,
                "processing_source": "hdr"
            },
            ...
        ],
        "track": [
            {
                "latitude": 37.78885,
                "longitude": -122.38805,
                "timestamp": "2026-02-09T20:22:35.000Z",
                "processing_source": "embedded"
            },
            ...
        ],
        "wind": [
            {
                "speed": 3.6,
                "direction": 22,
                "seasurfaceId": 1,
                "latitude": 37.7883833,
                "longitude": -122.3872833,
                "timestamp": "2026-02-09T20:55:00.000Z",
                "processing_source": "embedded"
            },
            ...
        ],
        "surfaceTemp": [
            {
                "degrees": 18.07,
                "latitude": 37.7884802,
                "longitude": -122.3874607,
                "timestamp": "2026-02-09T20:50:00.000Z",
                "processing_source": "hdr"
            },
            ...
        ],
        "barometerData": [
            {
                "latitude": 37.7884802,
                "longitude": -122.3874607,
                "timestamp": "2026-02-09T20:50:00.000Z",
                "units": "hPa",
                "value": 1020.24,
                "unit_type": "barometric_pressure",
                "data_type_name": "sofar_meanbaropressure_13bits",
                "processing_source": "hdr"
            },
            ...
        ],
        "frequencyData": [
            {
                "frequency": [0.0293,0.03906,0.04883,...],
                "df": [0.00977,0.00977,0.00977,...],
                "a1": [-0.263793,-0.145408,-0.079853,...],
                "b1": [-0.156966,-0.042024,-0.011402,...],
                "a2": [-0.279535,-0.249703,-0.362721,...],
                "b2": [0.357514,0.279398,0.498925,...],
                "varianceDensity": [31.657672703999996,56.993054719999996,31.283789823999996,...],
                "direction": [59.245884309453686,73.8803104577832,81.87381531971278,...],
                "directionalSpread": [67.45535919200792,74.64481950023747,77.69177038569596,...],
                "timestamp": "2026-02-09T21:00:00.000Z",
                "latitude": 37.78838,
                "longitude": -122.3873,
                "processing_source": "hdr"
            },
            ...
        ],
        "partitionData": [
            {
                "partitions": [
                    {
                        "startFrequency": 0.029296875,
                        "endFrequency": 0.126953125,
                        "significantWaveHeight": 5.902,
                        "meanPeriod": 17.432,
                        "meanDirection": 32.146,
                        "meanDirectionalSpread": 69.084
                    },
                    {
                        "startFrequency": 0.126953125,
                        "endFrequency": 0.80078125,
                        "significantWaveHeight": 1.35,
                        "meanPeriod": 5.776,
                        "meanDirection": 22.918,
                        "meanDirectionalSpread": 70.757
                    }
                ],
                "latitude": 37.7883843,
                "longitude": -122.3873023,
                "timestamp": "2026-02-09T21:00:00.000Z",
                "processing_source": "hdr"
            },
            ...
        ]
    }
}

400

{
    "status": "error",
    "message": "Device not found"
}

401

Incorrect token:

{
    "message": "Authentication Failed"
}

Missing token:

{
    "message": "No token provided"
}