Versions Compared

Old Version 22

changes.mady.by.user Timothy Choo

Saved on

compared with

New Version 23

changes.mady.by.user Yingsong Zheng

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

Method

Description

Example

getByStation51085963*Retrieve raw data available at given station.method=getByStation
getByDevice51085963Retrieve raw data available for a given device within a time rangemethod=getByDevice
getByLocation51085963Retrieve raw data for the specified location and date range. This method is replacing getByStation.method=getByLocation

...

Expand
titleDeprecated. Click here to expand...

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.

Parameters

ParameterTypeDescriptionExample
Required
tokenstringuser tokentoken=YOUR_TOKEN_HERE
stationstringstation code (corresponds with a search tree node, the one used in Data Search page) station=IONA
deviceCategorystringused to select which category of instruments at the station to use. Corresponds with the name column in the device category tabledeviceCategory=AISRECEIVER
Optional
dateFromstringISO8601 (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
dateTostring

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 
rowLimitinteger

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.maxRowLimit as max row limit.

rowLimit=10
skipErrorsBoolean

skipErrors=true will return all raw data with timestamps

skipErrors=false (default) will return error message when there are some badly formatted raw data within requested time range

Example of error message in the return

{

"errors": [

{

"errorCode": 143,

"errorMessage": "Badly formatted raw data could not be returned. Recommend use 'skipErrors=true' option to skip errors and return remaining data. Alternatively, use archivefile service to download raw data."

}

]

}

rowLimit=10

Response

Success


Sample <responseType> Response

{  
    "data" : [
              {
                "rawData": <string>,
                "sampleTime": <string>
              },
                ...
    ],
    "metadata": {
        "queryMetadata": {
            "stationCode" : <string>,
            "dateFrom"            : <string>,
            "dateTo"          : <string>,
            "deviceCategory"  : <string>,
            "rowLimit"            : <integer>
        }
        "dataMetadata": {
            "numberOfData"    : <integer>,
            "firstTimestamp"  : <string>,
            "lastTimestamp"       : <string>,
            "stationName"     : <string>,
            "hasMoreDataInRange": <boolean>
        }
    }
}



Property

Type

Description

Example

dataarray of objectsThe array containing the requested data, including the sample time and the raw data for each reading time.

data.sampleTimestringThe sample time for a single reading time. ISO8601 Extended Format.
"2015-09-01T00:21:21.000Z"
data.rawDatastringThe 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"
metadataobjectThe metadata for the query and data 
metadata.queryMetadataobjectThe metadata for the query
metadata.queryMetadata.stationCodestring

part of the query metadata. The station code (search tree node code) that was queried

"IONA"
metadata.queryMetadata.deviceCategorystringpart of the query metadata. the device category requested.
"AISRECEIVER"
metadata.queryMetadata.dateFromstringpart of the query metadata. string date used in the query for the start time of the data
"2015-09-01T00:21:21.000Z"
metadata.queryMetadata.dateTostringpart of the query metadata. 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.rowLimitintegerpart of the query metadata. the value given, if any, in the query limiting the size of the data
100000
metadata.dataMetadataobjectThe metadata for the data itself
metadata.dataMetadata.numberOfDataintegerpart of the data metadata. the number of rows of data returned in the query
100000
metadata.dataMetadata.firstTimestampstringpart of the data metadata. string ISO8601 representing the first timestamp returned
"2015-09-01T00:21:21.123Z"
metadata.dataMetadata.lastTimestampstringpart of the data metadata. string ISO8601 representing the last timestamp returned
"2015-09-01T03:22:18.908Z"
metadata.dataMetadata.stationNamestringpart of the data metadata. The name of the station (device)
"Iona Shore Station"
metadata.dataMetadata.hasMoreDataInRangebooleanpart of the data metadata. Indicates whether all the data was returned with the query or whether more data is available in the requested range.
true

Example

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:

http://data.oceannetworks.ca/api/rawdata?method=getByStation&deviceCategory=AISRECEIVER&station=IONA&token=YOUR_TOKEN_HERE

Get data from AIS receiver at Iona Shore Station starting from September 1, 2015, at 21 minutes and 21 seconds after midnight:

 http://data.oceannetworks.ca/api/rawdata?token=YOUR_TOKEN_HERE&method=getByStation&station=IONA&deviceCategory=AISRECEIVER&dateFrom=2015-09-01T00:21:21.000Z


{"data":
     [
      {
       "rawData":"\\c:1441061153,C:1990,s:P-Parke*58\\!AIVDM,2,1,8,B,55NP0eP26m;5L@O?CC0Lu8@tr0`Dq<Dr2222220N9@J885Kd0?4i@E531H88,0*79",
       "sampleTime":"2015-09-01T00:21:21.123Z"
       },
      {
        "rawData":"\\c:1441061153,C:1990,s:P-Parke*58\\!AIVDM,2,2,8,B,88888888880,2*2F",
        "sampleTime":"2015-09-01T00:21:21.250Z"
       },
       {
          "rawData":"\\c:1441061153,C:1992,s:P-Helmcken*38\\!AIVDM,1,1,,B,15N;600P1Do>6CjKe>iG8Owb26jl,0*57",
          "sampleTime":"2015-09-01T00:21:21.352Z"},
       ...
     }],
    "metadata":
          {"dataMetadata": {
                  "firstTimestamp":"2015-09-01T00:21:21.123Z",
                  "hasMoreDataInRange":false,
                  "lastTimestamp":"2015-09-01T01:02:08.013Z",
                  "numberOfData":100000,
                  "stationName":"Iona Shore Station"
                 },
          "queryMetadata":{
                 "deviceCategory":"AISRECEIVER",
                 "dateTo":null,
                 "rowLimit":null,
                 "dateFrom":"2015-09-01T00:21:21.000Z",
                 "stationCode":"IONA"
          }
     }
}


