(GET) Search

Retrieve data from Spotters within an area for a specified time window.

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.

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

200

Results:

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

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

400

401