Latest version:

2.3.1 (14/08/2019)

The Python Client Library provides easy access to the Oceans 2.0 Web API by providing a class that hides the complexity of consuming ONC's web services. The class methods provided by this package allow to request and download ONC data and files using a single line of code.

If this is your first time using this library, you might want to visit the Installation and Getting started pages.


Discovery methods

Search for available locations, deployments, device categories, devices, properties, and data products (documentation).


getLocations (filters)

Returns a filtered list of locationslink

getLocationHierarchy (filters)

Returns a filtered tree of locations with their childrenlink

getDeployments (filters)

Returns a filtered list of deploymentslink

getDeviceCategories (filters)

Returns a filtered list of device categorieslink

getDevices (filters)

Returns a filtered list of deviceslink

getProperties (filters)

Returns a filtered list of propertieslink

getDataProducts (filters)

Returns a filtered list of data productslink

Data product download methods

Order the generation and download of more than 120 different types of ONC data products, with your own configuration (documentation).



orderDataProduct (filters, maxRetries, downloadResultsOnly, includeMetadataFile)

Request, run and download a data productlink

requestDataProduct (filters)

Request a data productlink

runDataProduct (dpRequestId, waitComplete)

Run a data product requestlink

downloadDataProduct (runId, maxRetries, downloadResultsOnly, includeMetadataFile, overwrite) 

Download an available data productlink

Near real-time data access methods

Extract sensor data as time-series, either as processed scalar data or as raw data directly from the device (documentation).



getDirectByLocation (filters, allPages)

Obtain scalar data readings from a device category in a locationlink
getDirectByDevice (filters, allPages)Obtain scalar data readings from a devicelink

getDirectRawByLocation (filters, allPages)

Obtain raw data readings from a device category in a locationlink

getDirectRawByDevice (filters, allPages)

Obtain raw data readings from a devicelink

Archive file download methods

Download previously generated data product files from our archive (documentation).



getListByLocation (filters, allPages)

Get a list of archived files for a device category in a locationlink

getListByDevice (filters, allPages)

Get a list of archived files for a devicelink

getFile (filename, overwrite)

Download a file with the given filenamelink
getDirectFiles (filters, overwrite, allPages)Download a list of archived files that match the filters providedlink

Utility methods

Methods included as convenience shortcuts for end users. (documentation).


print (dict, filename)

Prints a dictionary in a format easier to readlink

formatUtc (dateString)

Formats the provided date string to meet ISO8601link

The latest library version works with the current version of Oceans 2.0 Web API.

New versions are created to resolve known client library issues, add new functionality or handle changes to the underlying Web Services.

Please report all issues with the web services, documentation and client libraries to the Oceans 2.0 Help Centre.