Page History

...

No Format
http://data.oceannetworks.ca/api/dataProductDelivery

Method	Description	Example
request	Create a request for a data product from a filter criteria parameters.	`method=request`
run	Run a data product created by the request method.	`method=run`
download	Download one of the data product result files by index number.	`method=download`

...

The request method creates a search and returns information regarding the number of files, file sizesized, compressed file sizesized, and estimated download times as well as a request id that can be used to run generate the data product using the run method.

...

Parameter	Type	Description	Example
Required
token	string	All Web Services require a token. This can be . Once logged in at http://data.oceannetworks.ca/login, your token can be retrieved or generated at http://dmasdata.uvicoceannetworks.ca/Profile . Click on the "Web Services" tab and , then click "Generate Token".	token=5ba514e8-1203-428c-8835-879c8173e387
dataProductCode	string	Request a Data Product for a specific Data Product Code Data Product Code must be valid and match exactly, including case Specific Data Product Codes can be obtained programatically from the dataProducts service or interactively from the Available Data Products page	dataProductCode=TSSD
extension	string	Request a Data Product for a specific File Format Extension Extension must be valid and match exactly, including case Extensions available for specific Data Product Codes can be obtained programatically from the dataProducts service or interactively from the Available Data Products page	extension=csv
begin	datetime	Request a Data Product for data starting at a specific date/time Date Time format: yyyy-MM-dd'T'HH:mm:ss'.'SSS'Z' DateTime is represented in Coordinated Universal Time (UTC)	begin=2016-07-25T00:00:00.000Z
end	datetime	Request a Data Product for data ending at a specific date/time Date Time format: yyyy-MM-dd'T'HH:mm:ss'.'SSS'Z' DateTime is represented in Coordinated Universal Time (UTC)	end=2016-07-29T00:00:00.000Z
Conditionally Required
locationCode	string	Request a Data Product for data from a specific Location Location Code must be valid and match exactly, including case Specific Location Codes can be obtained programatically from the locations service or interactively from the Available Locations page	locationCode=BACAX
deviceCategoryCode	string	Request a Data Product for data from devices belonging to a specific Device Category Device Category Code must be valid and match exactly, including case Specific Device Category Codes can be obtained programatically from the deviceCateogries service or interactively from the Available Device Categories page	deviceCategoryCode=ADCP2MHZ
deviceCode	string	Request a Data Product for data from a specific Device Device Code must be valid and match exactly, including case Specific Device Codes can be obtained programatically from the devices service or interactively from the Available Devices page	deviceCode=AandOpt0581
propertyCode	string	Request a Data Product for data for a specific Property Property Code must be valid and match exactly, including case Specific Property Codes can be obtained programatically from the properties service or interactively from the Available Properties page	property=pressure
Data Product Options	string	Each Data Product Extension may have required data product options that determine how to process or package the data. Data Product Options include and are not limited to: Quality Control Resampling Data Gaps Hydrophone Data Diversion Mode Data Product Options and usage information for each Data Product, can be found on the Data Product Options page	dpo_qualityControl=1 dpo_resample=average dpo_average=600

...

Search Type Equivalent	Parameters Given
Instrument by location Location (Device Level)	locationCode, deviceCategoryCode
Instrument by location Location (Sensor Level)	locationCode, deviceCategoryCode, propertyCode
Instrument by Category (Device Level)	deviceCode
Instrument by Category (Sensor Level)	deviceCode, propertyCode
Variable by Location	locationCode, propertyCode

...

Response

Detailed information will be returned if the files are about the number of files, file size, compressed file size, and download time estimates are returned if the files are in archive. If the data product needs to be generated, only a dpRequestId will be , status and filesize and processing time estimates are returned.

Success for files from Archive (HTTP 200)

...

Property	Type	Description	Example
dpRequestId	integer	Returns a numerical request id to be passed into the "run" method (SearchHdrId)	"dpRequestId":1852695
numFiles	integer	Returns the number of files that meet the criteria of the search	"numFiles":4
fileSize	Long	The sum of all file size sizes (in bytes)	"fileSize":70766230
compressedFileSize	Long	The sum of all file size (in bytes) after compression	"compressedFileSize":12563408
downloadTimes	String':'Float	A set of three common download speeds and the time (in seconds) it would take to download the files for each speed	"downloadTimes":{"10Mbps":7.076623,"50Mbps":1.4153247,"150Mbps":0.47177488}

...

Property

Type

Description

Example

dpRequestId

integer

Returns a numerical request id to be passed into the "run" method (SearchHdrId)

"dpRequestId":1908432

estimatedFileSize

string

The estimated file size (in bytes)

"estimatedFileSize":"11940760"

or

"estimatedFileSize":"no estimated file size avalible."

estimatedProcessingTime

string

The estimated time (in seconds) it will take to process the data proeuctproduct

"estimatedProcessingTime":"21"

or

"estimatedProcessingTime":"No processing time estimates found for this type of data."

...

errorCode	errorMessage	Description
25	Invalid Time Range, Start Time is in the future.	Occurs when the end is before the begin date/time. The name names of both of the datetime filters will be are included in the " parameter " property.
127	Invalid parameter value	Occurs when an invalid code is used in the filter. Most filters require an exact match, otherwise this error will occur. The name of the filter parameter will be is included in the " parameter " property.
128	Missing parameter	Occurs when multiple parameters are needed, but not all are present. Occurs when begin is used without end. The names of the required filter parameters will be , separated by /, are included in the " parameter " property separated by /.
128	Requested type can not be determined	Occurs when the one of the 5 possible parameter combinations is not usedspecified. A list of the valid parameter combinations are listed in the parameter. "possible parameter combinations are: locationCode, deviceCategoryCode; locationCode, deviceCategoryCode, propertyCode; locationCode, propertyCode; deviceCode; deviceCode, propertyCode"
129	Invalid parameter name	Occurs when a an unsupported filter parameter is used, but is not supported.

Examples

Request a 'Log File' data product in 'txt' format, using a Data Product Code of 'LF' and Extension of 'txt' for Device Category Code of 'ADCP2MHZ' at the Location Code of 'BACAX', Between July 25th and 28th, 2016 25-28 July 2016.

http://data.oceannetworks.ca/api/dataProductDelivery?method=request&token=[YOUR_TOKEN_HERE]&locationCode=BACAX&deviceCategoryCode=ADCP2MHZ&dataProductCode=LF&extension=txt&begin=2016-07-25T00:00:00.000Z&end=2016-07-29T00:00:00.000Z

...

Request a 'Time Series Scalar Data' data product in 'csv' format, using a Data Product Code of 'TSSD' and Extension of Extension 'csv' for the Property Code of 'salinity' at the 'Barkley Canyon Axis (Pod 1) location using the Location Code of 'BACAX', Between July 1st and 12th, 2017 1-12 July 2017.

http://data.oceannetworks.ca/api/dataProductDelivery?method=request&token=[YOUR_TOKEN_HERE]&locationCode=BACAX&propertyCode=salinity&dataProductCode=TSSD&extension=csv&begin=2017-01-01T00:00:00.000Z&end=2017-01-13T00:00:00.000Z&dpo_qualityControl=1&dpo_resample=none&dpo_dataGaps=0

...

Parameter	Type	Description	Example
Required
token	string	All Web Services require a token. This can be . Once logged in at http://data.oceannetworks.ca/login, your token can be retrieved or generated at http://dmasdata.uvicoceannetworks.ca/Profile . Click on the "Web Services" tab and , then click "Generate Token".	token=5ba514e8-1203-428c-8835-879c8173e387
dpRequestId	integer	A dpRequestId returned from the request method. (SearchHdrId)	dpRequestId=1852695

Response

...

HTTP status code 200 is returned when all of the runs in the data product delivery request have completed running.

