scalardata service

Description

API scalardata allows users to get scalar data.

URL

http://data.oceannetworks.ca/api/scalardata

Method	Description	Example
getByLocation	Returns scalar data by given location code and device category	method=getByLocation

* getByStation was deprecated as of October 1, 2017 (see bottom of this page for documentation). It has been replaced by the getByLocation method.

getByLocation

Returns scalar data in JSON format by given location code and device category code.

Parameters

Parameter	Type	Description	Example
Required
token	string	credential token in GUID format	ffffffff-ffff-ffff-ffff-ffffffffffff
locationCode	string	the code of a location	KVIP.C2
deviceCategoryCode	string	the code of a device category	BPR
Optional
propertyCode	String	the code of a property	seawatertemperature
sensorCategoryCodes	String	A comma separated list of sensor code name. If missing, the system will return all search scalar data within the location code, device category pair, and propertyCode (if given).	pressure,borehole_pressure1,oxygen
dateFrom	date	inclusive start date in "yyyy-MM-ddTHH:mm:ss.SSSZ" format. If missing, the system will return last reading.	2015-05-25T00:00:00.000Z
dateTo	date	exclusive end date in "yyyy-MM-ddTHH:mm:ss.SSSZ" format. If missing the system will use 1 day range.	2015-05-26T20:01:23.456Z
metadata	String	Minimum (default or if missing) (case insensitive) provides only basic property information Full (case insensitive) provides all property information metadata is for the latest deployment overlapping dateFrom and dateTo or, if no dates specified, the latest deployment overall	Minimum
rowLimit	integer	maximum row scalar data returns for each sensor code. For those data they are sorted by sample time. If missing or invalid number, the maximum 100,000 will be used. If given number is over 100,000, the maximum 100,000 will be used.	80000
outputFormat	String	Array (default or if missing) (case insensitive) data will be out put as three arrays for a given sensor. Array of sampleTime, array of values, array of qaqcFlags Object(case insensitive) data will be output as a list of objects for a given sensor. Inside each data object, there are sampleTime, value, and qaqcFlag	Object
getLatest	Boolean	Whether the latest raw data readings should be returned first. This is false by default. When set to true, readings are returned and pagination is done from latest to earliest	true

Response

Success

{
	"metadata": {
		"boundingBox": {
			"maxDepth":<Double>,
			"maxLat":<Double>,
			"maxLon":<Double>,
			"minDepth":<Double>,
			"minLat":<Double>,
			"minLon":<Double>
		},
		"depth":<Double>,
		"deviceCategoryCode":<String>,
		"lat":<Double>,
		"locationName":<String>,
		"lon":<Double>
	},
	"next": {
		"parameters": {
			"metadata":<String>,
			"method":"getByLocation",
			"dateTo":<String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')>,
			"rowLimit":<String>,
			"locationCode":<String>,
			"deviceCategoryCode":<String>,
			"sensorCategoryCodes":<String>,
		 	"dateFrom":<String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')>,
			"outputFormat" : <String>,
            "token":<String (GUID)>
		},
		"url": <String (URL)>
	},
	"queryUrl": <String (URL)>,
	"sensorData": [
		{
			"data": {
				"qaqcFlags": <Array of integers>,
				"sampleTimes": <Array of String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')>,
				"values": <Array of doubles>
			},
			"sensorCode":<String>,
			"sensorName":<String>,
			"unitOfMeasure":<String>
		},
		...
	]
}

