# (GET) Search

<mark style="color:blue;">`GET`</mark> `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

<table><thead><tr><th>Name</th><th>Type</th><th width="250">Description</th></tr></thead><tbody><tr><td><code>shape</code></td><td>string</td><td><p>Either <code>circle</code> or <code>envelope</code>.</p><p></p><p>The shape of the geospatial area you want to search.</p></td></tr><tr><td><code>shapeParams</code></td><td>array</td><td>A comma-separated array of SRID 4326-compliant coordinates (latitude, longitude).<br><br>If <code>shape</code> is set to <code>circle</code>, there must be one pair. If <code>shape</code> is set to <code>envelope</code>, there must be two pairs.<br><br>e.g., "(1, -1), (2, -2)" translates to <code>1,-1,2,-2</code></td></tr><tr><td><code>startDate</code></td><td>string</td><td>ISO 8601-formatted timestamp indicating the start date for data inclusion.<br><br>e.g., <code>2021-01-01T07:00:00Z</code></td></tr><tr><td><code>endDate</code></td><td>string</td><td>ISO 8601-formatted timestamp indicating the end date for data inclusion.<br><br>e.g.,  <code>2021-01-02T07:00:00Z</code></td></tr><tr><td><code>pageSize</code></td><td>integer</td><td><p>Default: <code>500</code></p><p></p><p>The desired number of samples to be returned.</p></td></tr><tr><td><code>radius</code></td><td>number</td><td>The radius in meters of the geospatial area to be queried if <code>shape</code> is <code>circle</code>.<br><br>This parameter is required if <code>shape</code> is <code>circle</code>.</td></tr></tbody></table>

## 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sofarocean.com/spotter-and-smart-mooring/spotter-data/search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.