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