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.

This a beta endpoint. All input and output parameters are subject to change without notice.

## 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. |

## Example Request

```
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

### 200

```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
        }
    }
}
```

### No Results

```json
{
    "data": [],
    "metadata": {
        "page": {
            "nextPage": "https://api.sofarocean.com/api/search?cursor=eyJlbmREYXRlIjoiMjAyNi0wMy0xMFQwMDowMDowMFoiLCJyYWRpdXMiOiIyNSIsInNoYXBlIjoiY2lyY2xlIiwic2hhcGVQYXJhbXMiOiI0Mi41NTA1NDIzLCAxMS4xMTY5MDQzIiwic3RhcnREYXRlIjoiMjAyNi0wMy0wNVQwMDowMDowMFoiLCJjdXJzb3JJZCI6MH0%3D",
            "hasMoreData": false,
            "pageSize": 500
        }
    }
}
```

### 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"
}
```

### Incorrect token:

```json
{
    "message": "Authentication Failed"
}
```

### Missing token:

```json
{
    "message": "No token provided"
}
```