{"id":13948675,"url":"https://github.com/oceannetworkscanada/api-python-client","last_synced_at":"2025-07-20T10:32:29.562Z","repository":{"id":71642077,"uuid":"198900631","full_name":"OceanNetworksCanada/api-python-client","owner":"OceanNetworksCanada","description":"Provides easy access to ONC data in Python","archived":false,"fork":false,"pushed_at":"2025-07-13T05:24:06.000Z","size":8862,"stargazers_count":13,"open_issues_count":7,"forks_count":11,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-07-17T02:47:41.986Z","etag":null,"topics":["api","data-science","ocean-sciences","onc","python"],"latest_commit_sha":null,"homepage":"https://oceannetworkscanada.github.io/api-python-client/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OceanNetworksCanada.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-25T21:01:32.000Z","updated_at":"2025-07-13T05:22:21.000Z","dependencies_parsed_at":"2024-01-11T20:45:58.997Z","dependency_job_id":"fd58b40c-7374-4386-b378-87d4063aca87","html_url":"https://github.com/OceanNetworksCanada/api-python-client","commit_stats":{"total_commits":89,"total_committers":6,"mean_commits":"14.833333333333334","dds":0.3707865168539326,"last_synced_commit":"ca0ccc28d507c16e1e936bbcde04e26576c6c381"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/OceanNetworksCanada/api-python-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OceanNetworksCanada%2Fapi-python-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OceanNetworksCanada%2Fapi-python-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OceanNetworksCanada%2Fapi-python-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OceanNetworksCanada%2Fapi-python-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OceanNetworksCanada","download_url":"https://codeload.github.com/OceanNetworksCanada/api-python-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OceanNetworksCanada%2Fapi-python-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265568890,"owners_count":23789620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","data-science","ocean-sciences","onc","python"],"created_at":"2024-08-08T05:01:27.704Z","updated_at":"2025-07-20T10:32:29.551Z","avatar_url":"https://github.com/OceanNetworksCanada.png","language":"Python","funding_links":[],"categories":["Hydrosphere"],"sub_categories":["Ocean and Hydrology Data Access"],"readme":"\u003ch1 align=\"center\"\u003e\n\u003cimg src=\"https://www.oceannetworks.ca/svg/logo.svg\" width=\"300\"\u003e\n\u003c/h1\u003e\u003cbr\u003e\n\n# onc: client library for accessing Oceans 3.0 API\n\n[![PyPI Latest Release](https://img.shields.io/pypi/v/onc.svg)](https://pypi.org/project/onc/)\n[![PyPI Supported Versions](https://img.shields.io/pypi/pyversions/onc.svg)](https://pypi.org/project/onc/)\n[![License - Apache 2.0](https://img.shields.io/pypi/l/onc.svg)](https://github.com/OceanNetworksCanada/api-python-client/blob/main/LICENSE.txt)\n[![Frontiers in Marine Science Paper](https://img.shields.io/badge/DOI-10.3389%2Ffmars.2022.806452-blue)](https://doi.org/10.3389/fmars.2022.806452)\n\nonc is a Python client library that facilitates access to scientific data hosted by [Ocean Networks Canada](https://oceannetworks.ca)\nthrough the [Oceans 3.0 API](https://data.oceannetworks.ca/OpenAPI) public web services.\nIt can help you explore and download our data, by consuming our\n_[discovery](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#discovery-methods)_,\n_[data product download](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#data-product-download-methods)_,\n_[archive file download](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#archive-file-download-methods)_, and\n_[near real-time data access](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#near-real-time-data-access-methods)_ services.\n\n# Getting Started\n\n## Installation\n\nonc can be installed from PyPI:\n\n```shell\npip install onc\n```\n\n## Obtaining a token\n\nA unique Oceans 3.0 API token is required to access our data.\nTo obtain a token, follow the steps below:\n\n1. Register for an Oceans 3.0 account at \u003chttps://data.oceannetworks.ca/Registration\u003e.\n\n2. Log into your account at \u003chttps://data.oceannetworks.ca\u003e by clicking the Log In link.\n\n3. Click the _Profile_ link (top right corner) to access your account profile.\n\n4. Access the _Web Services API_ tab and click _Copy Token_.\n\n5. If you forget your token, you can always find it again in your Oceans 3.0 account profile.\n\n## Searching with discovery methods\n\nTo download ONC data, you need to specify the type of data you require\nand where in particular (i.e. location, device) it originates from.\n\nIn the Oceans 3.0 API, there's a unique code that identifies every location, device, property, data product type, etc.\nInclude these codes in a group of filters (these will be used as URL parameters when making HTTP requests)\nthat determine the data you're interested in.\n\nDiscovery methods allow you to explore the hierarchy of the ONC database to obtain the codes for your filters\n(they work like a \"search\" function).\n\nThe example below uses the `getLocations` method to search for locations that include \"Burrard\" in their name (i.e. \"Burrard Inlet\"):\n\n```python\nfrom onc import ONC\n\nonc = ONC(\"YOUR_TOKEN\")\n\nonc.getLocations({\"locationName\": \"Burrard\"})\n```\n\nThe previous code prints a list with locations that match the search filters provided.\nEach location in the list includes a _dataSearchURL_ that points to the Data Search Tool,\nand a _locationCode_ (\"BIPP\" and \"BISS\" in this example) that can be used to continue searching \"inside\" it,\nas in the following example:\n\n```python\nonc.getDeviceCategories({\"locationCode\": \"BIIP\"})\nonc.getDataProducts({\"locationCode\": \"BIIP\", \"deviceCategoryCode\": \"CTD\"})\n```\n\nCheck more on the _[discovery methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#discovery-methods)_\nand _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/index.html)_.\n\n## Downloading data products\n\nOnce you determine the exact dictionary of filters that identifies the data you are interested in,\nthere are multiple methods to download it.\n\nOne method is to request the ONC servers to generate a custom data product with the data.\nThis is done through the data product download methods.\n\nThe following example downloads two PNG files with plots for 30 seconds of data from a CTD in Campbell River:\n\n```python\nparams = {\n    \"locationCode\": \"BIIP\",\n    \"deviceCategoryCode\": \"CTD\",\n    \"dataProductCode\": \"TSSP\",\n    \"extension\": \"png\",\n    \"dateFrom\": \"2019-06-20T00:00:00.000Z\",\n    \"dateTo\": \"2019-06-20T00:30:00.000Z\",\n    \"dpo_qualityControl\": \"1\",\n    \"dpo_resample\": \"none\",\n}\nonc.orderDataProduct(params, includeMetadataFile=False)\n```\n\nThe filters above include codes for location, deviceCategory, and dataProduct,\nas well as the file extension and a time interval (in UTC).\nThey also include a couple of filters to configure this specific data product type (starting with the \"dpo\\_\" prefix),\nwhich can be obtained from the [Data Product Options](https://wiki.oceannetworks.ca/display/DP/Data+Product+Options) documentation.\nYou can download more than 120 different [types of data products](https://wiki.oceannetworks.ca/display/O2A/Available+Data+Products) including audio \u0026 video.\n\nCheck more on the _[data product download methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#data-product-download-methods)_\nand _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Download_Data_Products.html)_.\n\n## Obtaining sensor readings in (near) real-time\n\nAnother method to obtain ONC data is by directly obtaining a time series of sensor readings\n(available as soon as they reach our database).\n\nIn the following example, we obtain 5 seconds of conductivity readings from the CTD at Burrard Inlet:\n\n```python\nparams = {\n    \"locationCode\": \"BIIP\",\n    \"deviceCategoryCode\": \"CTD\",\n    \"propertyCode\": \"conductivity\",\n    \"dateFrom\": \"2019-06-20T00:00:00.000Z\",\n    \"dateTo\": \"2019-06-20T00:00:05.000Z\",\n}\nonc.getScalardata(params)\n\n# Longer method name\n# onc.getScalardataByLocation(params)\n```\n\nThe result includes matching lists of \"values\" and \"sampleTimes\" (increases performance for long time ranges).\nWe also use the property code \"conductivity\" to limit results to a specific property available in this CTD.\n\nCheck more on the _[near real-time data access methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#near-real-time-data-access-methods)_\nand _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Request_Real_Time_Data.html)_.\n\n## Downloading archived files\n\nONC scripts auto-generate and archive data products of different types at set time intervals.\nYou can directly download these data product files from our files archive, as long as you know their unique filename.\n\nIn the following example, we get a list of archived files available for a camera at Ridley Island (in a certain time span),\nand download one of the files:\n\n```python\nparams = {\n    \"locationCode\": \"RISS\",\n    \"deviceCategoryCode\": \"VIDEOCAM\",\n    \"dateFrom\": \"2016-12-01T00:00:00.000Z\",\n    \"dateTo\": \"2016-12-01T00:05:00.000Z\",\n}\nresult = onc.getArchivefile(params, allPages=True)\n\n# Longer method name\n# result = onc.getArchivefileByLocation(params, allPages=True)\n\n# Download one of the files from result[\"files\"]\nonc.downloadArchivefile(\"AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg\", overwrite=True)\n```\n\nYou can use the method `downloadArchivefile()` as above to download individual files or the method `downloadDirectArchivefile()`\nto download all the files that match your filters.\n\nAlternatively, if you prefer using a download manager like [aria2](https://aria2.github.io/) or [Free Download Manager](https://www.freedownloadmanager.org/), `getArchivefileUrls` and `getArchivefileUrl` can return the download URLs of the archivefile\nwithout downloading the files.\n\nCheck more on the _[archive file download methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#archive-file-download-methods)_\nand _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Download_Archived_Files.html)_.\n\n# Documentation\n\nThe client library documentation is hosted on [GitHub Pages](https://oceannetworkscanada.github.io/api-python-client).\nFor documentation and examples about Oceans 3.0 API, visit the [wiki](https://wiki.oceannetworks.ca/display/O2A/Oceans+3.0+API+Home)\nand [OpenAPI](https://data.oceannetworks.ca/OpenAPI) page on the Oceans 3.0 Data Portal website.\n\n# Multithreading issue\n\nWe kindly ask users to **not** use too many threads when using threading/multiprocessing libraries on download tasks.\nIt can cause issues for both server and client and may not appreciably increase download speeds.\n\n# Contributing\n\nAll contributions are welcome and appreciated!\nPlease refer to the [Contributing guide](https://oceannetworkscanada.github.io/api-python-client/contributing.html) before submitting any issues or pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foceannetworkscanada%2Fapi-python-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foceannetworkscanada%2Fapi-python-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foceannetworkscanada%2Fapi-python-client/lists"}