Description
Gets the most recent raw data from an instrument from a date, to a date, or raw data between two given dates.
If no time is specified, the last hour of data will be limited to the last hour of datareturned for getByStation, or the data will be from the beginning of time to the present, subject to (default or otherwise) row and size limits (for getByDevice and getByLocation).
If time is specified, the data is limited to 100,000 rows.
See the rawdata service for method, token, and responseType usage and error messages.
URL
...
http://data.oceannetworks.ca/api/rawdata
Method | Description | Example |
---|---|---|
getByStation* | Retrieve raw data available at given station. | method=getByStation |
getByDevice | Retrieve raw data available for a given device within a time range | method=getByDevice |
getByLocation | Retrieve raw data for the specified location and date range. This method is replacing getByStation. | method=getByLocation |
...
* getByStation is still available but is deprecated as of October 1, 2017. It has been replaced by the getByLocation method.
getByStation
Retrieve raw data available at Retrieve raw data available at given station. Data can be most recent from instruments, or data that's been archived in a raw data file.
...
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | string | user token | token=1234567890adbcde123 |
station | string | station code (corresponds with a search tree node, the one used in Data Search page) | station=IONA |
deviceCategory | string | used to select which category of instruments at the station to use. Corresponds with the name column in the device category table | deviceCategory=AISRECEIVER |
Optional | |||
dateFrom | string | ISO8601 (extended) Date for the start time of the data. If not given, defaults to one hour before current time, so that last hour of data is returned (if there is data in the last hour), up to rowLimit number of rows. | dateFrom=2012-01-02T00:12:42.000Z |
dateTo | string | ISO8601 (extended) Date for end time of data. Defaults to the current time if not provided. If no dateFrom is given and a dateTo is given, a date range error will be returned. The max amount of data returned will be rowLimit. | dateTo=2012-01-02T00:13:42.000Z |
rowLimit | integer | The maximum number of data to return, within the constraints of the service. Note this will limit the data starting at the start time and ending at the row limit, not necessarily at the end time. default row limit: 100000 Treat negative or 0 rowLimit as max rowLimit. Treat rowLimit > maxRowLimit as max row limit. | rowLimit=10 |
Response
Success
...
Sample <responseType> Response
|
...
|
...
|
...
|
...
|
Property | Type | Description | Example |
---|---|---|---|
data | array of objects | The array containing the requested data, including the sample time and the raw data for each reading time. | |
data.sampleTime | string | The sample time for a single reading time. ISO8601 Extended Format. | "2015-09-01T00:21:21.000Z" |
data.rawData | string | The string of raw data for the sampleTime | "\c:1441212680,C:776,s:P-Cumshewa*1E\!AIVDO,1,1,9,A,4030p;1uvA@kDnSi;fNJgk7008<8,0*47" |
metadata | object | The metadata for the query and data | |
metadata.queryMetadata | object | The metadata for the query | |
metadata.queryMetadata.stationCode | string | part of the query metadata. The station code (search tree node code) that was queried | "IONA" |
metadata.queryMetadata.deviceCategory | string | part of the query metadata. the device category requested. | "AISRECEIVER" |
metadata.queryMetadata.dateFrom | string | part of the query metadata. string string date used in the query for the start time of the data | "2015-09-01T00:21:21.000Z" |
metadata.queryMetadata.dateTo | string | part of the query metadata. string string ISO8601 date used in the query for the end time of the data. Can be null. | "2015-09-18T02:23:21.000Z" |
metadata.queryMetadata.rowLimit | integer | part of the query metadata. the the value given, if any, in the query limiting the size of the data | 100000 |
metadata.dataMetadata | object | The metadata for the data itself | |
metadata.dataMetadata.numberOfData | integer | part of the data metadata. the the number of rows of data returned in the query | 100000 |
metadata.dataMetadata.firstTimestamp | string | part of the data metadata. string ISO8601 representing the first timestamp returned | "2015-09-01T00:21:21.123Z" |
metadata.dataMetadata.lastTimestamp | string | part of the data metadata. string ISO8601 representing the last timestamp returned | "2015-09-01T03:22:18.908Z" |
metadata.dataMetadata.stationName | string | part of the data metadata. The name of the station (device) | "Iona Shore Station" |
metadata.dataMetadata.hasMoreDataInRange | boolean | part of the data metadata. Indicates Indicates whether all the data was returned with the query or whether more data is available in the requested range. | true |
Failure
...
Example
Get most recent hour of Get raw data from an AIS receiver at Iona Shore Station from the beginning of time to the present with the default 100,000-row limit:
...
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
getByDevice Method
Retrieve raw data for a given device. A date range is optional–when that is not specified, data from the last hour of data is returnedbeginning of time to the present will be returned within (possibly default) row and size limits. Older data is returned by specifying a dateFrom date and optionally an dateTo date.
...
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | String | User Token | token=1234567890adbcde123 |
deviceCode | String | The device code of the Device requested. | deviceCode=ASLZAP1006 |
Optional | |||
dateFrom | String | The start date inclusive for the data to be returned in ISO8601 Extended format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). if not specified then the start date is one hour agothe beginning of time. | dateFrom=2017-06-08T00:00:00.000Z |
dateTo | String | The end date exclusive for the data to be returned in ISO8601 Extended format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). If not specified the end date is now. The end date cannot be specified unless a dateFrom date is also specified. | dateTo=2017-06-08T01:00:00.000Z |
rowLimit | Integer | The limit on the number of raw data readings to return. If not specified the row limit is 100,000. | rowLimit=300 |
sizeLimit | Integer | The limit on the size of raw data readings to return specified in MB. If not specified the size limit is 250 MB. | sizeLimit=20 |
convertHexToDecimal | Boolean | Format of raw data readings. By default, binary data will be returned in decimal. When set to false, it will be returned in hexadecimal | convertHexToDecimal = false |
outputFormat | String | Array (default or if missing) (case insensitive) Object (case insensitive) | outputFormat = array outputFormat = object |
Response
Success
...
(outputFormat = Array)
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
Property | Type | Description | Example |
---|---|---|---|
data | Object | An object containing the raw data readings and time stamps | |
| Array of Strings | An array of lineTypes, one for each reading in the requested date range. LineTypes are ">" for CommandSent, " " for DataReceived, and "<" for CommandResponse. | [" ",">","<"," "," "," "," ",">"] |
| Array of Strings OR Array of Integer Arrays | An array of readings one for each reading in the requested date range. If the raw data is text then this is an array of strings. If the raw data is binary then each item in the array is an array of integers. If conversion is turned off, array of hexadecimal strings returned. | Text:
Binary:
Binary: (convertHexToDecimal = false)
|
| Array of Strings | An array of timestamps one for each reading in the requested date range. Each timestamp is a string in ISO8601 (extended) format, yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. | [ "2014-04-25T00:00:00.005Z" ] |
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. | |
| 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 plus dateFrom if dateFrom hadn't been specified. | "parameters": { "method": "getByDevice", "rowLimit": "1", |
| String | As passed into the original call | "ffffffff-ffff-ffff-ffff-ffffffffffff" |
| String | getByDevice, as passed into the original call. | "getByDevice" |
| String | As passed into the original call | "SBECTD19p7128" |
| String | This is set to 1 millisecond more than the date of the last reading sent in the current call. | "2014-04-25T00:00:00.006Z" |
| String | Any optional parameters passed into the original call. | "dateTo":"2014-04-25T00:00:00.001Z", "rowLimit":"5", "outputFormat": "objectarray" |
| String | The complete URL that can be used to get the next set of data in the requested range. | "https://data.oceannetworks.ca/api/rawdata?method=getByDevice&dateTo=2014-04-25T00%3A00%3A00.001Z&deviceCode=SBECTD16p6934&rowLimit=5&dateFrom=2014-04-24T23%3A51%3A00.003Z&token=ffffffff-ffff-ffff-ffff-ffffffffffff" |
queryUrl | String | The complete URL for the current call. | "https://data.oceannetworks.ca/api/rawdata?method=getByDevice&token=ffffffff-ffff-ffff-ffff-ffffffffffff&deviceCode=BARIX001&dateFrom=2017-06-08T00:00:00.000Z&dateTo=2017-06-08T00:00:00.010Z" |
Failure
See rawdata service
Example Service Call
Code Block | ||
---|---|---|
| ||
{
"data": {
"lineTypes": [
">",
"<",
">"
],
"readings": [
"version[0d]",
"version,BARIONET 1.2",
"getio,201[0d]"
],
"times": [
"2017-06-08T00:00:00.003Z",
"2017-06-08T00:00:00.008Z",
"2017-06-08T00:00:00.009Z"
]
},
"next": null,
"queryUrl": "https://data.oceannetworks.ca/api/rawdata?method=getByDevice&token=ffffffff-ffff-ffff-ffff-ffffffffffff&deviceCode=BARIX001&dateFrom=2017-06-08T00:00:00.000Z&dateTo=2017-06-08T00:00:00.010Z"
} |
Example Service Call with outputFormat parameter
Code Block | ||
---|---|---|
| ||
{
"data":[
{
"lineType":">",
"rawData":"version[0d]",
"sampleTime":"2017-06-08T00:00:00.001Z"
},
{
"lineType":"<",
"rawData":"version,BARIONET 1.2 Simulator",
"sampleTime":"2017-06-08T00:00:00.002Z"
},
{
"lineType":">",
"rawData":"getio,201[0d]",
"sampleTime":"2017-06-08T00:00:00.003Z"
}
],
"next":null,
"queryUrl":"https://data.oceannetworks.ca/api/rawdata?method=getByDevice&token=ffffffff-ffff-ffff-ffff-ffffffffffff&deviceCode=BARIX001&dateFrom=2017-06-08T00:00:00.000Z&dateTo=2017-06-08T00:00:00.004Z&outputFormat=object"
} |
...
Retrieve the raw data at a given location for the given device category. A date range is optional, when not specified the last hour of data is returned. Older data is returned by specifying a dateFrom date and optionally an dateTo date.
Parameters
...
The end date exclusive for the data to be returned in ISO8601 Extended format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). If not specified the end date is now. The end date cannot be specified unless a dateFrom date is also specified.
...
Array (default or if missing) (case insensitive)
data will be output as three arrays for a given device. Array of lineTypes, array of readings, array of times
Object (case insensitive)
data will be output as a list of objects for a given device. Inside each data object, there are lineType, rawData, and sampleTime.
Can be used if the user wants data object to have the same output format of getByStation method.
...
outputFormat= array
outputFormat = object
Success (outputFormat = Object)
|
Property | Type | Description | Example |
---|---|---|---|
data | Array of Objects | An array containing the raw data readings and time stamps | |
| Strings | A lineType. LineTypes are ">" for CommandSent, " " for DataReceived, and "<" for CommandResponse. | ">" |
| String OR Integer Array | A single raw data reading. If the raw data is text then this is a string. If the raw data is binary then this is an array of integers. If conversion is turned off, a hexadecimal string is returned. | Text:
Binary:
Binary: (convertHexToDecimal = false)
|
| String | A timestamp. Each timestamp is a string in ISO8601 (extended) format, yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. | "2014-04-25T00:00:00.005Z" |
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. | |
| 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 plus dateFrom if dateFrom hadn't been specified. | "parameters": { "method": "getByDevice", "rowLimit": "1", |
| String | As passed into the original call | "ffffffff-ffff-ffff-ffff-ffffffffffff" |
| String | getByDevice, as passed into the original call. | "getByDevice" |
| String | As passed into the original call | "SBECTD19p7128" |
| String | This is set to 1 millisecond more than the date of the last reading sent in the current call. | "2014-04-25T00:00:00.006Z" |
| String | Any optional parameters passed into the original call. | "dateTo":"2014-04-25T00:00:00.001Z", "rowLimit":"5", "outputFormat": "object" |
| String | The complete URL that can be used to get the next set of data in the requested range. | "https://data.oceannetworks.ca/api/rawdata?method=getByDevice&dateTo=2014-04-25T00%3A00%3A00.001Z&deviceCode=SBECTD16p6934&rowLimit=5&dateFrom=2014-04-24T23%3A51%3A00.003Z&token=ffffffff-ffff-ffff-ffff-ffffffffffff" |
queryUrl | String | The complete URL for the current call. | "https://data.oceannetworks.ca/api/rawdata?method=getByDevice&token=ffffffff-ffff-ffff-ffff-ffffffffffff&deviceCode=BARIX001&dateFrom=2017-06-08T00:00:00.000Z&dateTo=2017-06-08T00:00:00.010Z" |
Example Service Call
|
Example Service Call with outputFormat parameter
|
getByLocation
Retrieve the raw data at a given location for the given device category. A date range is optional–when not specified, data from the beginning of time to the present will be returned within (possibly default) row and size limits. Older data is returned by specifying a dateFrom date and optionally an dateTo date.
Parameters
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | String | All Web Services require a token. This can be generated at http://data.oceannetworks.ca/Profile. Click on the "Web Services" tab and click "Generate Token" | token=1234567890adbcde123 |
locationCode | String | Specify the location of the data to be retrieved. This is a location code as returned by the locations service get method. A location must have device data associated with it to be valid. | locationCode=SCVIP |
deviceCategoryCode | String | Specify the type of device generating the data to be retrieved. This is a device category code as returned by the deviceCategories service get method. There must be a device with device category code at the specified location for the deviceCategoryCode to be valid. | deviceCategoryCode=CTD |
Optional | |||
dateFrom | String | The start date inclusive for the data to be returned in ISO8601 Extended format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). if not specified then the start date is the beginning of time. | dateFrom=2017-06-08T00:00:00.000Z |
dateTo | String | The end date exclusive for the data to be returned in ISO8601 Extended format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). If not specified the end date is now. | dateTo=2017-06-08T01:00:00.000Z |
rowLimit | Integer | The limit on the number of raw data readings to return. If not specified the row limit is 100,000. | rowLimit=300 |
sizeLimit | Integer | The limit on the size of raw data readings to return specified in MB. If not specified the size limit is 250 MB. | sizeLimit=20 |
outputFormat | String | Array (default or if missing) (case insensitive) Object (case insensitive) | outputFormat= array outputFormat = object |
Response
Success (outputFormat = Array)
|
Property | Type | Description | Example |
---|---|---|---|
data | Object | An object containing the raw data readings and time stamps | |
| Array of Strings | An array of lineTypes, one for each reading in the requested date range. LineTypes are ">" for CommandSent, " " for DataReceived, and "<" for CommandResponse. | [" "," "," "," "," "," "," "," "] |
| Array of Strings OR Array of Integer Arrays | An array of readings one for each reading in the requested date range. If the raw data is text then this is an array of strings. If the raw data is binary then each item in the array is an array of integers. | Text:
Binary:
|
| Array of Strings | An array of timestamps one for each reading in the requested date range. Each timestamp is a string in ISO8601 (extended) format, yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. | [ "2014-04-25T00:00:00.005Z" ] |
metadata | Object | An object containing metadata items. | |
| String | The name of the location for the requested location code. | "Strait of Georgia VENUS Instrument Platform" |
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. | |
| 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 plus dateFrom if dateFrom hadn't been specified. | "parameters": {
"method": "getByLocation",
"rowLimit": "1",
"locationCode": "SCVIP",
"deviceCategoryCode": "CURRENTMETER",
"dateFrom": "2014-04-25T00:00:00.006Z",
"token": "ffffffff-ffff-ffff-ffff-ffffffffffff"
}, |
| String | As passed into the original call | "ffffffff-ffff-ffff-ffff-ffffffffffff" |
| String | getByLocation, as passed into the original call. | "getByLocation" |
| String | As passed into the original call | "SCVIP" |
| String | As passed into the original call | "CURRENTMETER" |
| String | This is set to 1 millisecond more than the date of the last reading returned in the current call. | "2014-04-25T00:00:00.006Z" |
| String | Any optional parameters passed into the original call. | "dateTo":"2009-08-15T17:50:00.000Z", "rowLimit": "1", "outputFormat": "object" |
| String | The complete URL that can be used to get the next set of data in the requested range. | https://data.oceannetworks.ca/api/rawdata? |
queryUrl | String | The complete URL for the current call. | "https://data.oceannetworks.ca/api/rawdata?method=getByLocation&locationCode=NCBC&deviceCategoryCode=BPR&dateFrom=2009-07-24T17:50:00.000Z&rowLimit=5&token=ffffffff-ffff-ffff-ffff-ffffffffffff" |
Success (outputFormat = Object)
|
Response
Success
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
Property | Type | Description | Example | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
data | ObjectArray of Objects | An | objectarray containing the raw data readings and time stamps | ||||||||
| lineTypes
| Array of Strings | String | A lineType | An array of lineTypes, one for each reading in the requested date range. LineTypes are ">" for CommandSent, " " for DataReceived, and "<" for CommandResponse. | [" "," "," "," "," "," "," "," "]">" | |||||
| readings
| Array of Strings String OR | Integer Array | of Integer ArraysAn array of readings one for each reading in the requested date rangeA single raw data reading. If the raw data is text then this is | an array of stringsa string. If the raw data is binary then | each item in the array this is an array of integers. If conversion is turned off, a hexadecimal string is returned. | Text: | [
| ]Binary:
| [ -91, 16, 0, 123, 4, 0 ] ]
Binary: (convertHexToDecimal = false)
| |
| String | A timestamp |
| Array of Strings | An array of timestamps one for each reading in the requested date range. Each timestamp is a string in ISO8601 (extended) format, yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. | ["2014-04-25T00:00:00.005Z" | ]|||||
metadata | Object | An object containing metadata items. | |||||||||
| String | The name of the location for the requested location code. | "Strait of Georgia VENUS Instrument Platform" | ||||||||
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. | |||||||||
| 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 plus dateFrom if dateFrom hadn't been specified. | "parameters": { "method": "getByLocation", "rowLimit": "1", "locationCode": "SCVIP", "deviceCategoryCode": "CURRENTMETER", "dateFrom": "2014-04-25T00:00:00.006Z", "token": "ffffffff-ffff-ffff-ffff-ffffffffffff" }, | ||||||||
| String | As passed into the original call | "ffffffff-ffff-ffff-ffff-ffffffffffff" | ||||||||
| String | getByLocation, as passed into the original call. | "getByLocation" | ||||||||
| String | As passed into the original call | "SCVIP" | ||||||||
| String | As passed into the original call | "CURRENTMETER" | ||||||||
| String | This is set to 1 millisecond more than the date of the last reading returned in the current call. | "2014-04-25T00:00:00.006Z" | ||||||||
| String | Any optional parameters passed into the original call. | "dateTo":"2009-08-15T17:50:00.000Z", "rowLimit": "1", "outputFormat": "object" | ||||||||
| String | The complete URL that can be used to get the next set of data in the requested range. | https://data.oceannetworks.ca/api/rawdata? | ||||||||
queryUrl | String | The complete URL for the current call. | "https://data.oceannetworks.ca/api/rawdata?method=getByLocation&locationCode=NCBC&deviceCategoryCode=BPR&dateFrom=2009-07-24T17:50:00.000Z&rowLimit=5&token=ffffffff-ffff-ffff-ffff-ffffffffffff" |
...
See rawdata service
Examples
Get 5 raw data readings for BPR data from Barkley Canyon Upper Slope (NCBC):
http://data.oceannetworks.ca/api/rawdata?method=getByLocation&locationCode=NCBC&deviceCategoryCode=BPR&dateFrom=2017-07-24T17:50:00.000Z&rowLimit=5&token=c9ed940dffffffff-1c48ffff-49caffff-9bbdffff-1b126cb50917ffffffffffff
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
...
...
...
...
...
|
...
...
...
...
...
...
...
|
...
Get 1 raw data reading for Current Meter (CURRENTMETER) data from Strait of Georgia VENUS Instrument Platform (SCVIP):
http://data.oceannetworks.ca/api/rawdata?method=getByLocation&locationCode=SCVIP&deviceCategoryCode=CURRENTMETER&token=c9ed940dffffffff-1c48ffff-49caffff-9bbdffff-1b126cb50917ffffffffffff&dateFrom=2014-04-25T00:00:00.000Z&rowLimit=1
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
...
...
...
...
...
|
...
...
...
...
...
...
...
|