For the complete documentation index, see [llms.txt](https://docs.sofarocean.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sofarocean.com/~/revisions/i4w2YzZYZxcM4UMsnSvX/spotter-and-smart-mooring/spotter-data/wave-data.md).

# (GET) Historical Data

<mark style="color:blue;">`GET`</mark> `https://api.sofarocean.com/api/wave-data?spotterId=:spotterId`

Returns waves and sensor data collected by the specified Spotter between `startDate` and `endDate`.

For Spotters shared, but not registered, to your account, you can only retrieve 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`                     | number  | <p>Default: <code>20</code><br>Maximum: <code>500</code> *</p><p></p><p>The maximum amount of data to be included in the response.<br><br>*<code>100</code> if <code>frequencyData</code> is included in the response</p>                                                                         |
| `startDate`                 | string  | <p>Default: <code>null</code><br><br>ISO 8601-formatted timestamp indicating the start date for data inclusion.<br><br>e.g., <code>2021-01-01T07:00:00Z</code></p>                                                                                                                                |
| `endDate`                   | string  | <p>Default: <code>now()</code><br><br>ISO 8601-formatted timestamp indicating the end date for data inclusion.<br><br>e.g.,  <code>2021-01-02T07:00:00Z</code></p>                                                                                                                                |
| `includeWaves`              | boolean | <p>Default: <code>true</code><br><br>Set <code>false</code> to omit waves data.</p>                                                                                                                                                                                                               |
| `includeWindData`           | boolean | <p>Default: <code>false</code><br></p><p>Set <code>true</code> to return wind data.</p>                                                                                                                                                                                                           |
| `includeSurfaceTempData`    | boolean | <p>Default: <code>false</code><br><br>Set <code>true</code> to return surface temperature data from </p><p>Spotters equipped with SST sensors.</p>                                                                                                                                                |
| `includeTrack`              | boolean | <p>Default: <code>false</code><br></p><p>Set <code>true</code> to return location tracking data.</p>                                                                                                                                                                                              |
| `includeFrequencyData`      | boolean | <p>Default: <code>false</code><br><br>Set <code>true</code> to return frequency data for samples collected in <strong>Waves: Spectrum</strong> mode or <strong>HDR</strong> mode\*. <br><br>\*In combination with <code>processingSources</code> set to <code>hdr</code> or <code>all</code>.</p> |
| `includeDirectionalMoments` | boolean | <p>Default: <code>false</code><br></p><p>Set <code>true</code> to return directional moments data for samples collected in <strong>Waves: Spectrum</strong> mode. <code>includeFrequencyData</code> must also be set to <code>true</code>.</p>                                                    |
| `includePartitionData`      | boolean | <p>Default: <code>false</code><br><br>Set <code>true</code> to return partition data from Spotters in <strong>Waves: Partition</strong> mode or <strong>HDR</strong> mode.</p>                                                                                                                    |
| `includeBarometerData`      | boolean | <p>Default: <code>false</code><br><br>Set <code>true</code> to return barometer data from Spotters equipped with barometers.</p>                                                                                                                                                                  |
| `processingSources`         | string  | <p>Default: <code>embedded</code></p><p><br>The data processing source, which can be <code>embedded</code>, <code>hdr</code>*, or <code>all</code>.</p><p></p><p>*<code>hdr</code> is only applicable to Spotters in <strong>HDR</strong> mode with cellular enabled.</p>                         |

### Response Description

For more information on the data collected by Spotters, see the [product documentation](/content/posts/spotter-product-documentation/index.html).

| Name                       | Description | Units            |
| -------------------------- | ----------- | ---------------- |
| `significantWaveHeight`    |             | meters           |
| `peakPeriod`, `meanPeriod` |             | seconds          |
| `varianceDensity`          |             | m<sup>2</sup>/Hz |
| `windSpeed`                |             | m/s              |
|                            |             |                  |
|                            |             |                  |

### Examples

#### Example Request

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

#### Example Response

{% tabs %}
{% tab title="200 " %}

```json
{
  "data": {
    "spotterId": "SPOT-0222",
    "limit": 20,
    "waves": [
      {
        "significantWaveHeight": 1.91,
        "peakPeriod": 10.24,
        "meanPeriod": 7.72,
        "peakDirection": 302.735,
        "peakDirectionalSpread": 55.142,
        "meanDirection": 279.846,
        "meanDirectionalSpread": 70.635,
        "timestamp": "2020-01-08T00:24:31.000Z",
        "latitude": 34.64697,
        "longitude": -159.877,
        "processing_source": "embedded"
      },
      {...}
    ],
    "track": [
      {
        "timestamp": "2017-09-27T22:41:27.000Z",
        "latitude": 34.777083,
        "longitude": -120.7396172,
        "processing_source": "embedded"
      },
      {
        "timestamp": "2017-09-27T22:44:27.000Z",
        "latitude": 34.7769077,
        "longitude": -120.7390585,
        "processing_source": "embedded"
      },
      ...
    ],
    "frequencyData": [...],
    "wind": [...],
    "partitionData": [...]
  }
}
```

{% endtab %}
{% endtabs %}