Property	Type	Description	Example
next	Object	An object containing information on how to make a rawdata call if the current call was unable to return all the data as a limit was exceeded. This is null if there is no more data in the requested range.
next.parameters	Object	An object containing the set of parameters making up the query to get the next set of data in the requested date range. The parameters will include all parameters passed into the original URL.
next.parameters.metadata	String	As passed into the original call	"minimum"
next.parameters.method	String	getByLocation, as passed into the original call.	"getByLocation"
next.parameters.dateTo	String	As passed into the original call	"2015-02-25T00:00:01.000Z"
next.parameters.rowLimit	String	As passed into the original call	"10"
next.parameters.locationCode	String	As passed into the original call	"NC27"
next.parameters.deviceCategoryCode	String	As passed into the original call	"CORK"
next.parameters.sensorCategoryCodes	String	As passed into the original call	"pressure"
next.parameters.dateFrom	String	This is set to 1 millisecond more than the date of the last reading sent in the current call.	"2015-02-25T00:00:01.189Z"
next.parameters.outputFormat	String	As passed into the original call	"object"
next.parameters.token	String	As passed into the original call	"ffffffff-ffff-ffff-ffff-ffffffffffff"
next.url	String	The complete URL that can be used to get the next set of data in the requested range.	"https://data.oceannetworks.ca/api/scalardata?method=getByLocation&dateTo=2015-02-25T00%3A00%3A01.000Z&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00%3A00%3A01.189Z&token=ffffffff-ffff-ffff-ffff-ffffffffffff"
queryUrl	String	URL of current query	"https://data.oceannetworks.ca/api/scalardata?method=getByLocation&dateTo=2015-02-25T00%3A00%3A01.000Z&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00%3A00%3A00.000Z&token=ffffffff-ffff-ffff-ffff-ffffffffffff"
sensorData	Array of objects	Data sets returned for all applicable sensors
sensorData.data	Object	Data sets returned for a single sensor
sensorData.data.qaqcFlags	Array of integers	QAQC test results of each data point–guidelines for what each number means: 0 No quality control on data 1 Data passed all tests 2 Data probably good 3 Data probably bad. Failed minor tests 4 Data bad. Failed major tests 7 Averaged value 8 Interpolated value 9 Missing data	[1]
sensorData.data.sampleTimes	Array of strings	Sampling times of sensor data returned, formatted as yyyy-MM-dd'T'HH:mm:ss.SSS'Z'	["2015-02-25T00:00:00.188Z"]
sensorData.data.values	Array of doubles	Values of sensor data returned, units of measurement are given in sensorData.unitOfMeasure	[2706.1145305467917]
sensorData.sensorCode	String	Code of sensor, can be null	"sigmaT"
sensorData.sensorName	String	Name that denotes what the sensor measures	"Uncompensated Borehole Pressure"
sensorData.unitOfMeasure	String	Unit of measurement or "NA" if none apply; temperature units of measure are "C" for degrees Celsius	"Gregorian days since 19700101T000000Z"
metadata	Object	Optional; only returned if the metadata parameter is set to full
metadata.boundingBox	Object	Bounding limits statistics
metadata.boundingBox.maxDepth	Double	Maximum depth in meters below water surface (negative numbers denote above)	982.0
metadata.boundingBox.maxLat	Double	Maximum latitude in degrees north of the equator (negative numbers denote south)	48.316583
metadata.boundingBox.maxLon	Double	Maximum longitude in degrees east of the prime meridian (negative numbers denote west)	-126.050796
metadata.boundingBox.minDepth	Double	Minimum depth in meters below water surface (negative numbers denote above)	982.0
metadata.boundingBox.minLat	Double	Minimum latitude in degrees north of the equator (negative numbers denote south)	48.316583
metadata.boundingBox.minLon	Double	Minimum longitude in degrees east of the prime meridian (negative numbers denote west)	-126.050796
metadata.depth	Double	Depth in meters below water surface (negative numbers denote above)	2660.5
metadata.deviceCategoryCode	String	Should be the same as next.parameters.deviceCategoryCode	"CORK"
metadata.lat	Double	Latitude in degrees north of the equator (negative numbers denote south)	47.7626
metadata.locationName	String	Name of location	"ODP 1026"
metadata.lon	Double	Longitude in degrees east of the prime meridian (negative numbers denote west)	-127.759212

Note: Not all the properties above may be included in the resulting JSON, especially parameters that were not in the original call.

Example

https://data.oceannetworks.ca/api/scalardata?method=getByLocation&token=ffffffffffffffff&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00:00:00.000Z&dateTo=2015-02-25T00:00:01.000Z&propertyCode=totalpressure&sensorCategoryCodes=pressure