...

ParameterTypeDescriptionExample
Required
tokenStringAll Web Services require a token. This can be generated at https://data.oceannetworks.ca/Profile. Click on the "Web Services" tab and click "Generate Token".token=YOUR_TOKEN_HERE
deviceCodeString

Return raw data of a specific Device Code.

  • Device Code must be valid and match exactly, including case.
  • Specific Device Codes can be found by simply running the service without this parameter to get a list of all devices.
deviceCode=ASLZAP1006
Optional
dateFromString

Return raw data that has a timestamp on or after a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the beginning of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateFrom=2010-07-27T00:00:00.000Z

dateFrom=2010-07-27

dateFrom=-P1DT1H

  • Previous 1 day and 1 hour, relative to the dateTo. Note the '-' before the P.
dateToString

Return scalar data that has a timestamp before a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the end of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateTo=2016-08-01T00:00:00.000Z

dateTo=2016-08-01

dateTo=PT12H30M

  • Next 12 hours and 30 minutes, relative to the dateFrom.
rowLimitIntegerThe limit on the number of raw data readings to return. If not specified the row limit is 100,000.rowLimit=300
sizeLimitIntegerThe limit on the size of raw data readings to return, specified in MB. If not specified the size limit is 250 MB.sizeLimit=20
convertHexToDecimalBooleanFormat 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
outputFormatString

There are two values:

  • Array (default or if missing) (case insensitive)
    • Data will be output as three arrays for a given device: a lineTypes array, a readings array, and a times array.
  • 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 lists.

outputFormat=array

outputFormat=object

getLatestBooleanSpecifies whether or not 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.getLatest=true
skipErrorsBoolean

skipErrors=true will return all raw data with timestamps

skipErrors=false (default) will return error message when there are some badly formatted raw data within requested time range



Response

Success (outputFormat = Array)

...

ParameterTypeDescriptionExample
Required
tokenStringAll 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=YOUR_TOKEN_HERE
locationCodeString

Return raw data from a specific Location.

  • Location Code must be valid and match exactly, including case.
  • Specific Location Codes can be obtained using the locations service.
locationCode=SCVIP
deviceCategoryCodeString

Return raw data belonging to a specific Device Category Code.

  • Device Category Code must be valid and match exactly, including case.
  • Specific Device Category Codes can be obtained using the deviceCategories service.
deviceCategoryCode=CTD
Optional
dateFromString

Return raw data that has a timestamp on or after a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the beginning of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateFrom=2010-07-27T00:00:00.000Z

dateFrom=2010-07-27

dateFrom=-P1DT1H

  • Previous 1 day and 1 hour, relative to the dateTo. Note the '-' before the P.
dateToString

Return scalar data that has a timestamp before a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the end of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateTo=2016-08-01T00:00:00.000Z

dateTo=2016-08-01

dateTo=PT12H30M

  • Next 12 hours and 30 minutes, relative to the dateFrom.
rowLimitIntegerThe limit on the number of raw data readings to return. If not specified the row limit is 100,000.rowLimit=300
sizeLimitIntegerThe limit on the size of raw data readings to return specified in MB. If not specified the size limit is 250 MB.sizeLimit=20
outputFormatString

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

getLatestBooleanSpecifies whether or not 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.getLatest=true
skipErrorsBoolean

skipErrors=true will return all raw data with timestamps

skipErrors=false (default) will return error message when there are some badly formatted raw data within requested time range



Response

Success (outputFormat = Array)

...