# Authentication
The Sofar API uses token-based authentication. To get started using the Sofar API, you'll need to retrieve or generate an authentication token.
{% hint style="info" %}
Get your authentication token [**here**](https://spotter.sofarocean.com/api)**.**
{% endhint %}
The authentication token is tied to your account, and will grant API access to all resources owned by or shared with your account. You can regenerate the authentication token at any time at [spotter.sofarocean.com/api](https://spotter.sofarocean.com/api), but this will invalidate all previous tokens.
The Wave Spectra API and the Spotter & Smart Mooring API both accept a valid API token either as a `token` in the request HTTP header or in the `token` query parameter.
# Wave Spectra
The Wave Spectra API provides full spectra 7-day forecast from the Sofar Operational WaveWatch III Model.
## Operational Wave Spectra Forecast
`GET` `https://api.sofarocean.com/api/op-wave-spectra/:lat/:lon`
This endpoint returns a list of locations you have access to, or retrieves NetCDF data for a target location.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------------------------------------- |
| lat | number | latitude of location in decimal degrees.
Must be 0.5º resolution.
|
| lon | number | longitude of location in decimal degrees.
Must be 0.5º resolution.
|
{% tabs %}
{% tab title="200 Example response of the list request, with lat and lon path parameters excluded." %}
```
{
"status": "success",
"data": [
{
"latitude": 34.5,
"longitude": 200.0,
"url": "https://api.sofarocean.com/api/op-wave-spectra/34.5/200"
}
]
}
```
{% endtab %}
{% endtabs %}
#### Example List Request
```
curl https://api.sofarocean.com/api/op-wave-spectra -H 'token: YOUR_API_TOKEN'
```
#### Example Data File Request
Content-Type: application/octet-stream\
Content-Disposition: attachment; filename="34.50\_200.00\_2019-12-19T12:00:00Z\_data.netcdf"
```
curl https://api.sofarocean.com/api/op-wave-spectra/34.5/200 -H 'token: YOUR_API_TOKEN' -J -O
```
## **Spectral File Description**
A Sofar Spectral File contains the variance density spectrum at a single grid point of the Sofar global wave model at an hourly resolution for the duration of the forecast. The data is stored in NetCDF format, and the variables contained in each file are listed in Table 1. A detailed description of the variables is given below.
| **Variable Name** | **Shape** | **Type** | **Units** |
| ---------------------------- | ------------------ | -------- | -------------------- |
| directions | ( Nd , ) | float | Degrees |
| frequencies | ( Nf , ) | float | Hertz |
| time | ( Nt , ) | integer | Seconds |
| latitude | ( 1 , ) | float | Decimal degrees |
| longitude | ( 1, ) | float | Decimal degrees |
| depth | ( 1, ) | float | Meters |
| frequency direction spectrum | ( Nt , Nd , Nf ) | float | Meters2/Hertz/Degree |
{% hint style="info" %}
Table 1: The shape column indicates the shape of the array containing the variable, with Nt denoting the number of entries in time, Nf the number of frequencies and Nd the number of directions.
{% endhint %}
### **Directions**
The direction vector contains the model directions at which the spectrum is stored. The directions are stored as a single vector of *Nd*=36 entries. Directions are measured counterclockwise from East. Each direction is given in degrees and indicates the direction the waves are traveling in. The directional grid has a constant resolution of 10 degrees ranging between \[0,360].
### **Frequencies**
The frequency vector contains the model frequencies at which the spectrum is stored. The frequencies are stored as a single vector of *Nf*=36 entries. Frequencies are measured in Hertz. The frequencies are defined on a logarithmic grid (1.1 growth factor) with minimum frequency *f=0.035* Hz and maximum frequency *f=0.98* Hz.
### **Time**
The time vector denotes the time of the spectral entries. Time is denoted in Unix Epoch time, i.e. as seconds elapsed since Jan 1, 1970 (UTC). The time vector will be different lengths depending on the forecast initialization time. The first time denotes the initialization of the forecast.
### **Latitude, Longitude**
The latitude and longitude are denoted in decimal degrees and indicate the location of the model grid point where the spectra were output.
### **Depth**
Depth denotes the depth in meters at the location considered.
### **Frequency Direction Spectrum**
The frequency direction spectrum contains the variance density as a function of time, direction, and frequency. Spectra are stored as a three-dimensional array where the first dimension is time, the second dimension is direction, and the third is frequency. Entries are stored as density values with units m2/Hz/deg.
# Spotter & Smart Mooring
The Spotter & Smart Mooring API gives you access to data transmitted by your Spotter and any attached Smart Mooring sensors via telemetry.
{% hint style="info" %}
For more information about accessing data from your Spotter(s), please refer to the [Data Access guide](https://sofarocean.notion.site/Spotter-Data-Access-Dashboard-API-SD-Card-c7f51351f82e4b21bc5e9251a84423c3).
{% endhint %}
# (GET) Devices
Retrieve a list of Spotters associated with your account.
`GET` `https://api.sofarocean.com/api/devices`
Returns a list containing the display name, Spotter ID, and hull type of any Spotters you have API access to (i.e., Spotters registered to or shared with your account).
## Query Parameters
| Name | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `excludeSharedDevices` | boolean | Default: false
Set true to limit the response to Spotters registered directly to your account. Any Spotters shared to your account will be excluded.
|
## Response Description
The response body contains a list of Spotters associated with the account, ordered by `spotterId`.
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `spotterId` | string | The Spotter's identifier. |
| `name` | string | The Spotter's display name, as configured in the [Spotter Dashboard](https://spotter.sofarocean.com/). Returns `null` if no display name has been set. |
| `hullType` | string | The Spotter's hull type.
Can be spotter, scout or velella.
|
## Examples
### Example Request
```bash
curl "https://api.sofarocean.com/api/devices" -H 'token: YOUR_API_TOKEN'
```
### Example Responses
{% tabs %}
{% tab title="200" %}
**2 Devices:**
```json
{
"message": "2 devices",
"data": {
"devices": [
{
"spotterId": "SPOT-0017",
"hullType": "spotter",
"name": "Mavericks 1"
},
{
"spotterId": "SPOT-0018",
"hullType": "spotter",
"name": "Golden Gate"
}
]
}
}
```
**No Devices:**
```json
{
"message": "0 devices",
"data": {
"devices": []
}
}
```
{% endtab %}
{% tab title="401" %}
**Incorrect Token:**
```json
{
"message": "Authentication Failed"
}
```
**Missing Token:**
```json
{
"message": "No token provided"
}
```
{% endtab %}
{% endtabs %}
# Spotter Data
Get access to data collected by onboard Spotter sensors.
The Spotter Data API endpoints report data gathered from onboard Spotter sensors, such as wave, wind, and sea surface temperature (SST) sensors.
# (GET) Latest Data
Retrieve the latest data from a Spotter.
`GET` `https://api.sofarocean.com/api/latest-data?spotterId=:spotterId`
Returns the most recently transmitted device, waves and sensor data from a Spotter, specified by `spotterId`.
## Query Parameters
| Name | Type | Description |
| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spotterId` | string | The identifier of the device you wish to retrieve information from. |
| `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.
|
| `includeDirectionalMoments` | boolean | Default: false
Set true to return directional moments data from Spotters in Waves: Spectrum (Full) mode.
|
| `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.
|
## Response Description
The response body includes general device information, the device status and data transmission details, and a data stream of the most recently transmitted samples, grouped by data type and ordered by timestamp.
{% 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. |
| `spotterName` | string | The Spotter's display name, as configured in the [Spotter Dashboard](https://spotter.sofarocean.com/). Returns `""` if no display name has been set. |
| `payloadType` | string | The type of payload. Can be `waves` (standard or partitioned), `sensorData` (Smart Mooring), `full` (full wave spectrum) or `track` (Track mode). |
| `batteryVoltage` | number | The Spotter's battery voltage level in volts.
Full battery: 3.8 - 4.1
Mid-level capacity: 3.6-3.7
Low: 3.5
Critically low: 3.3
Empty battery: 3.0
|
| `batteryPower` | number | The Spotter's battery power level in watts.
A negative value indicates the battery is supplying power to the system. A positive value indicates the solar system is recharging the battery.
|
| `solarVoltage` | number | The Spotter's measured solar-panel voltage in volts. |
| `humidity` | number | The Spotter's internal relative humidity as a percentage (%).
Sharp increases in absolute humidity (accounting for temperature) may indicate a leak. If relative humidity is greater than 70%, we recommend replacing the desiccant.
|
| `waves` | array | Waves data. |
| `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 | The Spotter's position at given timestamps. |
| `commSource` | string | The telemetry source used to transmit the data.
Can be cellular or satellite.
|
### 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 sample arrays include 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. Differences in transmission times are likely due to differences in sampling cadences.
Your Spotter's configured data mode and update rate will also impact the amount of samples included in a single data transmission. A Spotter with default settings (Waves: Standard and hourly update rate), for example, will include two 30-minute samples in an hourly update. To review or change your Spotter's data mode and update rate, open the [Spotter Dashboard](https://spotter.sofarocean.com/), find its Spotter card in the Map View, click the Gear icon to open the Settings tab, and scroll down to the Satellite data and Cellular data sections.
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. |
| `algorithm_version` | integer | The wind algorithm version, with `1` indicating version 1 and `2` indicating version 2. |
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
```bash
curl "https://api.sofarocean.com/api/latest-data?spotterId=SPOT-0018" -H 'token: YOUR_API_TOKEN'
```
### Example Response
{% 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-010423",
"spotterName": "",
"payloadType": "full",
"batteryVoltage": 4.01,
"batteryPower": -0.1,
"solarVoltage": 0,
"humidity": 75.2,
"track": [
{
"latitude": -37.4935167,
"longitude": 32.9982667,
"timestamp": "2026-03-11T19:06:01.000Z"
},
{
"latitude": -37.5133667,
"longitude": 33.00605,
"timestamp": "2026-03-11T19:26:01.000Z"
},
{
"latitude": -37.5337333,
"longitude": 33.0134333,
"timestamp": "2026-03-11T19:46:01.000Z"
}
],
"waves": [
{
"significantWaveHeight": 2.347,
"peakPeriod": 10.24,
"meanPeriod": 8.996,
"peakDirection": 208.988,
"peakDirectionalSpread": 41.774,
"meanDirection": 187.491,
"meanDirectionalSpread": 47.082,
"timestamp": "2026-03-11T19:46:01.000Z",
"latitude": -37.53373,
"longitude": 33.01343
}
],
"wind": [
{
"speed": 4.4,
"direction": 137,
"location": {
"latitude": -37.5337333,
"longitude": 33.0134333,
"timestamp": "2026-03-11T19:46:01.000Z"
},
"seasurfaceId": 1,
"algorithm_version": 1
}
],
"surfaceTemp": [
{
"degrees": 22.04,
"location": {
"latitude": -37.4935167,
"longitude": 32.9982667,
"timestamp": "2026-03-11T19:06:01.000Z"
}
},
{
"degrees": 22.02,
"location": {
"latitude": -37.5133667,
"longitude": 33.00605,
"timestamp": "2026-03-11T19:26:01.000Z"
}
},
{
"degrees": 22.02,
"location": {
"latitude": -37.5337333,
"longitude": 33.0134333,
"timestamp": "2026-03-11T19:46:01.000Z"
}
}
],
"partitionData": [
{
"partitions": [
{
"startFrequency": 0.025,
"endFrequency": 0.078125,
"significantWaveHeight": 0.69,
"meanPeriod": 15.38,
"meanDirection": 240.014,
"meanDirectionalSpread": 29.828
},
{
"startFrequency": 0.078125,
"endFrequency": 0.8,
"significantWaveHeight": 0.97,
"meanPeriod": 8.58,
"meanDirection": 251.647,
"meanDirectionalSpread": 29.645
}
],
"location": {
"latitude": -37.5337333,
"longitude": 33.0134333,
"timestamp": "2026-03-11T19:46:01.000Z"
}
}
],
"frequencyData": [
{
"frequency": [0.0293,0.03906,0.04883,...],
"df": [0.00977,0.00977,0.00977,...],
"a1": [-0.018573,-0.043988,-0.292278,...],
"b1": [0.100684,0.147605,0.587488,...],
"a2": [-0.143695,-0.148583,-0.27566,...],
"b2": [-0.186706,-0.174976,-0.319648,...],
"varianceDensity": [0.003497984,0.01050112,0.29932134400000004,...],
"direction": [169.54824416491098,163.4053337896601,153.54944229298735,...],
"directionalSpread": [76.76853080901289,74.52769022723301,47.512177743358464,...],
"timestamp": "2026-03-11T19:46:01.000Z",
"latitude": -37.53373,
"longitude": 33.01343
}
],
"barometerData": [
{
"units": "hPa",
"value": 1029.5,
"unit_type": "barometric_pressure",
"data_type_name": "sofar_meanbaropressure_13bits",
"latitude": -37.4935167,
"longitude": 32.9982667,
"timestamp": "2026-03-11T19:06:01.000Z"
},
{
"units": "hPa",
"value": 1029.5,
"unit_type": "barometric_pressure",
"data_type_name": "sofar_meanbaropressure_13bits",
"latitude": -37.5133667,
"longitude": 33.00605,
"timestamp": "2026-03-11T19:26:01.000Z"
},
{
"units": "hPa",
"value": 1029.4,
"unit_type": "barometric_pressure",
"data_type_name": "sofar_meanbaropressure_13bits",
"latitude": -37.5337333,
"longitude": 33.0134333,
"timestamp": "2026-03-11T19:46:01.000Z"
}
],
"commSource": "satellite"
}
}
```
{% 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 %}
# (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 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 %}
# (GET) Search
Retrieve data from Spotters within an area for a specified time window.
`GET` `https://api.sofarocean.com/api/search`
Returns data from all Spotters **registered** to your account within the specified geospatial area between `startDate` and `endDate`. Spotters shared with your account will not be included in the response.
{% hint style="info" %}
This a beta endpoint. All input and output parameters are subject to change without notice.
{% endhint %}
## Query Parameters
| Name | Type | Description |
|---|
shape | string | Either circle or envelope. The shape of the geospatial area you want to search. |
shapeParams | array | A comma-separated array of SRID 4326-compliant coordinates (latitude, longitude).
If shape is set to circle, there must be one pair. If shape is set to envelope, there must be two pairs.
e.g., "(1, -1), (2, -2)" translates to 1,-1,2,-2 |
startDate | string | ISO 8601-formatted timestamp indicating the start date for data inclusion.
e.g., 2021-01-01T07:00:00Z |
endDate | string | ISO 8601-formatted timestamp indicating the end date for data inclusion.
e.g., 2021-01-02T07:00:00Z |
pageSize | integer | Default: 500 The desired number of samples to be returned. |
radius | number | The radius in meters of the geospatial area to be queried if shape is circle.
This parameter is required if shape is circle. |
## Response Description
The response body consists of a data stream of transmissions within the specified geospatial area and during the specified time window, ordered by timestamp. Each element of the `data` array represents a transmission by a Spotter. The maximum number of data samples returned per page is capped at the `pageSize` limit.
| Name | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------------------ |
| `spotterId` | string | The Spotter's identifier. |
| `waves` | object | Waves data. |
| `wind` | object | Wind data. |
| `surfaceTemperature` | object | Surface temperature data from Spotters equipped with SST sensors. |
| `frequencyData` | object | Frequency data from Spotters in **Waves: Spectrum (Full)** mode. |
| `partitionData` | object | Partition data from Spotters in **Waves: Partition** mode or **HDR** mode. |
| `smartMooringData` | array | Information on the positioning and tilt of any Smart Mooring sensors. |
| `sensorData` | array | Data from Smart Mooring and/or Barometer sensors. |
| `timestamp` | string | ISO 8601-formatted timestamp indicating the end of a sample collection period. |
| `metadata` | object | The pagination of the response. |
## Examples
### Example Request
```bash
curl "https://api.sofarocean.com/api/search?shape=circle&shapeParams=37.788480,-122.387461&startDate=2026-02-05T00:00:00Z&endDate=2026-02-10T00:00:00Z&radius=250" -H 'token: YOUR_API_TOKEN'
```
### Example Responses
{% tabs %}
{% tab title="200" %}
**Results:**
{% code expandable="true" %}
```json
{
"data": [
{
"timestamp": "2021-01-01T00:00:00Z",
"latitude": 37.777777,
"longitude": -122.1212121,
"spotterId": "SPOT-0222",
"waves": {
"significantWaveHeight": 1.91,
"peakPeriod": 10.24,
"meanPeriod": 7.72,
"peakDirection": 302.735,
"peakDirectionalSpread": 55.142,
"meanDirection": 279.846,
"meanDirectionalSpread": 70.635
},
"frequencyData": {
"frequency": [0.02930,0.03906,0.04883,...],
"df": [0.00977, 0.00977, 0.00977,...],
"a1": [-0.097752, -0.095797, -0.054741,...],
"b1": [-0.054741, 0.021505, 0.073314,...],
"a2": [0.120235, 0.115347, -0.018573,...],
"b2": [0.414467, 0.180841, 0.184751,...],
"varianceDensity": [0.7111054247697032, 0.6186233367451381, 0.6411207778915046,...],
"direction": [335.6588548979852, 338.1985905136482, 269.8174396209903,...],
"directionalSpread": [79.181787169671, 74.12281945451112, 67.45630665882223,...]
},
"wind": {
"speed": 1,
"direction": 2,
"seasurfaceId": 1
},
"surfaceTemperature": {
"degrees": 15
},
"partitionData": {
"partitions": [
{
"startFrequency": 0.025,
"endFrequency": 0.1953125,
"significantWaveHeight": 36.95,
"meanPeriod": 30.24,
"meanDirection": 185.994,
"meanDirectionalSpread": 15.328
},
{
"startFrequency": 0.1953125,
"endFrequency": 0.8,
"significantWaveHeight": 34.55,
"meanPeriod": 25.58,
"meanDirection": 200.062,
"meanDirectionalSpread": 37.692
}
]
},
"smartMooringData": [
{
"sensorPosition": 1,
"degrees": 10.2
},
{
"sensorPosition": 2,
"degrees": 10.16
}
],
"sensorData": [
{
"sensorPosition": 1,
"units": "°C",
"value": 18.060000000000002,
"unit_type": "temperature",
"data_type_name": "sofar_temperature_12bits"
},
{
"sensorPosition": 2,
"units": "μbar",
"value": 1020490,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_meanpressure_21bits"
},
{
"sensorPosition": 2,
"units": "°C",
"value": 18.060000000000002,
"unit_type": "temperature",
"data_type_name": "rbrcoda3_meantemperature_20bits"
},
{
"sensorPosition": 2,
"units": "μbar",
"value": 90,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_stdevpressure_15bits"
}
]
},
{
"timestamp": "2021-01-01T00:01:00Z",
"latitude": 38.777777,
"longitude": -123.1212121,
"spotterId": "SPOT-0223",
...
},
...
],
"metadata": {
"page": {
"nextPage": "https://api.sofarocean.com/api/search?shape=envelope&startDate=2021-01-01T00:00:00.000Z&endDate=2021-02-01T00:00:00.000Z&shapeParams=37,-122,39,-124",
"hasMoreData": true
}
}
}
```
{% endcode %}
**No Results:**
```json
{
"data": [],
"metadata": {
"page": {
"nextPage": "https://api.sofarocean.com/api/search?cursor=eyJlbmREYXRlIjoiMjAyNi0wMy0xMFQwMDowMDowMFoiLCJyYWRpdXMiOiIyNSIsInNoYXBlIjoiY2lyY2xlIiwic2hhcGVQYXJhbXMiOiI0Mi41NTA1NDIzLCAxMS4xMTY5MDQzIiwic3RhcnREYXRlIjoiMjAyNi0wMy0wNVQwMDowMDowMFoiLCJjdXJzb3JJZCI6MH0%3D",
"hasMoreData": false,
"pageSize": 500
}
}
}
```
{% endtab %}
{% tab title="400 " %}
**No `radius` for `circle`:**
```json
{
"status": "error",
"message": "Valid radius not found! A valid radius is required when shape is circle"
}
```
**Improper `shapeParams`:**
```json
{
"status": "error",
"message": "Improper amount of lat/lon pairs! There must be exactly 1 pair(s)"
}
```
**Missing `startDate` :**
```json
{
"status": "error",
"message": "Invalid parameter startDate. Date value must be provided in ISO 8601 format"
}
```
{% endtab %}
{% tab title="401" %}
**Incorrect token:**
```json
{
"message": "Authentication Failed"
}
```
**Missing token:**
```json
{
"message": "No token provided"
}
```
{% endtab %}
{% endtabs %}
# Smart Mooring Data
Get access to data collected by Smart Moorings sensors.
The Spotter Smart Mooring API endpoints report data gathered by Smart Mooring sensors and relayed to Spotter devices.
# (GET) Sensor Data
Retrieve Smart Mooring data from a Spotter for a specified time window.
`GET` `https://api.sofarocean.com/api/sensor-data?spotterId=:spotterId&startDate=:startDate&endDate=:endDate`
Returns Smart Mooring sensor data collected and transmitted by a Spotter, specified by `spotterId`, between `startDate` and `endDate`.
## Query Parameters
| Name | Type | Description |
|---|
spotterId | string | The Spotter ID of the device you wish to retrieve information from. |
startDate | string | Default: 24 hours ago 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 |
includeSoundPressureReadings | boolean | Default: false
Set true to return sound pressure level (SPL) readings (i.e., 1-second resolution raw data) from Spotters with hydrophones transmitting via cellular*.
*Spotters with hydrophones transmitting via satellite will only return aggregated SPL samples. |
## Response Description
The response body consists of a flat (uncategorized) data stream of transmissions by the Spotter’s Smart Mooring sensors during the specified time window, ordered by timestamp. These timestamps, while ordered, are not necessarily unique. It is possible for two or more sensors to send different values at the same time, resulting in identical timestamps.
If the Spotter is configured to send multiple samples in a single transmission (e.g., to save on data telemetry costs), multiple samples in the response will have the same location data. To review a Spotter's (read-only) subsurface data transmission settings, open the [Spotter Dashboard](https://spotter.sofarocean.com/), find its Spotter card in the Map View, click the Gear icon to open the Settings tab, and scroll down to the Subsurface data transmission section.
{% hint style="info" %}
For more information about [Smart Mooring](https://www.notion.so/Smart-Mooring-Product-Documentation-Onboarding-557d26176ca6422fab42c879b2093d92?source=copy_link) sensors and data, please refer to the [Smart Mooring Sensors guide](https://sofarocean.notion.site/Sensors-Payloads-a26e005cc5374a7eb6a1e64a3b54b7de?pvs=74).
{% endhint %}
| Name | Type | Description |
| ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `latitude` | number | The Spotter's latitude when the report was encoded and transmitted. |
| `longitude` | number | The Spotter's longitude when the report was encoded and transmitted. |
| `timestamp` | string | ISO 8601-formatted timestamp indicating the end of a sample collection period. |
| `sensorPosition` | integer | The sensor's physical position in the Smart Mooring relative to the Spotter, with `1` being closest to the Spotter. |
| `units` | string | The units of measurement.
e.g., °C
|
| `value` | object, string or number | The measured value. |
| `unit_type` | string | A contextual description of what is being measured.
e.g., temperature
|
| `data_type_name` | string | The type of information being sent by a sensor, as ingested by the API.
e.g., sofar\_temperature\_12bits
|
| `configuration_checksum` | string | A unique identifier for the Smart Mooring configuration. Can be cross-referenced with the configurations returned by the Configuration History endpoint to determine the sensor configuration at the time of data collection.
e.g., 0xb6929687
|
## Examples
### Example Request
```bash
curl "https://api.sofarocean.com/api/sensor-data?spotterId=SPOT-0222&startDate=2021-12-01T00:00:00Z&endDate=2021-12-02T00:00:00Z" -H 'token: YOUR_API_TOKEN'
```
### Example Responses
{% tabs %}
{% tab title="200" %}
**Sensor data:**
{% code expandable="true" %}
```json
{
"status": "success",
"spotterId": "SPOT-31082C",
"data": [
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "hex",
"value": "84011a69b1f40f821901c8186ca2051901c811186c",
"unit_type": "binary",
"data_type_name": "binary_hex_encoded",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "unitless",
"value": 0,
"unit_type": "spectral_entropy",
"data_type_name": "bm_borealis_entropy_8bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "dB re µPa²",
"value": 0.75,
"unit_type": "interquartile_range",
"data_type_name": "bm_borealis_max_iqr_8bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "unitless",
"value": 16,
"unit_type": "index",
"data_type_name": "bm_borealis_max_iqr_band_number_6bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "dB re µPa²",
"value": {
"mean": [94.892,94.142,93.392,...],
"frequency": [40,50,63,...],
"band_number": [16,17,18,...],
"25th_percentile": [93.392,92.642,91.892,...],
"50th_percentile": [94.142,93.392,91.892,...],
"75th_percentile": [94.892,94.142,92.642,...]
},
"unit_type": "borealis_sound_pressure_level_stats",
"data_type_name": "bm_borealis_spl_band_stats",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:14:01.000Z",
"sensorPosition": 1,
"units": "dB re µPa²",
"value": 102.392,
"unit_type": "sound_pressure_level",
"data_type_name": "bm_borealis_spl_broadband_8bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:44:01.000Z",
"sensorPosition": 1,
"units": "hex",
"value": "84011a69b1fb16821901c8186ca4051901c811186912031603",
"unit_type": "binary",
"data_type_name": "binary_hex_encoded",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:44:01.000Z",
"sensorPosition": 1,
"units": "unitless",
"value": 0,
"unit_type": "spectral_entropy",
"data_type_name": "bm_borealis_entropy_8bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:44:01.000Z",
"sensorPosition": 1,
"units": "dB re µPa²",
"value": 0.75,
"unit_type": "interquartile_range",
"data_type_name": "bm_borealis_max_iqr_8bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:44:01.000Z",
"sensorPosition": 1,
"units": "unitless",
"value": 17,
"unit_type": "index",
"data_type_name": "bm_borealis_max_iqr_band_number_6bits",
"configuration_checksum": "0x03696310"
},
{
"latitude": 37.78845,
"longitude": -122.38695,
"timestamp": "2026-03-11T23:44:01.000Z",
"sensorPosition": 1,
"units": "dB re µPa²",
"value": 101.642,
"unit_type": "sound_pressure_level",
"data_type_name": "bm_borealis_spl_broadband_8bits",
"configuration_checksum": "0x03696310"
}
]
}
```
{% endcode %}
**No sensor data:**
```json
{
"status": "success",
"spotterId": "SPOT-30973C",
"data": []
}
```
{% 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 %}
# (GET) Sensor Configuration History
Retrieve Smart Mooring sensor configurations from a Spotter for a specified time window.
`GET` `https://api.sofarocean.com/api/sensor-configuration-history?spotterId=:spotterId&startDate=:startDate&endDate=:endDate`
Returns Smart Mooring sensor configurations for a Spotter, specified by `spotterId`, between `startDate` and `endDate`.
{% hint style="info" %}
This endpoint will only return sensor configuration history from June 2025 or later.
{% endhint %}
## Query Parameters
| Name | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `spotterId` | string | The Spotter ID of the device you wish to retrieve information from. |
| `startDate` | string | ISO 8601-formatted timestamp indicating the start date for data inclusion.
e.g., 2025-06-01T07:00:00Z
|
| `endDate` | string | ISO 8601-formatted timestamp indicating the end date for data inclusion.
e.g., 2025-06-02T07:00:00Z
|
## Response Description
The response body includes the configurations of all sensors attached to the Smart Mooring during the specified time window, ordered by timestamp. Each element of the `data` array represents a complete configuration at one time.
{% hint style="info" %}
For more information about [Smart Mooring](https://www.notion.so/Smart-Mooring-Product-Documentation-Onboarding-557d26176ca6422fab42c879b2093d92?source=copy_link) sensors and data, please refer to the [Smart Mooring Sensors guide](https://sofarocean.notion.site/Sensors-Payloads-a26e005cc5374a7eb6a1e64a3b54b7de?pvs=74).
{% endhint %}
| Name | Type | Description |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `timestamp` | string | ISO 8601-formatted timestamp indicating the time the configuration was reported by the Spotter.
The timestamp of the first entry will be at or after the specified startDate. This does not necessarily indicate the earliest time the configuration was used, as the sensor configuration could have been in use prior to the specified startDate.
|
| `configuration_checksum` | string | A unique identifier for the Smart Mooring configuration. Can be cross-referenced with the sensor data samples returned by the Sensor Data endpoint to determine the sensor configuration at the time of data collection.
If the sensors are returned to an earlier configuration, the configuration\_checksum will also return to its previous value (as long as the sensors are in the same position and have the same configured settings).
|
| `sensor_configurations` | array | The complete configuration of all sensors attached to the Spotter's Smart Mooring at a given time. |
### Sensor Configurations
The `sensor_configurations` array contains details on the configuration of each sensor.
| Name | Type | Description |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_name` | string | The name of the sensor, returned for Bristlemouth sensors.
For Bristlemouth Development Kits, app\_name can be changed for better identification of the device.
|
| `sensor_type` | object | The name and display name of the sensor. |
| `position` | integer | The sensor's physical position in the Smart Mooring relative to the Spotter, with `1` being closest to the Spotter and `0` being the Bristlemouth processor within the Spotter at the root of the Smart Mooring. |
| `configuration` | object | The sensor's configuration settings. |
| `data_types` | array | The data fields and units potentially returned by the sensor among its data samples. |
| `firmware_sha` | string | The Bristlemouth mote's firmware version. |
| `bristlemouth_node_id` | string | The Bristlemouth mote's ID. |
| `configuration_crc` | string | An error-detecting code for the Bristlemouth mote. |
## Examples
### Example Request
curl "https://api.sofarocean.com/api/sensor-configuration-history?spotterId=SPOT-0222&startDate=2025-12-01T07:00:00Z&endDate=2025-12-02T07:00:00Z" -H 'token: YOUR_API_TOKEN'
### Example Responses
{% tabs %}
{% tab title="200" %}
**Configuration history:**
{% code expandable="true" %}
```json
{
"status": "success",
"spotterId": "SPOT-31082C",
"data": [
{
"timestamp": "2025-09-02T02:16:07.000Z",
"sensor_configurations": [
{
"app_name": "bridge",
"position": 0,
"data_types": [],
"firmware_sha": "3610e39f",
"configuration": {
"sampleDurationMs": 840000,
"sampleIntervalMs": 1800000,
"samplesPerReport": 2,
"subsampleEnabled": 0,
"softReadingPeriodMs": 500,
"subsampleDurationMs": 60000,
"subsampleIntervalMs": 300000,
"ticksSamplingEnabled": 0,
"transmitAggregations": 1,
"alignmentInterval5Min": 1,
"sensorsCheckIntervalS": 60,
"sensorsPollIntervalMs": 10000,
"currentReadingPeriodMs": 60000,
"rbrCodaReadingPeriodMs": 500,
"disableUnusedPortsTimeMs": 0,
"turbidityReadingPeriodMs": 1000,
"bridgePowerControllerEnabled": 1
},
"configuration_crc": "0xedba5d73",
"bristlemouth_node_id": "0xd158263d60f8e3a1",
"sensor_type": {
"name": "bm_bridge_1",
"display_name": "Spotter"
}
},
{
"app_name": "borealis",
"position": 1,
"data_types": [
{
"units": "unitless",
"unit_type": "boolean",
"data_type_name": "generic_boolean_1bits"
},
{
"units": "dB re µPa²",
"unit_type": "sound_pressure_level",
"data_type_name": "bm_borealis_spl_broadband_8bits"
},
{
"units": "dB re µPa²",
"unit_type": "interquartile_range",
"data_type_name": "bm_borealis_max_iqr_8bits"
},
{
"units": "unitless",
"unit_type": "index",
"data_type_name": "bm_borealis_max_iqr_band_number_6bits"
},
{
"units": "unitless",
"unit_type": "spectral_entropy",
"data_type_name": "bm_borealis_entropy_8bits"
},
{
"units": "unitless",
"unit_type": "buffer_length",
"data_type_name": "generic_buffer_length_8bits"
},
{
"units": "bit",
"unit_type": "bit",
"data_type_name": "generic_dummy_1bits"
}
],
"firmware_sha": "98b26cbb",
"configuration": {
"enable_dsp": 1,
"enable_sbc": 1,
"dfu_confirm": 1,
"sample_rate": 48000,
"sbc_command": "/usr/local/bin/borealis_hydrotwin.sh",
"hydrotwin_ldr": 3,
"report_interval": 810,
"enable_daq_recording": 1,
"disableUnusedPortsTimeMs": 0
},
"configuration_crc": "0x4d24634d",
"bristlemouth_node_id": "0x9d24ede22a7e7413",
"sensor_type": {
"name": "bm_borealis_1",
"display_name": "Bristlemouth Borealis Hydrophone"
}
}
],
"configuration_checksum": "0x4b15a6d0"
},
{
"timestamp": "2025-09-05T02:43:58.000Z",
"sensor_configurations": [
{
"app_name": "bridge",
"position": 0,
"data_types": [],
"firmware_sha": "3610e39f",
"configuration": {
"sampleDurationMs": 840000,
"sampleIntervalMs": 1800000,
"samplesPerReport": 2,
"subsampleEnabled": 0,
"softReadingPeriodMs": 500,
"subsampleDurationMs": 60000,
"subsampleIntervalMs": 300000,
"ticksSamplingEnabled": 0,
"transmitAggregations": 1,
"alignmentInterval5Min": 1,
"sensorsCheckIntervalS": 60,
"sensorsPollIntervalMs": 10000,
"currentReadingPeriodMs": 60000,
"rbrCodaReadingPeriodMs": 500,
"disableUnusedPortsTimeMs": 0,
"turbidityReadingPeriodMs": 1000,
"bridgePowerControllerEnabled": 1
},
"configuration_crc": "0xedba5d73",
"bristlemouth_node_id": "0xd158263d60f8e3a1",
"sensor_type": {
"name": "bm_bridge_1",
"display_name": "Spotter"
}
},
{
"app_name": "borealis",
"position": 1,
"data_types": [
{
"units": "unitless",
"unit_type": "boolean",
"data_type_name": "generic_boolean_1bits"
},
{
"units": "dB re µPa²",
"unit_type": "sound_pressure_level",
"data_type_name": "bm_borealis_spl_broadband_8bits"
},
{
"units": "dB re µPa²",
"unit_type": "interquartile_range",
"data_type_name": "bm_borealis_max_iqr_8bits"
},
{
"units": "unitless",
"unit_type": "index",
"data_type_name": "bm_borealis_max_iqr_band_number_6bits"
},
{
"units": "unitless",
"unit_type": "spectral_entropy",
"data_type_name": "bm_borealis_entropy_8bits"
},
{
"units": "unitless",
"unit_type": "buffer_length",
"data_type_name": "generic_buffer_length_8bits"
},
{
"units": "bit",
"unit_type": "bit",
"data_type_name": "generic_dummy_1bits"
}
],
"firmware_sha": "98b26cbb",
"configuration": {
"enable_dsp": 1,
"enable_sbc": 0,
"dfu_confirm": 1,
"sample_rate": 31250,
"sbc_command": "/usr/local/bin/borealis_hydrotwin.sh",
"enable_pgram": 0,
"hydrotwin_ldr": 3,
"report_interval": 810,
"sensorBmLogEnable": 1,
"enable_daq_recording": 1,
"sensorsCheckIntervalS": 60,
"sensorsPollIntervalMs": 5000,
"disableUnusedPortsTimeMs": 0
},
"configuration_crc": "0x332d39ff",
"bristlemouth_node_id": "0x9d24ede22a7e7413",
"sensor_type": {
"name": "bm_borealis_1",
"display_name": "Bristlemouth Borealis Hydrophone"
}
}
],
"configuration_checksum": "0x9fedcb4e"
},
...
]
}
```
{% endcode %}
**No configuration history:**
```json
{
"status": "success",
"spotterId": "SPOT-010423",
"data": []
}
```
{% 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 %}
# Test the API
Try the Spotter & Smart Mooring API for yourself.
## Demo API Token
Include this API token in the header or query parameters of your requests to retrieve sample data:
space.vars.demo_api_token
## Walkthrough
{% stepper %}
{% step %}
#### Get a list of Spotters associated with the demo account
Use the [Devices endpoint](/spotter-and-smart-mooring/fetch-devices) to retrieve a list of Spotters associated with the demo account, ordered by `spotterId`.
curl "https://api.sofarocean.com/api/devices" -H 'token: space.vars.demo_api_token'
{% endstep %}
{% step %}
#### Get the latest data from the demo account's Spotters
Choose a `spotterId` from the list of Spotters associated with the demo account and use the [Latest Data endpoint](/spotter-and-smart-mooring/spotter-data/latest-data) to retrieve the most recently transmitted device, waves and sensor data for that Spotter.
curl "https://api.sofarocean.com/api/latest-data?spotterId=space.vars.spotter_id_1" -H 'token: space.vars.demo_api_token'
Change the `spotterId` to retrieve the latest data from another one of the demo account's Spotters and/or try adjusting the other [query parameters](/spotter-and-smart-mooring/spotter-data/latest-data#query-parameters) (e.g., `includeSurfaceTempData`, `includeWindData` , etc.) to modify which data is returned.
{% endstep %}
{% step %}
#### Get data from that Spotter for a specified time window
Use the [Wave Data endpoint](/spotter-and-smart-mooring/spotter-data/wave-data) to retrieve data from one of the demo account's Spotters, specified by `spotterId`, for a given time window. By default, the response will consist of general device information and up to 20 of the most recent data samples.
curl "https://api.sofarocean.com/api/wave-data?spotterId=space.vars.spotter_id_1" -H 'token: space.vars.demo_api_token'
Change the `spotterId` to retrieve the data from another one of the demo account's Spotters and/or try adjusting the other [query parameters](/spotter-and-smart-mooring/spotter-data/wave-data#query-parameters) (e.g., `startDate`, `endDate` , `includeBarometerData` etc.) to modify which data is returned.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
You can also use the demo API token to call the Sensor Data and Sensor Configuration Endpoints, but the data arrays in the responses will be empty because the demo account has no registered Smart Mooring devices.
{% endhint %}
# Data Forwarding
Forward newly generated data to your delivery endpoints via POST requests.
Set up optional custom delivery endpoints to get a POST request any time one of your Spotters generates new data.
You can configure and manage your delivery endpoints in the [Spotter Dashboard](https://spotter.sofarocean.com/api). To add a new delivery endpoint, click the menu icon ☰ and select **Sofar API**, then under **Delivery Endpoints**, enter the URL path in the **New Delivery Endpoint** field and click the **Add Endpoint** button. All of your delivery endpoints will be listed there. To remove one, click the corresponding **Remove** button.
Any new data will be included in the JSON body of the POST request. The content and structure will vary based on the Spotter's operating mode and configuration.
## Examples
{% tabs %}
{% tab title="Request Body: Waves Mode" %}
{% 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-0018",
"spotterName": "Mavericks 2",
"payloadType": "waves",
"batteryVoltage": 4.07,
"batteryPower": -0.41,
"solarVoltage": 0.0,
"humidity": 32.8,
"waves": [
{
"significantWaveHeight": 1.14,
"peakPeriod": 9.3,
"meanPeriod": 8.3,
"peakDirection": 302.3,
"peakDirectionalSpread": 42.11,
"meanDirection": 286.2,
"meanDirectionalSpread": 56.16,
"timestamp": "2017-11-08T07:06:57.000Z",
"latitude": 34.30115,
"longitude": -120.6133
},
{
"significantWaveHeight": 1.14,
"peakPeriod": 10.24,
"meanPeriod": 8.44,
"peakDirection": 312.28,
"peakDirectionalSpread": 37.07,
"meanDirection": 284.18,
"meanDirectionalSpread": 57.4,
"timestamp": "2017-11-08T07:36:57.000Z",
"latitude": 34.29883,
"longitude": -120.61127
}
],
"track": [
{
"timestamp": "2017-11-08T07:06:57.000Z",
"latitude": 34.30115,
"longitude": -120.6133
},
{
"timestamp": "2017-11-08T07:36:57.000Z",
"latitude": 34.2988333,
"longitude": -120.6112667
}
],
"frequencyData": [
{
"frequency": [0.02930,0.03906,0.04883,...],
"df": [0.00977, 0.00977, 0.00977,...],
"a1": [-0.097752, -0.095797, -0.054741,...],
"b1": [-0.054741, 0.021505, 0.073314,...],
"a2": [0.120235, 0.115347, -0.018573,...],
"b2": [0.414467, 0.180841, 0.184751,...],
"varianceDensity": [0.7111054247697032, 0.6186233367451381, 0.6411207778915046,...],
"direction": [335.6588548979852, 338.1985905136482, 269.8174396209903,...],
"directionalSpread": [79.181787169671, 74.12281945451112, 67.45630665882223,...],
"timestamp": "2017-10-12T13:28:40.000Z",
"latitude": 35.19229,
"longitude": -120.86748
}
],
"partitionData": [
{
"partitions": [
{
"startFrequency": 0.025,
"endFrequency": 0.078125,
"significantWaveHeight": 0.69,
"meanPeriod": 15.38,
"meanDirection": 240.014,
"meanDirectionalSpread": 29.828
},
{
"startFrequency": 0.078125,
"endFrequency": 0.8,
"significantWaveHeight": 0.97,
"meanPeriod": 8.58,
"meanDirection": 251.647,
"meanDirectionalSpread": 29.645
}
],
"location": {
"latitude": 35.19229,
"longitude": -120.86748,
"timestamp": "2017-10-12T13:28:40.000Z"
}
}
],
"wind": [
{
"speed": 1,
"direction": 171,
"location": {
"latitude": 37.8973,
"longitude": -122.6868833,
"timestamp": "2019-08-09T20:14:54.000Z"
},
"seasurfaceId": 1
}
],
"surfaceTemp": [
{
"degrees": 14.44,
"location": {
"latitude": 37.7733,
"longitude": -122.3861833,
"timestamp": "2019-11-05T19:34:31.000Z"
}
}
],
...
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Request Body: Track Mode" %}
{% hint style="info" %}
The `track` property represents a Spotter's location, ordered by `timestamp` values.
{% endhint %}
{% code expandable="true" %}
```json
{
"data": {
"spotterId": "SPOT-0018",
"spotterName": "Mavericks 2",
"payloadType": "track",
"batteryVoltage": 4.13,
"batteryPower": -0.03,
"solarVoltage": 7,
"humidity": 9.6,
"waves": [],
"track": [
{
"timestamp": "2017-09-27T22:41:27.000Z",
"latitude": 34.777083,
"longitude": -120.7396172
},
{
"timestamp": "2017-09-27T22:44:27.000Z",
"latitude": 34.7769077,
"longitude": -120.7390585
},
{
"timestamp": "2017-09-27T22:47:27.000Z",
"latitude": 34.776726,
"longitude": -120.7385352
},
{
"timestamp": "2017-09-27T22:50:27.000Z",
"latitude": 34.7765415,
"longitude": -120.7380058
},
{
"timestamp": "2017-09-27T22:53:27.000Z",
"latitude": 34.7763545,
"longitude": -120.7375838
}
],
"frequencyData": [],
"partitionData": [],
"wind": []
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Request Body: Smart Mooring" %}
{% hint style="info" %}
* The `sensorPosition` property represents a sensor's physical position in the Smart Mooring relative to the Spotter, with **`1`** being closest to the Spotter.
* The `data_type_name` property represents the type of information being sent by a sensor, as ingested by the API.
* Timestamps within this data format, while ordered, are not necessarily unique. It is possible for two or more sensors to send different values with identical timestamps (e.g., a temperature sensor and a pressure sensor may both emit data at the same time).
{% endhint %}
{% code expandable="true" %}
```json
{
"data": {
"spotterId": "SPOT-0018",
"spotterName": "Mavericks 2",
"payloadType": "sensorData",
"batteryVoltage": 4.13,
"batteryPower": -0.03,
"solarVoltage": 7,
"humidity": 9.6,
"sensorData": [
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-01T23:46:43.000Z",
"sensorPosition": 2,
"units": "μbar",
"value": 1020490,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_meanpressure_21bits"
},
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-01T23:46:43.000Z",
"sensorPosition": 2,
"units": "μbar",
"value": 100,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_stdevpressure_15bits"
},
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-01T23:46:43.000Z",
"sensorPosition": 2,
"units": "°C",
"value": 13.426700000000004,
"unit_type": "temperature",
"data_type_name": "rbrcoda3_meantemperature_20bits"
},
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-02T00:01:43.000Z",
"sensorPosition": 2,
"units": "μbar",
"value": 1020390,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_meanpressure_21bits"
},
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-02T00:01:43.000Z",
"sensorPosition": 2,
"units": "μbar",
"value": 50,
"unit_type": "pressure",
"data_type_name": "rbrcoda3_stdevpressure_15bits"
},
{
"latitude": 37.7733833,
"longitude": -122.38715,
"timestamp": "2020-12-02T00:01:43.000Z",
"sensorPosition": 2,
"units": "°C",
"value": 15.081299999999999,
"unit_type": "temperature",
"data_type_name": "rbrcoda3_meantemperature_20bits"
}
]
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}