OpenSearch

Using the NASA EOSDIS Common Metadata Repository

CMR OpenSearch Documentation

CMR OpenSearch Overview

CMR OpenSearch is a CMR collections and granules search implementation based on the OpenSearch 1.1 (Draft 5) specification. It allows clients to formulate OpenSearch compliant queries against the CMR collections and granules inventory and specify the desired search results format as OpenSearch compliant ATOM or HTML. The typical two-step usage scenario is described in the ESIP Earth Data discovery OpenSearch best practices document.

Specifications of interest

CMR OpenSearch is compliant with the following specifications, best practices and implementation guides:

Searching for CMR collections (datasets) using OpenSearch

The CMR OpenSearch root OSDD describes the supported search query parameters for CMR OpenSearch collection searches. CMR OpenSearch provides an alternate facet-enabled CMR OpenSearch root OSDD , which allows the client to request the presentation of the faceted search results as specified in the OASIS Search Retrieve via URL 2.0 specification. When requested, facet information is added to the end of the ATOM feed in order to maintain the ATOM response compatibility. It is recommended that OSDD requests include a clientId query paramater, which is used to uniquely identify the client as illustrated in the examples below:

Searching for CWIC CMR collections using OpenSearch

CMR OpenSearch can restrict the scope of the search queries to CEOS WGISS Integrated Catalog (CWIC) collections via the queryParamter isCwic = true. CWIC collections are tagged in the CMR inventory as special collections for which granules are provided via a CWIC OpenSearch interface according to the ESIP Earth Data discovery OpenSearch best practices. Details about CWIC can be found at Committee for Earth Observation Satellites CWIC project page.

Searching for CMR granules using OpenSearch

A CMR collection specific OSDD allow searches for granules within a specified collection. There is no facet-enabled collection specific OSDD. An OpenSearch CMR collection must be uniquely identified by its shortName, versionId and dataCenter as illustrated by the sample CMR OpenSearch collection specific OSDD below:

Retrieving OpenSearch Holdings

To retrieve information related to the holdings across supported OpenSearch providers (in JSON format) visit the holdings endpoint.

For each provider, the endpoint will provide the number of collections, and the sum of all of their granules. Errors and timestamps are also returned for debugging purposes. An example response is provided below: 

    {
      "provider_name": {
        "collections": 263,
        "granules": 0,
        "last_error": null,
        "last_requested_at": "2022-07-22T14:38:02Z",
        "updated_at": "2022-07-22T14:38:04Z"
      }
    }

To retrieve information for a specific provider and their collections (in JSON format) visit the provider holdings endpoint, ensure to change `provider_name` to a supported OpenSearch provider. 

{
    "count": 263,
    "last_requested_at": "2022-07-28T18:24:15Z",
    "items": {
      "C1000000001-TEST": {
        "last_error": "No granule url found in tags or related url metadata.",
        "last_requested_at": "2022-07-28T18:24:15Z"
      },
      "C1000000002-TEST": {
        "count": 2733598,
        "updated_at": "2022-07-28T18:24:17Z"
      }
      ...
    }
  }

Validating the standards compliance of the CMR OpenSearch implementation

The CMR OpenSearch or any other implementation which has a publicly accessible OpenSearch Description Document can be validated for compliance with all off the Specifications of interest by providing the URL of the OSDD to be validated to the CWICSmart OSDD validation tool.

The tool will provide individual validation scores for OpenSearch features as well as an overall validation score. For features which failed validation, the tool will suggest ways to achieve compliance.

XML and RELAX NG schemas used for validating the CMR OpenSearch Descriptor Document: