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

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.

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" %} Results:

{% code expandable="true" %}

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

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

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

Improper shapeParams:

{
    "status": "error",
    "message": "Improper amount of lat/lon pairs! There must be exactly 1 pair(s)"
}

Missing startDate :

{
    "status": "error",
    "message": "Invalid parameter startDate. Date value must be provided in ISO 8601 format"
}

{% endtab %}

{% tab title="401" %} Incorrect token:

{
    "message": "Authentication Failed"
}

Missing token:

{
    "message": "No token provided"
}

{% endtab %} {% endtabs %}