{ 
   "next":{ 
      "parameters":{ 
         "propertyCode":"totalpressure",
         "method":"getByLocation",
         "sensorCategoryCodes":"pressure,borehole_pressure1",
         "dateTo":"2015-02-25T00:00:01.000Z",
         "locationCode":"NC27",
         "deviceCategoryCode":"CORK",
         "dateFrom":"2015-02-25T00:00:01.189Z",
         "token":"c9ed940d-1c48-49ca-9bbd-1b126cb50917"
      },
      "url":"https://data.oceannetworks.ca/api/scalardata?propertyCode=totalpressure&sensorCategoryCodes=pressure,borehole_pressure1&method=getByLocation&dateTo=2015-02-25T00%3A00%3A01.000Z&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00%3A00%3A01.189Z&token=fffffffffffff"
   },
   "queryUrl":"https://data.oceannetworks.ca/api/scalardata?method=getByLocation&token=fffffffffffff&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00:00:00.000Z&dateTo=2015-02-25T00:00:01.000Z&propertyCode=totalpressure&sensorCategoryCodes=pressure,borehole_pressure1",
   "sensorData":[ 
      { 
         "data":{ 
            "qaqcFlags":[ 
               1
            ],
            "sampleTimes":[ 
               "2015-02-25T00:00:00.188Z"
            ],
            "values":[ 
               2706.1145305467917
            ]
         },
         "sensorCode":"Pressure",
         "sensorName":"Uncompensated Seafloor Pressure",
         "unitOfMeasure":"decibar"
      },
      { 
         "data":{ 
            "qaqcFlags":[ 
               1
            ],
            "sampleTimes":[ 
               "2015-02-25T00:00:00.188Z"
            ],
            "values":[ 
               2705.9145624950315
            ]
         },
         "sensorCode":"borehole_pressure1",
         "sensorName":"Uncompensated Borehole Pressure",
         "unitOfMeasure":"decibar"
      }
   ]
}

Example with outputFormat option

https://data.oceannetworks.ca/api/scalardata?method=getByLocation&token=ffffffffffffff&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00:00:00.000Z&dateTo=2015-02-25T00:00:01.000Z&propertyCode=totalpressure

{  
   "next":{  
      "parameters":{  
         "propertyCode":"totalpressure",
         "method":"getByLocation",
         "dateTo":"2015-02-25T00:00:01.000Z",
         "locationCode":"NC27",
         "deviceCategoryCode":"CORK",
         "dateFrom":"2015-02-25T00:00:01.189Z",
         "outputFormat":"object",
         "token":"c9ed940d-1c48-49ca-9bbd-1b126cb50917"
      },
      "url":"https://data.oceannetworks.ca/api/scalardata?propertyCode=totalpressure&method=getByLocation&dateTo=2015-02-25T00%3A00%3A01.000Z&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00%3A00%3A01.189Z&outputFormat=object&token=fffffffffffff"
   },
   "queryUrl":"https://data.oceannetworks.ca/api/scalardata?method=getByLocation&token=fffffffffffff&locationCode=NC27&deviceCategoryCode=CORK&dateFrom=2015-02-25T00:00:00.000Z&dateTo=2015-02-25T00:00:01.000Z&propertyCode=totalpressure&outputFormat=object",
   "sensorData":[  
      {  
         "data":[  
            {  
               "qaqcFlag":1,
               "sampleTime":"2015-02-25T00:00:00.188Z",
               "value":2706.1145305467917
            }
         ],
         "sensorCode":"Pressure",
         "sensorName":"Uncompensated Seafloor Pressure",
         "unitOfMeasure":"decibar"
      },
      {  
         "data":[  
            {  
               "qaqcFlag":1,
               "sampleTime":"2015-02-25T00:00:00.188Z",
               "value":2705.9145624950315
            }
         ],
         "sensorCode":"borehole_pressure1",
         "sensorName":"Uncompensated Borehole Pressure",
         "unitOfMeasure":"decibar"
      }
   ]
}

