For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

(GET) Historical Data

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

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.

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.

Examples

Example Request

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

Example Responses

{% tabs %} {% tab title="200 " %} {% hint style="info" %} frequencyData is only transmitted in Waves: Spectrum mode or HDR mode, and partitionData is only transmitted in Waves: Partition mode or HDR mode. {% endhint %}

{% code expandable="true" %}

{
    "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"
            },
            ...
        ]
    }
}

{% endcode %} {% endtab %}

{% tab title="400" %}

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

{% endtab %}

{% tab title="401" %} Incorrect token:

{
    "message": "Authentication Failed"
}

Missing token:

{
    "message": "No token provided"
}

{% endtab %} {% endtabs %}