Edit on GitLab

Introduction

OpenSearch is a set of technologies that allow publishing of search results in a standard and accessible format. The Ifremer implementation allows for both satellite and in-situ high-performance geospatial data discovery and access.

Getting Started

Let’s start from the beginning.

URI Components

The OpenSearch base URI addresses, is as follow :

<protocol>://<hostname>:<port>/<resource>.<output-format>?<query-string>

Where :

  • <protocol> is always https.
  • <hostname> is always opensearch.ifremer.fr.
  • <port> is always 443.
  • <resource> is one of the available resources. For instance, granules.
  • <output-format> is one of the supported output formats. For instance, atom.
  • <query-string> is <resource> specific. For instance, with granules as the resource, the query string could be datasetId=swi_l2anad&startPage=0&count=4&timeStart=1000-03-21T00:00:00Z&timeEnd=2200-01-01T00:00:00Z&geoBox=-180.0,-90.0,180.0,90.0, in order to select all granules from swi_l2anad dataset. See more in the resources dedicated pages.

Resources

You’ll find bellow, the available resources to work with, and the associated documentation.

Resource Description
granules Search NetCDF files granules from a wide range of datasets, with search criteria such as bounding box, timespan, and some more properties depending on the datasource

OpenSearch service

You’ll find bellow, some more information at the service level.

Output formats

The only output format supported currently is atom.

Browse to the dedicated resource doc page to see some output examples.

Paging results

A query can always be completed with the pagination options into the <query-string>. The available options are :

  • count=<page_size>, where page_size is the number of results listed per page. The maximum is 10000 results per page.

  • startPage=<page_start_value>, where page_start_value identifies from which result position starts the pagination. Such value starts from 0.

Warning : with or without paging, the ultimate number of results that can be fetched for a given query is limited to 10000 (for instance, you can’t do count=10000&startPage=1 in query string). This issue will be addressed in a later release.

A response always include information about pagination, in order to programmatically determine if the current page is the latest :

<opensearch:totalResults>8722</opensearch:totalResults>
<opensearch:startIndex>0</opensearch:startIndex>
<opensearch:itemsPerPage>4</opensearch:itemsPerPage>

opensearch:startIndex is the same as query parameter count.
opensearch:itemsPerPage is the same as query parameter startPage.
opensearch:totalResults refers to the total number of results.

Sorting results

The client must not assume the result’s items are sorted with particular attributes. The only guarantee is, of course, that the order is preserved when asking for previous or next pages.

Timeout

You may get a timeout error at the service level, if the query took more than 60 seconds to complete. In this case, the HTTP return code will always be 400 (as other errors), and the error message contains the word “timeout”.

HTTP Protocol

You’ll find bellow, some more information at the HTTP level.

Method

The only HTTP method supported is always the GET method.

Return codes

The HTTP status code is set to 400 if an error occurs. The code is set to 200 in case of success.

CORS Headers

The Access-Control-Allow-Origin is set to *, in order to allow remote client interraction, like client-side JavaScript in web browser.

Content-Type

The table shows the HTTP response Content-Type associated to the <output-format>.

<output-format> Content-Type
atom application/atom+xml;charset=UTF-8

Timeout

Our core front-end Apache servers, as well as our Dockerised Nginx instances may return an HTTP 504 Gateway Timeout, if the query take too long to complete (90 seconds after the query has begun). However, as our backends must respond within a 60 seconds timeout, you will most likely received a proper timeout at the OpenSearch service level.