An API (Application Programming Interface) is basically a programmatic tool that is used to interact with a system; in this case, the Balearic Islands Coastal Ocean Observing System (SOCIB). In other words, SOCIB API offers the possibility of discovering the SOCIB Data Repository and retrieving the data it contains. A success story is the development of the SOCIB Data Catalog web that fully relies on the capacity of this API.

This API is a REST API, which means that the requests are issued with an usual HTTP client (available in any programming language) and on the notebooks in this repository users will find useful code snippets in Python for doing so.

SOCIB API is meant to replace the services provided by the soon-to-be-deprecated SOCIB Data Discovery API. Among the significant improvements of SOCIB API over SOCIB Data Disocvery API users will find:

• Extended data discovery and retrieval capabilities. Unlike SOCIB Data Discovery API, SOCIB API does not limit the data retrieval to the last 60 days: users can now request further data (no temporal restrictions). In addition, a most complete set of parameters have been enabled so that users establish different filtering criteria over the data in the requests.
• New types of data, SOCIB API now handles gridded-like data in addition to time series, profiles and trajectory-like data. So far, this gridded data only applies to the observations produced by SOCIB High Frequency Radar system
• New data-entities. SOCIB API distinguishes a total of 3 data-entities: entries (files), sources (files coming from the same instrument/platform) and products (files from different instrument/platforms sharing a given context: i.e produced in the frame of a given project, campaign etc).
• Authentication. SOCIB API supports user authentication via API keys. This way users activity can be properly tracked.
• New dictionaries. SOCIB API now provides a wider range of dictionaries with descriptive fields to introduce the users the available types of platforms, instruments, processing levels, variables etc

SOCIB API is addressed to two different types of users: the IT (software developer) user and the scientists. IT experts will find the use of the API almost trivial. Scientists with no previous experience on API usage, will need some training.

Go to the API home page and request an API key (form at the bottom of the page) to be able to discover and retrieve SOCIB data by means of the API.

• Data streams (Static | Live):

  • Origin: Platform-types and instruments-types managed by SOCIB Observing System.
  • Content: standard variables managed by SOCIB Observing System
  • Representations: data-modes, data-levels and features

• Data entities (Static | Live):

  • Discovery: find data produced in a given area, time range, containing a certain variable and involving a given instrument or/and platform type.
  • Download: download data from the above discovery results.

• Export search results to CSV - for later download or sharing purposes (quickSetup1.zip)

This material has been developed by Paz Rotllan. Email: [email protected]

Copyright (c) 2017 ICTS SOCIB - Servei d'observació i predicció costaner de les Illes Balears.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.