getByStation (no longer available - deprecated)

Returns scalar data in JSON format by given station code and device category code.

Parameters

Parameter	Type	Description	Example
Required
token	string	credential token in GUID format	ffffffff-ffff-ffff-ffff-ffffffffffff
station	string	the code of a station	NCBC
deviceCategory	string	the code of a device category	BPR
Optional
sensors	string	a comma separated list of sensor code name. If missing, the system will return all search scalar data within the station code and device category pair.	pressure,temperature
dateFrom	date	inclusive start date in "yyyy-MM-ddTHH:mm:ss.SSSZ" format. If missing, the system will return last reading.	2015-05-25T00:00:00.000Z
dateTo	date	exclusive end date in "yyyy-MM-ddTHH:mm:ss.SSSZ" format. If missing, the system will use a 24-hour range.	2015-05-26T00:00:00.000Z
metadata	String	Minimum (default or if missing) (case insensitive) provides only basic property information Full (case insensitive) provides all property information metadata is for the latest deployment overlapping dateFrom and dateTo or, if no dates specified, the latest deployment overall	Minimum
outputFormat	String	Object (default or if missing) (case insensitive) data will be output as a list of objects for a given sensor. Inside each data object, there are sampleTime, value, and qaqcFlag Array (case insensitive) data will be out put as three arrays for a given sensor. Array of sampleTime, array of values, array of qaqcFlags	Object
rowLimit	integer	maximum row scalar data returns for each sensor code. For those data they are sorted by sample time. If missing or invalid number, the maximum 100,000 will be used. If given number is over 100,000, the maximum 100,000 will be used.	80000

Response

Success

Sample <responseType> Response

{
    "metadata": {
        "bbox": {
			"maxDepth": double,
			"maxLat": double,
			"maxLon": double,
			"minDepth": double,
			"minLat": double,
			"minLon": double
		},
        "dateFrom": string,
        "dateTo": string,
        "depth": double,
        "deviceCategoryName": string,
        "latitude": double,
        "longitude": double,
        "stationName": string
	},
	"sensorData": [
		{
			"actualSamples": integer,
			"data": [//outputFormat=object
				{
					"sampleTime": string,
					"value": double,
	   				"qaqcFlag": integer
	 			},
				...
			],
			"data": [//outputFormat=array
				{
					"sampleTimes": [array of strings],
					"values": [array of doubles],
	   				"qaqcFlags": [array of integers]
	 			},
				...
			],
			"sensor": string,
            "sensorName": string,
            "unitOfMeasure": string
		},
		...
	],
	"serviceMetadata": {
		"dateFrom": string,
        "dateTo": string,
        "deviceCategory": string,
        "metadata": string,
		"nextDateFrom": string,
		"outputFormat": string,
        "rowLimit": string,
		"sensors": string,
    	"station": string,
		"totalActualSamples": integer
	}
}