[
   {
      "dpRunId": 4521400,
      "status": "complete"
   }

The payload contains a list of runs, each run contains containing the following properties:

Property	Type	Description	Example
dpRunId	integer	A Run Id that can be used to download the data product when processing is complete. (AKA, SearchId)	"dpRunId":4521400
status	string	The current status of the data product request. Valid values are ("cancelled", "queued", "error", "running" and "complete").	"status": "complete"

Accepted (HTTP 202)

...

Property	Type	Description	Example
dpRunId	integer	A Run Id that can be used to download the data product when processing is complete. (AKA, SearchId)	"dpRunId":4521400
status	string	The current status of data product request. Valid values are ("queued", "error" and "running").	"status": "complete"
queuePosition	An Integer	only Only returned if status is "queued". it starts at 1 meaning it is Position 1 is the first item in the queue.	"queuePosition": 10
message	string	An error message is returned when the status is "error".	"message": "Unable to calculate position in queue."

...

errorCode

errorMessage

Description

127

Invalid search header ID.

Occurs when an invalid Request ID is used in the dpRequestId paramtersparameters.

128

Missing parameter

Occurs when multiple parameters are needed, but not all are present. Occurs when begin is used without end.

The names of the required filter parameters will be , separated by /, are included in the " parameter " property separated by /,

129

Invalid parameter name

Occurs when a an unsupported filter parameter is used, but is not supported.

Example

http://data.oceannetworks.ca/api/dataProductDelivery?method=run&token=[YOUR_TOKEN_HERE]&dpRequestId=[YOUR_REQUEST_ID_HERE]

...

The download method downloads a file for the specified data product searchrun request. The file to download is specified by index, with the first valid index being 1 and the last being the total number of files generated by the searchrequest.

Parameters

Parameter	Type	Description	Example
Required
token	string	All Web Services require a token. This can be Once logged in at http://data.oceannetworks.ca/login, your token can be retrieved or generated at http://dmasdata.uvicoceannetworks.ca/Profile . Click on the "Web Services" tab and , then click "Generate Token".	token=5ba514e8-1203-428c-8835-879c8173e387
dpRunId	integer	The dpRunId returned from the run method. (SearchId)
index	integer	The index of the file to be downloaded, valid values are 1 to the number of result files. If the index is greater than the number of result files a response code of 204 is returned, indicating no file at that index is returned.

Response

Success

HTTP status code 200 will be is returned in the HTTP header and the requested file will be is downloaded.

Response Codes

Response Code	Description
200 - Ok	The file is included in the payload.
202 - Accepted	The data product and index are valid but the data product is still being processed. This status can be used to poll waiting for data product completion. The payload includes the comment as displayed in the GUI.
204 - No Content	There is no result file for the data product at the index specified. This can be used to stop looping through result files when the actual number of result files isn't known.
400 - Bad Request	Missing required parameters.
	dpRunId is not a number.
	index is not neither a positive number or not nor "meta".
	dpRunId is not a valid data product run Id.
	The data product selected by dpRunId was run by a different user.
	Index is "meta", but the data product does not include metadata
401 - Unauthorized	Token is invalid.
404 - Not Found	Index number is greater than the number of files.
410 - Gone	The result file selected by dpRunId and index is not in expected location and may have been removed during FTP clean up.
500 - Internal Server Error	This is an unhandled exception and should not occur. All 500 errors should be immediately reported and a JIRA ticket created at http://jira.neptune.uvic.ca/servicedesk/customer/portal/9/create/43.

Examples

The following is an example of the return of for a data product that is still being processed, note that the response code in this case is 202.

...

{
    "message": "Transferring (BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv) to the FTP server",
    "status": "running"
}

Property	Type	Description	Example
status	string	The current status of the data product request. Valid values are ("queued", "error" and "running")	"status": "running"
message	string	The latest status message reported by the data product process.	"message": "Transferring (BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv) to the FTP server"

...

Page tree

Versions Compared

Old Version 13

New Version 14

Key

Response

Success for files from Archive (HTTP 200)

Examples

Response

Accepted (HTTP 202)

Example

Parameters

Response

Success

Response Codes

Examples