search.md

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

(GET) Search

GET https://api.sofarocean.com/api/search

Returns data from all accessible Spotters within the specified geospatial area during the specified time window.

{% 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`.

Examples

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

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

{
    "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
        }
    }
}

{% endtab %}

{% tab title="400 " %}

{ 
   status: 'error',
   message: 'Valid radius not found! A valid radius is required when shape is circle'
}

{% endtab %} {% endtabs %}