Property	Type	Description	Option
serviceMetadata	json object	meta data information of the web service request.	metadata=minimum
serviceMetadata.station	string	requested station code	metadata=minimum
serviceMetadata.deviceCategory	string	requested device category code	metadata=minimum
serviceMetadata.sensors	string	CSV searchable sensor code names	metadata=minimum
serviceMetadata.dateFrom	string	requested date from in yyyy-MM-ddTHH:mm:ss.SSSZ format	metadata=minimum
serviceMetadata.dateTo	string	requested date to in yyyy-MM-ddTHH:mm:ss.SSSZ format	metadata=minimum
serviceMetadata.metadata	string	requested metadata option	metadata=minimum
serviceMetadata.rowLimit	integer	requested row limit per sensor code name	metadata=minimum
serviceMetadata.outputFormat	string	the requested data output format	metadata=minimum
serviceMetadata.totalActualSamples	integer	how many scalar data expected in total for all the sensors	metadata=minimum
serviceMetadata.nextDateFrom	string	the date from for next reading in yyyy-MM-ddTHH:mm:ss.SSSZ format	metadata=minimum
metadata	json object	metadata station and device information	metadata=full
metadata.stationName	string	station name for the given station code	metadata=full
metadata.deviceCategoryName	string	device category name for the given category code	metadata=full
metadata.dateFrom	string	the date from for a given deployment in yyyy-MM-ddTHH:mm:ss.SSSZ format	metadata=full
metadata.dateTo	string	the date to for a given deployment in yyyy-MM-ddTHH:mm:ss.SSSZ format	metadata=full
metadata.longitude	double	the aggregate (mean) longitude of the station.	metadata=full
metadata.latitude	double	the aggregate (mean) latitude of the station.	metadata=full
metadata.depth	double	the aggregate (mean) depth of the station.	metadata=full
metadata.bbox	json object	the boundary of the station box	metadata=full
metadata.bbox.minLon	double	the minimum longitude of the station.	metadata=full
metadata.bbox.maxLon	double	the maximum longitude of the station.	metadata=full
metadata.bbox.minLat	double	the minimum latitude of the station.	metadata=full
metadata.bbox.maxLat	double	the maximum latitude of the station.	metadata=full
metadata.bbox.minDepth	double	the minimum depth of the station.	metadata=full
metadata.bbox.maxDepth	double	the maximum depth of the station.	metadata=full
sensorData	array	all available scalar data for given time range within the row limit	metadata=minimum
sensorData.sensor	string	sensor code name for a given sensor	metadata=minimum
sensorData.sensorName	string	sensor full name for a given sensor	metadata=minimum
sensorData.unitOfMeasure	string	unit of measure name for the scalar reading	metadata=minimum
sensorData.actualSamples	integer	number of samples for that sensorData	metadata=minimum
sensorData.data	array	sensor data for a given sensor	outputFormat=object
sensorData.data.sampleTime	string	time stamp of the reading in yyyy-MM-ddTHH:mm:ss.SSSZ format	outputFormat=object
sensorData.data.value	double	scalar reading after calibration, derivation and unit conversion	outputFormat=object
sensordata.data.qaqcFlag	integer	QAQC flag	outputFormat=object
sensorData.data	json object	sensor data for a given sensor	outputFormat=array
sensorData.data.sampleTimes	array	an array of time stamp of the reading in yyyy-MM-ddTHH:mm:ss.SSSZ format	outputFormat=array
sensorData.data.values	array	an array of scalar reading after calibration, derivation and unit conversion	outputFormat=array
sensorData.data.qaqcFlags	array	an array of QAQC flags	outputFormat=array

Note: If the value is null, this may be displayed in the resulting JSON as a null.

Example

https://data.oceannetworks.ca/api/scalardata?method=getByStation&token=ffffffff-ffff-ffff-ffff-ffffffffffff&station=SCHDW.O1&deviceCategory=OXYSENSOR

{
	"sensorData": [{
		"actualSamples": 1,
		"data": [{
			"qaqcFlag": 0,
			"sampleTime": "2015-08-20T17:30:53.058Z",
			"value": 23.4859
		}],
		"sensor": "Temperature",
		"sensorName": "Temperature",
		"unitOfMeasure": "C"
	}, {
		"actualSamples": 1,
		"data": [{
			"qaqcFlag": 1,
			"sampleTime": "2015-08-20T17:30:53.058Z",
			"value": 4.417862252
		}],
		"sensor": "oxygen",
		"sensorName": "Oxygen",
		"unitOfMeasure": "ml/l"
	}],
	"serviceMetadata": {
		"dateFrom": null,
		"dateTo": null,
		"deviceCategory": "OXYSENSOR",
		"nextDateFrom": null,
		"outputFormat": null,
		"rowLimit": null,
		"sensors": null,
		"station": "SCHDW.O1",
		"totalActualSamples": 2
	}
}

Page tree

scalardata service

Description

URL

getByLocation

Parameters

Response

Success

Example

Example with outputFormat option

getByStation (no longer available - deprecated)

Parameters

Response

Success

Example