# (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
| 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 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.
{% hint style="info" %}
For more information on the data collected by Spotters, refer to the [product documentation](https://www.sofarocean.com/posts/spotter-product-documentation).
{% endhint %}
| 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 from Spotters in **Waves: Spectrum (Full)** mode. |
| `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](https://sofarocean.notion.site/Spotter-Data-Modes-e78a76f5f94e49f58bfd68845113c4a7) 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 `includeDirectionalMoments`is set to true. |
| `b1` | array | Second component of first directional movement. Returned if `includeDirectionalMoments`is set to true. |
| `a2` | array | First component of second directional movement. Returned if `includeDirectionalMoments`is set to true. |
| `b2` | array | Second component of second directional movement. Returned if `includeDirectionalMoments`is 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
```shell
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" %}
```json
{
"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" %}
```json
{
"status": "error",
"message": "Device not found"
}
```
{% endtab %}
{% tab title="401" %}
**Incorrect token:**
```json
{
"message": "Authentication Failed"
}
```
**Missing token:**
```json
{
"message": "No token provided"
}
```
{% endtab %}
{% endtabs %}