API Documentation

See the CMR Client Partner User Guide for a general guide to developing a client utilizing the CMR Search API.
Join the CMR Client Developer Forum to ask questions, make suggestions and discuss topics like future CMR capabilities.

Table of Contents


General Request Details

Maximum URL Length

The Maximum URL Length supported by CMR is indirectly controlled by the Request Header Size setting in Jetty which is set to 1MB. This translates to roughly 500k characters. Clients using the Search API with query parameters should be careful not to exceed this limit or they will get an HTTP response of 413 FULL HEAD. If a client expects that the query url could be extra long so that it exceeds 500k characters, they should use the POST API for searching.

CORS Header support

The CORS headers are supported on search endpoints. Check CORS Documentation for an explanation of CORS headers. Custom CORS request headers supported are Echo-Token and Client-Id. Custom response headers supported are CMR-Hits and CMR-Request-Id.

Query Parameters

Paging Details

The CMR contains many more results than can be returned in a single response so the number of results that can be returned is limited. The parameters page_num, offset, and page_size along with the sort specified by sort_key control which items will be returned. The query parameter page_size, defaulting to 10, controls the amount of items that will be returned in a response. One of page_num or offset can be provided to index into the search results.

page_num, defaulting to 1, chooses a "page" of items to return. If a search matched 50 items the parameters page=3&page_size=5 would return the 11th item through the 15th item.

offset is a 0 based index into the result set of a query. If a search matched 50 items the parameters offset=3&page_size=5 would return 4th result through the 8th result.

You can not page past the 1 millionth item. Please contact the CMR Team through the CMR Client Developer Forum if you need to retrieve items in excess of 1 million from the CMR. Additionally granule queries which do not target a set of collections are limited to paging up to the 10000th item.

Scrolling Details

Scrolling allows the retrieval of all results of a query in an efficient manner. This parameter is primarily intended to support harvesting of metadata. Scrolling is only supported for parameter queries, but all query parameters are available with the exception of the page_num and offset parameters. The response format for scrolling queries is identical to the response for normal paremter queries with the exception of the addition of the CMR-Scroll-Id header. The CMR-Hits header is useful for determining the number of requests that will be needed to retrieve all the available results.

Scrolling is session based; the first search conducted with the scroll parameter set to true will return a session id in the form of a CMR-Scroll-Id header. This header should be included in subsequent searches until the desired number of results have been retrieved. Sessions time out after 10 minutes of inactivity; each new query before the timeout is reached with a given CMR-Scroll-Id header will reset the timeout to 10 minutes. Queries occurring after a session has timed out will result in an HTTP 404 status code and error message.

When all the results have been returned subsequent calls using the same CMR-Scroll-Id header will return an empty list.

Parameter Options

The behavior of search with respect to each parameter can be modified using the options parameter. The options parameter takes the following form:

options[parameter][option_key]=value

where parameter is the URL parameter whose behavior is to be affected, value is either true or false, and option_key is one of the following:

Collection Result Feature Parameters

These are query parameters that control what extra data is included with collection search results. They do not impact which collections are matched but can add additional data to the search results like facets, granule counts, and tags.

There is a known bug with the snippet_length parameter that occasionally leads to snippets that are longer than snippet_length characters.

The include_highlights feature is only supported for the JSON response format and only applies to keyword searches.

Headers

Extensions

Besides MimeTypes, client can also use extensions to specify the format for search results. Default is xml.

Here is a list of supported extensions and their corresponding MimeTypes:

Supported Result Formats

HTML

The HTML response format is supported for collections. It allows a single collection record to be viewed in a web browser. HTML is only supported for retrieving a single collection at a time with a URL of the format:

https://cmr.sit.earthdata.nasa.gov/search/concepts/<concept-id>

Atom

See the Atom specification for a full description of Atom.

The CMR Atom format provides search results in an XML file representing a feed of entries. The feed has the following fields:

Atom Feed Level Feeds
Field Description
id the URL linking to this feed
title Either 'ECHO dataset metadata' or 'ECHO granule metadata'
updated The date/time the search was executed

Each entry represents one search result, consisting of the following Atom standard fields and additional CMR specific fields:

Atom Standard Fields
Field Description
id the CMR identifier for the result
title the UMM Entry Title
summary (collections only) the summary of intentions with which this collection was developed. - corresponds to the UMM summary field
updated date/time of the last update to the associated metadata

The following fields are specific to the CMR output and most correspond to ECHO10 fields of the same name:

CMR Specific Fields
Field Description
echo:datasetId UMM entry title of the collection
echo:shortName (collections only) provider defined short name of the collection
echo:versionId (collections only) provider defined version id of the collection
echo:collectionDataType (collections only) type of the collection, e.g. Science Quality or Near Real Time
echo:producerGranuleId (granules only) producer granule id of the granule
echo:granuleSizeMB (granules only) granule size in megabytes
echo:originalFormat original metadata format
echo:dataCenter data center providing the metadata
echo:archiveCenter (collections only) archive center of the metadata
echo:organizations (collections only) organizations associated with the metadata
echo:processingLevelId (collections only) processing level id of the metadata
time:start start time of the metadata
time:end end time of the metadata
link online access and online resource urls associated with the metadata
echo:orbit (granules only) orbit info of the metadata
echo:orbitCalSpatialDomain (granules only) orbit calculated spatial domain nfo of the metadata
echo:coordinateSystem coordinate system info of the metadata
echo:orbitParameters (collections only) fields releated to the satellite orbit (startCircularLatitude, numberOfOrbits, inclinationAngle, period, swathWidth)
georss:point spatial point info of the metadata
georss:line spatial line info of the metadata
georss:box spatial bounding box info of the metadata
georss:polygon spatial polygon info of the metadata
echo:difId (collections only) associated dif id of the collection
echo:onlineAccessFlag true if the data is available online
echo:browseFlag true if the data contains browse imagery
echo:hasGranules (collections only) true if there are granules associated with the collection
echo:granuleCount (collections only) granule count of the collection
relevance:score (collections only) relevance score of the collection to search parameters
echo:tag (collections only) tags associated with the collection. It includes sub-elements of tagKey and optional data which is in embedded JSON.
echo:dayNightFlag (granules only) day night flag of the granule
echo:cloudCover (granules only) cloud cover of the granule

Example

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:os="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:georss="http://www.georss.org/georss/10"
      xmlns="http://www.w3.org/2005/Atom"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:echo="http://www.echo.nasa.gov/esip"
      xmlns:esipdiscovery="http://commons.esipfed.org/ns/discovery/1.2/"
      xmlns:gml="http://www.opengis.net/gml"
      xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/"
      esipdiscovery:version="1.2">
   <updated>2015-06-05T20:10:39.166Z</updated>
   <id>https://cmr.sit.earthdata.nasa.gov/search/collections.atom?pretty=true</id>
   <title type="text">ECHO dataset metadata</title>
   <entry>
      <id>C1200000000-PROV1</id>
      <title type="text">dataset-id</title>
      <summary type="text">The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.</summary>
      <updated>2010-10-06T11:45:39.530Z</updated>
      <echo:datasetId>dataset-id</echo:datasetId>
      <echo:shortName>short</echo:shortName>
      <echo:versionId>v1</echo:versionId>
      <echo:originalFormat>ECHO10</echo:originalFormat>
      <echo:dataCenter>PROV1</echo:dataCenter>
      <echo:orbitParameters/>
      <echo:onlineAccessFlag>false</echo:onlineAccessFlag>
      <echo:browseFlag>false</echo:browseFlag>
      <echo:tag>
        <echo:tagKey>tag1</echo:tagKey>
        <echo:data>{"status":"Reviewed","score":85}</echo:data>
      </echo:tag>
      <echo:tag>
        <echo:tagKey>tag2</echo:tagKey>
        <echo:data>"cloud cover &gt; 80"</echo:data>
      </echo:tag>
   </entry>
</feed>

CSV

The comma separated value (CSV) format is only supported for granules.

Example

Granule UR,Producer Granule ID,Start Time,End Time,Online Access URLs,Browse URLs,Cloud Cover,Day/Night,Size
SC:SPL1AA.001:12345,SMAP_L1C_S0_HIRES_00016_A_20150530T160100_R03001_001.h5,,,,,,,

Metadata Responses (DIF, DIF 10, ECHO 10, ISO-SMAP, ISO-MENDS)

All of the XML Metadata formats (except the XML used in returning references only) have the same structure, differing only in the way each result is returned. These formats return a single XML document with a <results> XML element containing the following fields as sub-elements:

Field Description
hits the number of results matching the search query
took time in milliseconds it took to perform the search
result (zero or more) a single search result - documented below

The results are returned as a sequence of <result> XML elements, the contents of which are documents in the specified format (DIF, ECHO 10 , etc.). If tags are included in the response a <tags> element will directly follow the metadata in the <result> element. Each <result> XML element contains the following attributes:

Attribute Description
concept-id the CMR unique identifier for the concept
format the mime-type for the returned metadata
revision-id the CMR revision number of the stored concept

DIF 9

Mime-type application/dif+xml corresponds to the DIF 9 format. See the specification

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>1</hits>
    <took>30</took>
    <result concept-id="C1200000000-PROV1" format="application/dif+xml" revision-id="1">
        <DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/"
            xmlns:dif="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/ http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/dif_v9.9.3.xsd">
            <Entry_ID>short_v1</Entry_ID>
            <Entry_Title>dataset-id</Entry_Title>
            <Data_Set_Citation>
                <Version>v1</Version>
            </Data_Set_Citation>
            <Quality/>
            <Use_Constraints/>
            <Summary>
                <Abstract>The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.</Abstract>
                <Purpose/>
            </Summary>
            <Metadata_Name>CEOS IDN DIF</Metadata_Name>
            <Metadata_Version>VERSION 9.9.3</Metadata_Version>
            <DIF_Creation_Date>2008-04-22T12:53:38.320Z</DIF_Creation_Date>
            <Last_DIF_Revision_Date>2010-10-06T11:45:39.530Z</Last_DIF_Revision_Date>
        </DIF>
        <tags>
          <tag>
            <tagKey>tag1</tagKey>
            <data>{"status":"Reviewed","score":85}</data>
          </tag>
          <tag>
            <tagKey>tag2</tagKey>
            <data>"cloud cover &gt; 80"</data>
          </tag>
        </tags>
    </result>
</results>

DIF 10

See the specification for details.

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>1</hits>
    <took>30</took>
    <result concept-id="C1200000000-PROV1"
        format="application/dif10+xml" revision-id="1">
        <DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/"
            xmlns:dif="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <Entry_ID>short_v1</Entry_ID>
            <Version>v1</Version>
            <Entry_Title>dataset-id</Entry_Title>
            <Science_Keywords>
                <Category>Not provided</Category>
                <Topic>Not provided</Topic>
                <Term>Not provided</Term>
            </Science_Keywords>
            <Platform>
                <Type>Not provided</Type>
                <Short_Name>Not provided</Short_Name>
                <Instrument>
                    <Short_Name>Not provided</Short_Name>
                </Instrument>
            </Platform>
            <Spatial_Coverage>
                <Granule_Spatial_Representation>CARTESIAN</Granule_Spatial_Representation>
            </Spatial_Coverage>
            <Project>
                <Short_Name>Not provided</Short_Name>
            </Project>
            <Quality/>
            <Use_Constraints/>
            <Summary>
                <Abstract>The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.</Abstract>
                <Purpose/>
            </Summary>
            <Related_URL>
                <URL>Not provided</URL>
            </Related_URL>
            <Metadata_Name>CEOS IDN DIF</Metadata_Name>
            <Metadata_Version>VERSION 10.1</Metadata_Version>
            <Metadata_Dates>
                <Metadata_Creation>2008-04-22T12:53:38.320Z</Metadata_Creation>
                <Metadata_Last_Revision>2010-10-06T11:45:39.530Z</Metadata_Last_Revision>
                <Data_Creation>1970-01-01T00:00:00</Data_Creation>
                <Data_Last_Revision>1970-01-01T00:00:00</Data_Last_Revision>
            </Metadata_Dates>
        </DIF>
        <tags>
          <tag>
            <tagKey>tag1</tagKey>
            <data>{"status":"Reviewed","score":85}</data>
          </tag>
          <tag>
            <tagKey>tag2</tagKey>
            <data>"cloud cover &gt; 80"</data>
          </tag>
        </tags>
    </result>
</results>

ECHO 10

See the specification for details.

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>1</hits>
    <took>17</took>
    <result concept-id="C1200000000-PROV1"
        format="application/echo10+xml" revision-id="1">
        <Collection>
            <ShortName>short</ShortName>
            <VersionId>v1</VersionId>
            <InsertTime>2008-04-22T12:53:38.320Z</InsertTime>
            <LastUpdate>2010-10-06T11:45:39.530Z</LastUpdate>
            <LongName>AMSR-E/Aqua 5-Day L3 Global Snow Water Equivalent EASE-Grids</LongName>
            <DataSetId>dataset-id</DataSetId>
            <Description>The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.</Description>
            <Orderable>false</Orderable>
            <Visible>true</Visible>
        </Collection>
        <tags>
          <tag>
            <tagKey>tag1</tagKey>
            <data>{"status":"Reviewed","score":85}</data>
          </tag>
          <tag>
            <tagKey>tag2</tagKey>
            <data>"cloud cover &gt; 80"</data>
          </tag>
        </tags>
    </result>
</results>

ISO-MENDS (ISO-19115)

See the specification

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>1</hits>
    <took>1373</took>
    <result concept-id="C1200000000-PROV1"
        format="application/iso19115+xml" revision-id="1">
        <gmi:MI_Metadata
            xmlns:eos="http://earthdata.nasa.gov/schema/eos"
            xmlns:gco="http://www.isotc211.org/2005/gco"
            xmlns:gmd="http://www.isotc211.org/2005/gmd"
            xmlns:gmi="http://www.isotc211.org/2005/gmi"
            xmlns:gml="http://www.opengis.net/gml/3.2"
            xmlns:gmx="http://www.isotc211.org/2005/gmx"
            xmlns:gsr="http://www.isotc211.org/2005/gsr"
            xmlns:gss="http://www.isotc211.org/2005/gss"
            xmlns:gts="http://www.isotc211.org/2005/gts"
            xmlns:srv="http://www.isotc211.org/2005/srv"
            xmlns:swe="http://schemas.opengis.net/sweCommon/2.0/"
            xmlns:xlink="http://www.w3.org/1999/xlink"
            xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <!--Other Properties, all:0, coi:0,ii:0,si:0,pli:0,pri:0,qi:0,gi:0,ci:0,dk:0,pcc:0,icc:0,scc:0-->
            <gmd:fileIdentifier>
                <gco:CharacterString>gov.nasa.echo:dataset-id</gco:CharacterString>
            </gmd:fileIdentifier>
            <gmd:language>
                <gco:CharacterString>eng</gco:CharacterString>
            </gmd:language>
            <gmd:characterSet>
                <gmd:MD_CharacterSetCode
                    codeList="http://www.ngdc.noaa.gov/metadata/published/xsd/schema/resources/Codelist/gmxCodelists.xml#MD_CharacterSetCode" codeListValue="utf8">utf8</gmd:MD_CharacterSetCode>
            </gmd:characterSet>
            <gmd:hierarchyLevel>
                <gmd:MD_ScopeCode
                    codeList="http://www.ngdc.noaa.gov/metadata/published/xsd/schema/resources/Codelist/gmxCodelists.xml#MD_ScopeCode" codeListValue="series">series</gmd:MD_ScopeCode>
            </gmd:hierarchyLevel>
            <gmd:contact gco:nilReason="missing"/>
            <gmd:dateStamp>
                <gco:DateTime>2015-06-05T16:17:30.386-04:00</gco:DateTime>
            </gmd:dateStamp>

            ...

            <gmd:dataQualityInfo>
                <gmd:DQ_DataQuality>
                    <gmd:scope>
                        <gmd:DQ_Scope>
                            <gmd:level>
                                <gmd:MD_ScopeCode
                                    codeList="http://www.ngdc.noaa.gov/metadata/published/xsd/schema/resources/Codelist/gmxCodelists.xml#MD_ScopeCode" codeListValue="series">series</gmd:MD_ScopeCode>
                            </gmd:level>
                        </gmd:DQ_Scope>
                    </gmd:scope>
                    <gmd:lineage>
                        <gmd:LI_Lineage>
                            <gmd:processStep>
                                <gmi:LE_ProcessStep>
                                    <gmd:description gco:nilReason="unknown"/>
                                </gmi:LE_ProcessStep>
                            </gmd:processStep>
                        </gmd:LI_Lineage>
                    </gmd:lineage>
                </gmd:DQ_DataQuality>
            </gmd:dataQualityInfo>
            <gmd:metadataMaintenance>
                <gmd:MD_MaintenanceInformation>
                    <gmd:maintenanceAndUpdateFrequency>
                        <gmd:MD_MaintenanceFrequencyCode
                            codeList="http://www.ngdc.noaa.gov/metadata/published/xsd/schema/resources/Codelist/gmxCodelists.xml#MD_MaintenanceFrequencyCode" codeListValue="irregular">irregular</gmd:MD_MaintenanceFrequencyCode>
                    </gmd:maintenanceAndUpdateFrequency>
                    <gmd:maintenanceNote>
                        <gco:CharacterString>Translated from ECHO using ECHOToISO.xsl Version: 1.31 (Nov. 3, 2014)</gco:CharacterString>
                    </gmd:maintenanceNote>
                </gmd:MD_MaintenanceInformation>
            </gmd:metadataMaintenance>
            <gmi:acquisitionInformation>
                <gmi:MI_AcquisitionInformation/>
            </gmi:acquisitionInformation>
        </gmi:MI_Metadata>
        <tags>
          <tag>
            <tagKey>tag1</tagKey>
            <data>{"status":"Reviewed","score":85}</data>
          </tag>
          <tag>
            <tagKey>tag2</tagKey>
            <data>"cloud cover &gt; 80"</data>
          </tag>
        </tags>
    </result>
</results>

ISO-SMAP

See the specification

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>1</hits>
    <took>15</took>
    <result concept-id="C1200000000-PROV1"
        format="application/iso:smap+xml" revision-id="1">
        <gmd:DS_Series xmlns:gco="http://www.isotc211.org/2005/gco"
            xmlns:gmd="http://www.isotc211.org/2005/gmd"
            xmlns:gmi="http://www.isotc211.org/2005/gmi"
            xmlns:gml="http://www.opengis.net/gml/3.2"
            xmlns:gmx="http://www.isotc211.org/2005/gmx"
            xmlns:gsr="http://www.isotc211.org/2005/gsr"
            xmlns:gss="http://www.isotc211.org/2005/gss"
            xmlns:gts="http://www.isotc211.org/2005/gts"
            xmlns:xlink="http://www.w3.org/1999/xlink"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.isotc211.org/2005/gmd file:/Users/bweiss/Desktop/SMAP/Metadata/NASASchemaFolder/schema.xsd">
            <gmd:composedOf gco:nilReason="inapplicable"/>
            <gmd:seriesMetadata>
                <gmi:MI_Metadata
                    xmlns:srv="http://www.isotc211.org/2005/srv" xmlns:xs="http://www.w3.org/2001/XMLSchema">
                    <gmd:fileIdentifier>
                        <gco:CharacterString>L1A_Radar</gco:CharacterString>
                        <!-- Assume that the file Identifier for series metadata would be the identifier that denotes that a file belongs to this series. -->
                    </gmd:fileIdentifier>
                    <gmd:language>
                        <gco:CharacterString>eng</gco:CharacterString>
                    </gmd:language>
                    <gmd:characterSet>
                        <gmd:MD_CharacterSetCode
                            codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#MD_CharacterSetCode" codeListValue="utf8">utf8</gmd:MD_CharacterSetCode>
                    </gmd:characterSet>

                    ...

                    <gmd:identificationInfo>
                        <gmd:MD_DataIdentification>
                            <gmd:citation>
                                <gmd:CI_Citation>
                                    <gmd:title>
                                    <gco:CharacterString>DIFID</gco:CharacterString>
                                    </gmd:title>
                                    <gmd:date>
                                    <gmd:CI_Date>
                                    <gmd:date>
                                    <gco:DateTime>2013-04-05T17:15:00Z</gco:DateTime>
                                    </gmd:date>
                                    <gmd:dateType>
                                    <gmd:CI_DateTypeCode
                                    codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode" codeListValue="revision">revision</gmd:CI_DateTypeCode>
                                    </gmd:dateType>
                                    </gmd:CI_Date>
                                    </gmd:date>
                                    <gmd:identifier>
                                    <gmd:MD_Identifier>
                                    <gmd:code>
                                    <gco:CharacterString>A_DIF_ID</gco:CharacterString>
                                    </gmd:code>
                                    </gmd:MD_Identifier>
                                    </gmd:identifier>
                                </gmd:CI_Citation>
                            </gmd:citation>
                            <gmd:abstract>
                                <gco:CharacterString>DIFID</gco:CharacterString>
                            </gmd:abstract>
                            <gmd:purpose>
                                <gco:CharacterString>DIFID</gco:CharacterString>
                            </gmd:purpose>
                            <gmd:language>
                                <gco:CharacterString>eng</gco:CharacterString>
                            </gmd:language>
                        </gmd:MD_DataIdentification>
                    </gmd:identificationInfo>
                </gmi:MI_Metadata>
            </gmd:seriesMetadata>
        </gmd:DS_Series>
    </result>
</results>

JSON

The JSON response contains the same fields as the ATOM response.

Example

{
  "feed" : {
    "updated" : "2015-06-05T17:52:10.316Z",
    "id" : "https://cmr.sit.earthdata.nasa.gov/search/collections.json?pretty=true",
    "title" : "ECHO dataset metadata",
    "entry" : [ {
      "version_id" : "v1",
      "updated" : "2010-10-06T11:45:39.530Z",
      "dataset_id" : "dataset-id",
      "data_center" : "PROV1",
      "short_name" : "short",
      "title" : "dataset-id",
      "summary" : "The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.",
      "orbit_parameters" : { },
      "id" : "C1200000000-PROV1",
      "original_format" : "ECHO10",
      "browse_flag" : false,
      "online_access_flag" : false,
      "tags" : {"tag1": {"data": {"score": 85, "status": "reviewed"}},
                "tag2": {"data" : "cloud cover > 80"}}
    } ]
  }
}

UMM JSON

The JSON response contains meta-metadata of the collection and the UMM fields. The UMM JSON format is only applicable to collection searches. The UMM-JSON response is helpful if you wish to get the native-id of a collection after ingesting it. The version of the UMM returned will be the version requested or the latest most version. Clients are recommended to always specify a version to avoid breaking changes in UMM.

This format can be retrieved in a variety of methods:

Example

{
  "hits" : 2,
  "took" : 11,
  "items" : [ {
    "meta" : {
      "revision-id" : 3,
      "deleted" : false,
      "format" : "application/echo10+xml",
      "provider-id" : "PROV1",
      "native-id" : "et1",
      "concept-id" : "C1200000000-PROV1",
      "revision-date" : "2016-07-27T12:00:17Z",
      "concept-type" : "collection"
    },
    "umm" : {
      "SpatialExtent" : {
        "HorizontalSpatialDomain" : {
          "Geometry" : {
            "CoordinateSystem" : "GEODETIC",
            "Points" : [ {
              "Longitude" : 0.0,
              "Latitude" : 90.0
            } ]
          }
        },
        "GranuleSpatialRepresentation" : "GEODETIC"
      },
      "ScienceKeywords" : [ {
        "Category" : "Cat1",
        "Topic" : "Topic1",
        "Term" : "Term1"
      } ],
      "TemporalExtents" : [ {
        "RangeDateTimes" : [ {
          "BeginningDateTime" : "2000-01-01T00:00:00.000Z"
        } ]
      } ],
      "ProcessingLevel" : {
        "Id" : "Level 1"
      },
      "ShortName" : "s1",
      "EntryTitle" : "et1",
      "RelatedUrls" : [ {
        "Description" : "description648",
        "URLContentType" : "DistributionURL",
        "Type" : "GET DATA" ,
        "URL" : "http://example.com/file649"
      } ],
      "DataDates" : [ {
        "Date" : "2012-01-11T10:00:00.000Z",
        "Type" : "CREATE"
      }, {
        "Date" : "2012-01-19T18:00:00.000Z",
        "Type" : "UPDATE"
      } ],
      "Abstract" : "long-name651",
      "Version" : "v2",
      "DataCenters" : [ {
        "Roles" : [ "ARCHIVER" ],
        "ShortName" : "Not provided"
      } ],
      "Platforms" : [ {
        "Type" : "Type647",
        "ShortName" : "platform",
        "LongName" : "long-name646"
      } ]
    }
  }, {
    "meta" : {
      "native-id" : "et3",
      "provider-id" : "PROV2",
      "concept-type" : "collection",
      "concept-id" : "C1200000002-PROV2",
      "revision-date" : "2016-07-27T12:00:17Z",
      "user-id" : "user3",
      "deleted" : false,
      "revision-id" : 1,
      "format" : "application/echo10+xml"
    },
    "umm" : {
      "..."
    }
  } ]
}

When retrieving data in UMM JSON that has a native format other than UMM JSON, if there is an error parsing an individual field an "_errors" field will be added to the UMM with details about the parsing error.

Example

{ "Projects" : [ {
    "ShortName" : "Project2 Short Name",
    "LongName" : "Project2 Long Name",
    "Campaigns" : [ "Project 2 Campaign1 Short Name", "Project 2 Campaign2 Short Name" ],
    "_errors" : {
      "StartDate" : "Could not parse date-time value: 2002:03:01T01:00:00Z",
      "EndDate" : "Could not parse date-time value: 2002:04:02T01:00:00Z"
    }
  } ] }

A collection containing "_errors" is not valid UMM and cannot be ingested into the CMR.

KML

KML is the XML language used by the Google Earth application and is used by the CMR to return spatial data associated with a collection or granule.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
   <Document>
      <Style id="geodetic_style">
         <LineStyle>
            <color>ffffffff</color>
            <colorMode>random</colorMode>
            <width>2</width>
         </LineStyle>
         <IconStyle>
            <color>ffffffff</color>
            <colorMode>random</colorMode>
            <scale>3.0</scale>
         </IconStyle>
         <PolyStyle>
            <fill>0</fill>
         </PolyStyle>
      </Style>
      <Style id="cartesian_style">
         <LineStyle>
            <color>ffffffff</color>
            <colorMode>random</colorMode>
            <width>2</width>
         </LineStyle>
         <IconStyle>
            <color>ffffffff</color>
            <colorMode>random</colorMode>
            <scale>3.0</scale>
         </IconStyle>
         <PolyStyle>
            <color>00ffffff</color>
         </PolyStyle>
      </Style>
      <Placemark>
         <name>SC:GLAH06.034:52592022</name>
         <styleUrl>#geodetic_style</styleUrl>
         <Polygon>
            <tessellate>1</tessellate>
            <outerBoundaryIs>
               <LinearRing>
                  <coordinates>54.78656326403332,-50.09193846025951 51.20574574139643,-31.559024005924392 48.4203450238013,-12.998336645829609 45.85491943219788,5.57000444208618 43.19937665770624,24.135158655763025 40.044971936186634,42.68280248541986 38.50355532538929,49.84326030061438 38.53129884465536,49.845207013547224 40.06934290325555,42.68451022431186 43.21903945805716,24.13653428810218 45.87295686415376,5.571265771529057 48.438767344855485,-12.997048263813937 51.22679482714953,-31.55755075104193 54.81444766176902,-50.0899817427687 54.78656326403332,-50.09193846025951</coordinates>
               </LinearRing>
            </outerBoundaryIs>
         </Polygon>
      </Placemark>
   </Document>
</kml>

Open Data

The Open Data format was developed as part of Project Open Data in an attempt to make data more accessible. See the Open Data schema for details.

Example

{
  "conformsTo" : "https://project-open-data.cio.gov/v1.1/schema",
  "dataset" : [ {
    "description" : "The AMSR-E/Aqua Level-3 5-day snow water equivalent (SWE) product includes global 5-day maximum SWE on Northern and Southern Hemisphere 25 km EASE-Grids, generated by the GSFC algorithm using Level-2A TBs.",
    "accessLevel" : "public",
    "bureauCode" : [ "026:00" ],
    "publisher" : {
      "name" : null,
      "subOrganizationOf" : {
        "name" : "National Aeronautics and Space Administration",
        "subOrganizationOf" : {
          "name" : "U.S. Government"
        }
      }
    },
    "contactPoint" : {
      "fn" : "undefined",
      "hasEmail" : "mailto:support@earthdata.nasa.gov"
    },
    "modified" : "2010-10-06T11:45:39.530Z",
    "title" : "dataset-id",
    "theme" : [ "geospatial" ],
    "keyword" : [ "National Geospatial Data Asset", "NGDA" ],
    "language" : [ "en-US" ],
    "programCode" : [ "026:001" ],
    "identifier" : "C1200000000-PROV1",
    "issued" : "2008-04-22T12:53:38.320Z"
  } ]
}

XML

The XML response format is used for returning references to search results. It consists of the following fields:

Field Description
hits the number of results matching the search query
took time in milliseconds it took to perform the search
references identifying information about each search result

The references field may contain multiple reference entries, each consisting of the following fields:

Field Description
name the provider's unique identifier for the item. This is Granule UR for granules and Entry Title for collections.
id the CMR identifier for the result
location the URL at which the full metadata for the result can be retrieved
revision-id the internal CMR version number for the result

Example

<?xml version="1.0" encoding="UTF-8"?>
<results>
   <hits>1</hits>
   <took>9</took>
   <references>
      <reference>
         <name>dataset-id</name>
         <id>C1200000000-PROV1</id>
         <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000000-PROV1</location>
         <revision-id>1</revision-id>
      </reference>
   </references>
</results>

By passing echo_compatible=true in the URL parameters the output can be forced to a format that is compatible with the ECHO search response:

Example

<?xml version="1.0" encoding="UTF-8"?>
<references type="array">
   <reference>
      <name>SMAP Collection Dataset ID</name>
      <id>C1200000000-PROV1</id>
      <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000000-PROV1</location>
   </reference>
</references>

Temporal Range searches

A couple of parameters used in search expect a date range as input. For example, the parameter "temporal" used in collection and granule searches and the parameter "equator_crossing_longitude" used in granule searches both accept date ranges. All these parameters expect temporal ranges in the same format. The temporal ranges can be specified as a pair of date-time values separated by comma(,). Exactly one of the two bounds of the interval can be omitted. In addition to comma separated values, one can also specify temporal ranges as ISO 8601 time intervals. Some examples of valid temporal range values are:

2000-01-01T10:00:00Z,2010-03-10T12:00:00Z - matches data between 2000-01-01T10:00:00Z and 2010-03-10T12:00:00Z
,2010-03-10T12:00:00Z - matches data before 2010-03-10T12:00:00Z
2000-01-01T10:00:00Z, - matches data after 2010-03-10T12:00:00Z
2000-01-01T10:00:00Z/2010-03-10T12:00:00Z - matches data between 2000-01-01T10:00:00Z and 2010-03-10T12:00:00Z
2000-01-01T10:00:00Z/ - matches data after 2010-03-10T12:00:00Z
/2010-03-10T12:00:00Z - matches data before 2010-03-10T12:00:00Z
2000-01-01T10:00:00Z/P10Y2M10DT2H - matches data between 2000-01-01T10:00:00Z and a date 10 years 2 months 10 days and 2 hours after that or 2010-03-11T02:00:00Z
P1Y2M10DT2H30M/2008-05-11T15:30:00Z - matches data between 2008-07-11T16:30:00Z and a date 1 year 2 months 10 days 2 hours and 30 minutes before that or 2007-05-01T14:00:00Z.

Note: ISO 8601 does not allow open-ended time intervals but the CMR API does allow specification of intervals which are open ended on one side. For example, 2000-01-01T10:00:00Z/ and /2000-01-01T10:00:00Z are valid ranges.

Collection Search Examples

Find all collections

curl "https://cmr.sit.earthdata.nasa.gov/search/collections"

Collection search results are paged. See Paging Details for more information on how to page through collection search results.

Find collections by concept id

A CMR concept id is in the format <concept-type-prefix> <unique-number> "-" <provider-id>

Example: C123456-LPDAAC_ECS

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?concept_id\[\]=C123456-LPDAAC_ECS"

Find collections by doi value

Find a collection matching a collection doi value. Note more than one doi value may be supplied.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?doi\[\]=doi"

Find collections by echo collection id

Find a collection matching a echo collection id. Note more than one echo collection id may be supplied.

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?echo_collection_id\[\]=C1000000001-CMR_PROV2"

Find collections by provider short name

This searches for collections whose provider matches the given provider short names. This supports ignore_case option, but not the pattern option.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?provider_short_name\[\]=SHORT_5&options\[provider_short_name\]\[ignore_case\]=true"

Find collections by entry title

One entry title

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?entry_title\[\]=DatasetId%204"

a dataset id (alias for entry title)

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?dataset_id\[\]=DatasetId%204"

with multiple dataset ids

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?entry_title\[\]=DatasetId%204&entry_title\[\]=DatasetId%205"

with a entry title case insensitively

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?entry_title\[\]=datasetId%204&options\[entry_title\]\[ignore_case\]=true"

with a entry title pattern

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?entry_title\[\]=DatasetId*&options\[entry_title\]\[pattern\]=true"

Find collections by entry id

One entry id

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?entry_id\[\]=SHORT_V5"

Find collections by archive center

This supports pattern and ignore_case.

Find collections matching 'archive_center' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?archive_center\[\]=LARC"
curl "https://cmr.sit.earthdata.nasa.gov/search/collections?archive_center=Sedac+AC"

Find collections matching any of the 'archive_center' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?archive_center\[\]=Larc&archive_center\[\]=SEDAC"

Find collections by data center

This supports pattern, and, and ignore_case.

Find collections matching 'data_center' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?data_center\[\]=LARC"
curl "https://cmr.sit.earthdata.nasa.gov/search/collections?data_center=Sedac+AC"

Find collections matching any of the 'data_center' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?data_center\[\]=Larc&data_center\[\]=SEDAC"

Find collections with temporal

The temporal datetime has to be in yyyy-MM-ddTHH:mm:ssZ format.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?temporal\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z,30,60&temporal\[\]=2000-01-01T10:00:00Z,,30&temporal\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z"

The first two values of the parameter together define the temporal bounds. See under Temporal Range searches for different ways of specifying the temporal bounds including ISO 8601.

For temporal range search, the default is inclusive on the range boundaries. This can be changed by specifying exclude_boundary option with options[temporal][exclude_boundary]=true. This option has no impact on periodic temporal searches.

The collection's temporal range or the temporal range of the granules in the collection can be searched. options[temporal][limit_to_granules]=true will indicate that the temporal search should find collections based on the minimum and maximum values of each collection's granules' temporal range. If a collection does not have any granules it will search the collection's temporal range.

If a temporal range search is performed, the search results will be sorted by the temporal overlap across all ranges provided, with usage score being the tie-breaker. If a keyword search is performed in conjunction with the temporal range search, search results are first sorted by relevancy score, then by temporal overlap, then usage score.

Find collections by project

Note: An alias for the parameter 'project' is 'campaign'. As such 'campaign' can be used in place of 'project'.

This supports pattern, ignore_case and option and.

Find collections matching 'project' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?project\[\]=ESI"

Find collections matching any of the 'project' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?project\[\]=ESI&project\[\]=EVI&project\[\]=EPI"

Find collections that match all of the 'project' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?project\[\]=ESI&project\[\]=EVI&project\[\]=EPI&options\[project\]\[and\]=true"

Find collections by updated_since

Find collections which have revision date starting at or after 'updated_since' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?updated_since=2014-05-08T20:06:38.331Z"

Find collections by created_at

This supports option and.

Find collections which were created within the ranges of datetimes. The datetime has to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?created_at[]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z&created_at[]=2015-01-01T10:00:00Z,"

Find collections with new granules

This supports option and.

Find collections containing granules added within the range of datetimes. The datetime has to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.

curl "%CMR_ENDPOINT%/collections?has_granules_created_at=[]2015-01-01T10:00:00Z,"

Find collections by revision_date

This supports option and.

Find collections which have revision date within the ranges of datetimes. The datetime has to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?revision_date\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z&revision_date\[\]=2015-01-01T10:00:00Z,"

Find collections by processing_level_id

This supports pattern and ignore_case.

Find collections matching 'processing_level_id'

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?processing_level_id\[\]=1B"

Find collections matching any of the 'processing_level_id' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?processing_level_id\[\]=1B&processing_level_id\[\]=2B"

The alias 'processing_level' also works for searching by processing level id.

Find collections by platform

This supports pattern, ignore_case and option and.

Find collections matching 'platform' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?platform\[\]=1B"

Find collections matching any of the 'platform' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?platform\[\]=1B&platform\[\]=2B"

Find collections by instrument

This supports pattern, ignore_case and option and.

Find collections matching 'instrument' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?instrument\[\]=1B"

Find collections matching any of the 'instrument' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?instrument\[\]=1B&instrument\[\]=2B"

Find collections by sensor.

Sensor search is deprecated and should be replaced with instrument. Sensors are now child instruments on an instrument.

This supports pattern, ignore_case and option and.

Find collections matching 'sensor' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?sensor\[\]=1B"

Find collections matching any of the 'sensor' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?sensor\[\]=1B&sensor\[\]=2B"

Find collections by spatial_keyword

This supports pattern, ignore_case and option and.

Find collections matching 'spatial_keyword' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?spatial_keyword\[\]=DC"

Find collections matching any of the 'spatial_keyword' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?spatial_keyword\[\]=DC&spatial_keyword\[\]=LA"

Find collections by science_keywords

This supports option or.

Find collections matching 'science_keywords' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?science_keywords\[0\]\[category\]=Cat1"

Find collections matching multiple 'science_keywords' param values, default is :and

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?science_keywords\[0\]\[category\]=Cat1&science_keywords\[0\]\[topic\]=Topic1&science_keywords\[1\]\[category\]=Cat2"

Find collections by two_d_coordinate_system_name

This supports pattern. two_d_coordinate_system[name] param is an alias of two_d_coordinate_system_name, but it does not support pattern.

Find collections matching 'two_d_coordinate_system_name' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?two_d_coordinate_system_name\[\]=Alpha"

Find collections matching any of the 'two_d_coordinate_system_name' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?two_d_coordinate_system_name\[\]=Alpha&two_d_coordinate_system_name\[\]=Bravo"

Find collections by collection_data_type

Supports ignore_case and the following aliases for "NEAR_REAL_TIME": "near_real_time", "nrt", "NRT", "near real time", "near-real time", "near-real-time", "near real-time".

Find collections matching 'collection_data_type' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?collection_data_type\[\]=NEAR_REAL_TIME"

Find collections matching any of the 'collection_data_type' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?collection_data_type\[\]=NEAR_REAL_TIME&collection_data_type\[\]=OTHER"

Find collections by online_only

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?online_only=true"

Find collections by downloadable

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?downloadable=true"

Find collections by browse_only

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?browse_only=true"

Find collections by browsable

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?browsable=true"

Find collections by keyword (free text) search

Keyword searches are case insensitive and support wild cards ? and *.
There is a limit of 30 wild cards allowed in keyword searches. Within 30 wild cards, there's also limit on the max keyword
string length. The longer the max keyword string length, the less number of keywords with wild cards allowed.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?keyword=alpha%20beta%20g?mma"

The following fields are indexed for keyword search:

* Concept ID
* DOI value
* Provider ID
* Entry ID
* Entry title
* Data type
* Short name
* Summary
* Version ID
* Version description
* Processing level ID
* Science keywords
* Ancillary keywords
* Directory Names
* Archive centers
* Additional attribute names, data types, values, and descriptions
* detailed locations
* Spatial keywords
* Temporal keywords
* ISO Topic Categories
* Project short and long names
* Platform short and long names
* Instrument short names, long names, and techniques
* Sensor short names, long names, and techniques
* Characteristic names, descriptions and values
* TwoD coordinate system names

Find collections by provider

This parameter supports pattern, ignore_case and option and.

Find collections matching 'provider' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?provider=ASF"

Find collections matching any of the 'provider' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?provider=ASF&provider=SEDAC"

Find collections by native_id

This parameter supports pattern, ignore_case and option and.

Find collections matching 'native_id' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?native_id=nativeid1"

Find collections matching any of the 'native_id' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?native_id[]=nativeid1&native_id[]=nativeid2"

Find collections by short name

This parameter supports pattern, ignore_case and option and.

Find collections matching any of the 'short_name' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?short_name=DEM_100M&short_name=MINIMAL"

Find collections matching 'short_name' param value with a pattern

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?short_name=D*&options[short_name][pattern]=true"

Find collections by version

This parameter supports pattern, ignore_case and option and.

Find collections matching the given 'short_name' and 'version' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?short_name=DEM_100M&version=1"

Find collections matching the given 'short_name' and any of the 'version' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?short_name=dem_100m&version=1&version=2"

Find collections by tag parameters

Collections can be found by searching for associated tags. The following tag parameters are supported.

exclude parameter can be used with tag_key to exclude any collections that are associated with the specified tag key from the search result.

Find collections matching tag key.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?tag_key=org.ceos.wgiss.cwic.quality"

Find collections with exclude tag key.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?exclude\[tag_key\]=gov.nasa.earthdata.search.cwic"

Find collections with tag_data in the form of tag_data[tag_key]=tag_value. It finds collections match on both tag_key and tag_value, which is the string data that is associated with the collection during tag association.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?tag_data[org.ceos.wgiss.cwic.quality]=foo"

Find collections by variable parameters

Collections can be found by searching for associated variables. The following variable parameters are supported.

Find collections matching variable name.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?variable_name=totcldh2ostderr"

Find collections matching measurement.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?measurement\[\]=Ozone&measurement\[\]=radiance"

Find collections by hierarchical variables

This supports option or.

Find collections matching 'variables-h' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?variables-h\[0\]\[measurement\]=M1"

Find collections matching multiple 'variables-h' param values, default is :and

 curl "https://cmr.sit.earthdata.nasa.gov/search/collections?variables-h\[0\]\[measurement\]=M1&variables-h\[0\]\[variable\]=Var1&variables-h\[1\]\[measurement\]=M2"

Find collections by Spatial

Polygon

Polygon points are provided in counter-clockwise order. The last point should match the first point to close the polygon. The values are listed comma separated in longitude latitude order, i.e. lon1, lat1, lon2, lat2, lon3, lat3, and so on.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?polygon=10,10,30,10,30,20,10,20,10,10"
Bounding Box

Bounding boxes define an area on the earth aligned with longitude and latitude. The Bounding box parameters must be 4 comma-separated numbers: lower left longitude, lower left latitude, upper right longitude, upper right latitude.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?bounding_box=-10,-5,10,5
Point

Search using a point involves using a pair of values representing the point coordinates as parameters. The first value is the longitude and second value is the latitude.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?point=100,20"
Line

Lines are provided as a list of comma separated values representing coordinates of points along the line. The coordinates are listed in the format lon1, lat1, lon2, lat2, lon3, lat3, and so on.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?line=-0.37,-14.07,4.75,1.27,25.13,-15.51"

Note: A query could consist of multiple spatial parameters of different types, two bounding boxes and a polygon for example. If multiple spatial parameters are present, all the parameters irrespective of their type are AND'd in a query. So, if a query contains two bounding boxes and a polygon for example, it will return only those collections which intersect both the bounding boxes and the polygon.

Find collections by additional attribute

Find an attribute attribute with name "PERCENTAGE" only

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=PERCENTAGE"

Find an attribute attribute with name "PERCENTAGE" of type float with value 25.5

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=float,PERCENTAGE,25.5"

Find an attribute attribute with name "PERCENTAGE" of type float in range 25.5 - 30.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=float,PERCENTAGE,25.5,30"

Find an attribute attribute with name "PERCENTAGE" of type float with min value 25.5.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=float,PERCENTAGE,25.5,"

Find an attribute attribute with name "PERCENTAGE" of type float with max value 30.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=float,PERCENTAGE,,30"

Find an additional attribute with name "X\Y\Z" with value 7.

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?attribute\[\]=float,X\Y\Z,7"

Multiple attributes can be provided. The default is for collections to match all the attribute parameters. This can be changed by specifying or option with options[attribute][or]=true.

For additional attribute range search, the default is inclusive on the range boundaries. This can be changed by specifying exclude_boundary option with options[attribute][exclude_boundary]=true.

Find collections with or without granules

When has_granules is set to "true" or "false", results will be restricted to collections with or without granules, respectively.

curl "%CMR_ENDPOINT%/collections?has_granules=true"

Sorting Collection Results

Collection results are sorted by ascending entry title by default when a search does not result in a score.

If a keyword search is performed then the search results will be sorted by relevance (score descending), then by temporal overlap if one or more temporal ranges are provided with the tie breaker being the EMS community usage score (also descending). The usage score comes from EMS metrics which contain access counts of the collections by short name and version. The metrics are ingested into the CMR.

If a temporal range search is performed, the search results will be sorted by temporal overlap percentage over all ranges provided.

One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending.

Valid Collection Sort Keys

Examples of sorting by start_date in descending(Most recent data first) and ascending orders(Note: the + must be escaped with %2B):

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?sort_key\[\]=-start_date"
curl "https://cmr.sit.earthdata.nasa.gov/search/collections?sort_key\[\]=%2Bstart_date"

Retrieving All Revisions of a Collection

In addition to retrieving the latest revision for a collection parameter search, it is possible to return all revisions, including tombstone (deletion marker) revisions, by passing in all_revisions=true with the URL parameters. The reference and UMM JSON response formats are supported for all revision searches. References to tombstone revisions do not include the location tag and include an additional tag, deleted, which always has content of "true".

curl "https://cmr.sit.earthdata.nasa.gov/search/collections?provider=PROV1&all_revisions=true&pretty=true"

Sample response

    <?xml version="1.0" encoding="UTF-8"?>
    <results>
        <hits>3</hits>
        <took>5</took>
        <references>
            <reference>
                <name>et1</name>
                <id>C1200000000-PROV1</id>
                <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000000-PROV1/3</location>
                <revision-id>3</revision-id>
            </reference>
            <reference>
                <name>et1</name>
                <id>C1200000000-PROV1</id>
                <revision-id>2</revision-id>
                <deleted>true</deleted>
            </reference>
            <reference>
                <name>et1</name>
                <id>C1200000000-PROV1</id>
                <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000000-PROV1/1</location>
                <revision-id>1</revision-id>
            </reference>
        </references>
    </results>

Granule Search By Parameters

Find all granules

curl "https://cmr.sit.earthdata.nasa.gov/search/granules"

Granule search results are paged. See Paging Details for more information on how to page through granule search results.

Find granules with a granule-ur

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?granule_ur\[\]=DummyGranuleUR"

Find granules with a producer granule id

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?producer_granule_id\[\]=DummyID"

Find granules matching either granule ur or producer granule id

This condition is encapsulated in a single parameter called readable_granule_name

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?readable_granule_name\[\]=DummyID"

Find granules by online_only

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?online_only=true"

Find granules by downloadable

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?downloadable=true"

Find granules by additional attribute

Find an attribute attribute with name "PERCENTAGE" only

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=PERCENTAGE"

Find an attribute attribute with name "PERCENTAGE" of type float with value 25.5

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,PERCENTAGE,25.5"

Find an attribute attribute with name "PERCENTAGE" of type float in range 25.5 - 30.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,PERCENTAGE,25.5,30"

Find an attribute attribute with name "PERCENTAGE" of type float with min value 25.5.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,PERCENTAGE,25.5,"

Find an attribute attribute with name "PERCENTAGE" of type float with max value 30.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,PERCENTAGE,,30"

Find an additional attribute with name "X,Y,Z" with value 7.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,X\,Y\,Z,7"

Find an additional attribute with name "X\Y\Z" with value 7.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?attribute\[\]=float,X\Y\Z,7"

Multiple attributes can be provided. The default is for granules to match all the attribute parameters. This can be changed by specifying or option with options[attribute][or]=true.

For additional attribute range search, the default is inclusive on the range boundaries. This can be changed by specifying exclude_boundary option with options[attribute][exclude_boundary]=true.

For granule additional attributes search, the default is searching for the attributes included in the collection this granule belongs to as well. This can be changed by specifying exclude_collection option with options[attribute][exclude_collection]=true.

Find granules by Spatial

The parameters used for searching granules by spatial are the same as the spatial parameters used in collections searches. (See under "Find collections by Spatial" for more details.)

Note: The CMR does not permit spatial queries across all granules in all collections in order to provide fast search responses. Spatial granule queries must target a subset of the collections in the CMR using a condition like provider, concept_id (referencing one collection), short_name, or entry_title.

Polygon
curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=PROV1&polygon=10,10,30,10,30,20,10,20,10,10"
Bounding Box
curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=PROV1&bounding_box=-10,-5,10,5
Point
curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=PROV1&point=100,20"
Line
curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=PROV1&line=-0.37,-14.07,4.75,1.27,25.13,-15.51"

Find granules by orbit number

Find granules with an orbit number of 10

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?orbit_number=10"

Find granules with an orbit number in a range of 0.5 to 1.5

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?orbit_number=0.5,1.5"

Find granules by orbit equator crossing longitude

Find granules with an exact equator crossing longitude of 90

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?equator_crossing_longitude=90"

Find granules with an orbit equator crossing longitude in the range of 0 to 10

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?equator_crossing_longitude=0,10

Find granules with an equator crossing longitude in the range from 170 to -170
(across the anti-meridian)

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?equator_crossing_longitude=170,-170

Find granules by orbit equator crossing date

Find granules with an orbit equator crossing date in the range of 2000-01-01T10:00:00Z to 2010-03-10T12:00:00Z

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?equator_crossing_date=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z

The time interval in equator crossing date range searches can be specified in different ways including ISO 8601. See under Temporal Range searches.

Find granules by updated_since

Find granules which have revision date starting at or after 'updated_since' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?updated_since=2014-05-08T20:12:35Z"

Find granules by revision_date

This supports option and.

Find granules which have revision date within the ranges of datetimes. The datetime has to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?revision_date\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z&revision_date\[\]=2015-01-01T10:00:00Z,"

Find granules by created_at

This supports option and.

Find granules which were created within the ranges of datetimes. The datetime has to be in yyyy-MM-ddTHH:mm:ssZ format. The default is inclusive on the range boundaries.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?created_at[]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z&created_at[]=2015-01-01T10:00:00Z,"

Find granules by cloud_cover

Find granules with just the min cloud cover value set to 0.2

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?cloud_cover=0.2,"

Find granules with just the max cloud cover value set to 30

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?cloud_cover=,30"

Find granules with cloud cover numeric range set to min: -70.0 max: 120.0

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?cloud_cover=-70.0,120.0"

Find granules by platform

This supports pattern, ignore_case, exclude_collection and option and. The default behavior is that granules without platform values inherit their parent collection's platform. This can be changed by specifying exclude_collection option with options[platform][exclude_collection]=true.

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?platform\[\]=1B"

Find granules by instrument

This supports pattern, ignore_case, exclude_collection and option and. The default behavior is that granules without instrument values inherit their parent collection's instrument. This can be changed by specifying exclude_collection option with options[instrument][exclude_collection]=true.

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?instrument\[\]=1B"

Find granules by sensor param

This supports pattern, ignore_case, exclude_collection and option and. The default behavior is that granules without sensor values inherit their parent collection's sensor. This can be changed by specifying exclude_collection option with options[sensor][exclude_collection]=true.

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?sensor\[\]=1B"

Find granules by project

Note: An alias for the parameter 'project' is 'campaign'. As such 'campaign' can be used in place of 'project'.

This supports pattern, ignore_case and option and.

Find granules matching 'project' param value

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?project\[\]=2009_GR_NASA"

Find granules matching any of the 'project' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?project\[\]=2009_GR_NASA&project\[\]=2013_GR_NASA"

Find granules matching the given pattern for the 'project' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?project\[\]=20??_GR_NASA&options\[project\]\[pattern\]=true"

Find granules that match all of the 'project' param values

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?project\[\]=2009_GR_NASA&project\[\]=2013_GR_NASA&options\[project\]\[and\]=true"

Find granules by concept id

Note: more than one may be supplied

Find granule by concept id

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?concept_id\[\]=G1000000002-CMR_PROV1"

Find granule by echo granule id

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?echo_granule_id\[\]=G1000000002-CMR_PROV1"

Find granules by parent concept id. concept_id or collection_concept_id can be used interchangeably.

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?concept_id\[\]=C1000000001-CMR_PROV2"
 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?collection_concept_id\[\]=C1000000001-CMR_PROV2"

Find granules by echo collection id

 curl "https://cmr.sit.earthdata.nasa.gov/search/granules?echo_collection_id\[\]=C1000000001-CMR_PROV2"

Find granules by day_night_flag param, supports pattern and ignore_case

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?day_night_flag=night

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?day_night_flag=day

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?day_night=unspecified

Find granules by two_d_coordinate_system parameter.

Note: An alias for the parameter 'two_d_coordinate_system' is 'grid'. As such 'grid' can be used in place of 'two_d_coordinate_system'.

  curl "https://cmr.sit.earthdata.nasa.gov/search/granules?two_d_coordinate_system\[\]=wrs-1:5,10:8-10,0-10:8,12

The parameter expects a coordinate system name and a set of two-d coordinates. The two-d coordinates could be represented either by a single coordinate pair or a pair of coordinate ranges. ':' is used as the separator between the coordinate system name, single coordinate pairs and coordinate range pairs. The coordinates in the single coordinate pair are represented in the format "x,y". And the coordinates in the coordinate range pairs are represented in the format "x1-x2,y1-y2" where x1 and x2 are the bounds of the values for the first coordinate and y1 and y2, for the second coordinate. One can also use single values for each of the two ranges, say "x1" instead of "x1-x2", in which case the upper and lower bound are considered the same. In other words using "x1" for range is equivalent to using "x1-x1". A single query can consist of a combination of individual coordinate pairs and coordinate range pairs. For example, the query above indicates that the user wants to search for granules which have a two_d_coordinate_system whose name is wrs-1 and whose two-d coordinates match(or fall within) at least one of the given pairs: a single coordinate pair (5,10), a range coordinate pair 8-10,0-10 and another single coordinate pair (8,12).

Find granules by provider

This parameter supports pattern, ignore_case and option and.

Find granules matching 'provider' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=ASF"

Find granules matching any of the 'provider' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?provider=ASF&provider=SEDAC"

Find granules by native_id

This parameter supports pattern, ignore_case and option and.

Find granules matching 'native_id' param value

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?native_id=nativeid1"

Find granules matching any of the 'native_id' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?native_id[]=nativeid1&native_id[]=nativeid2"

Find granules by short name

This parameter supports pattern, ignore_case and option and.

Find granules matching any of the 'short_name' param values. The 'short_name' here refers to the short name of the collections corresponding to the granules being searched for.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?short_name=DEM_100M&short_name=MINIMAL"

Find granules matching 'short_name' param value with a pattern.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?short_name=D*&options[short_name][pattern]=true"

Find granules by version

This parameter supports pattern, ignore_case and option and.

Find granules matching the 'short_name' and 'version' param values. The 'short_name' and 'version' here refers to the short name and version of the collections corresponding to the granules being searched for.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?short_name=DEM_100M&version=1"

Find granules matching the given 'short_name' and any of the 'version' param values

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?short_name=DEM_100M&version=1&version=2"

Find granules by entry title

This parameter supports pattern, ignore_case and option and.

Find granules matching 'entry_title' param value. The 'entry_title' here refers to the entry title of the collections corresponding to the granules being searched for.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?entry_title=DatasetId%204"

See under "Find collections by entry title" for more examples of how to use this parameter.

Find granules with temporal

The temporal datetime has to be in yyyy-MM-ddTHH:mm:ssZ format.

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?temporal\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z,30,60&temporal\[\]=2000-01-01T10:00:00Z,,30&temporal\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z"

The first two values of the parameter together define the temporal bounds. See under Temporal Range searches for different ways of specifying the temporal bounds including ISO 8601.

For temporal range search, the default is inclusive on the range boundaries. This can be changed by specifying exclude_boundary option with options[temporal][exclude_boundary]=true. This option has no impact on periodic temporal searches.

Exclude granules from elastic results by echo granule id and concept ids.

Note: more than one id may be supplied in exclude param

Exclude granule by echo granule id

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?echo_granule_id\[\]=G1000000002-CMR_PROV1&echo_granule_id\[\]=G1000000003-CMR_PROV1&echo_granule_id\[\]=G1000000006-CMR_PROV2&exclude\[echo_granule_id\]\[\]=G1000000006-CMR_PROV2"

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?exclude\[echo_granule_id\]\[\]=G1000000006-CMR_PROV2&cloud_cover=-70,120"

Exclude granule by concept id

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?echo_granule_id\[\]=G1000000002-CMR_PROV1&echo_granule_id\[\]=G1000000003-CMR_PROV1&echo_granule_id\[\]=G1000000006-CMR_PROV2&exclude\[concept_id\]\[\]=G1000000006-CMR_PROV2"

Exclude granule by parent concept id

curl "https://cmr.sit.earthdata.nasa.gov/search/granules?echo_granule_id\[\]=G1000000002-CMR_PROV1&echo_granule_id\[\]=G1000000003-CMR_PROV1&echo_granule_id\[\]=G1000000006-CMR_PROV2&exclude\[concept_id\]\[\]=C1000000001-CMR_PROV2"

Sorting Granule Results

Granule results are sorted by ascending provider and start date by default. One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but +(Note: + must be URL encoded as %2B) can be used to explicitly request ascending.

Valid Granule Sort Keys

Examples of sorting by start_date in descending(Most recent data first) and ascending orders(Note: the + must be escaped with %2B):

curl "https://cmr.sit.earthdata.nasa.gov/search/granules/sort_key\[\]=-start_date"
curl "https://cmr.sit.earthdata.nasa.gov/search/granules/sort_key\[\]=%2Bstart_date"

Retrieve concept with a given concept-id or concept-id & revision-id

This allows retrieving the metadata for a single concept. This is only supported for collections and granules. If no format is specified the native format of the metadata will be returned.

By concept id

curl -i  "https://cmr.sit.earthdata.nasa.gov/search/concepts/:concept-id"

By concept id and revision id

curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/:concept-id/:revision-id"

curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1"
curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1.iso"
curl -i -H 'Accept: application/xml' "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1"
curl -i -H 'Accept: application/metadata+xml' "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1"
curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1.json"
curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/C100000-PROV1/1"
curl -i "https://cmr.sit.earthdata.nasa.gov/search/concepts/G100000-PROV1/2.echo10"

Note that attempting to retrieve a revision that is a tombstone is an error and will return a 400 status code.

The following extensions and MIME types are supported by the
/concepts/ resource:

Search with POST

Search collections or granules with query parameters encoded form in POST request body.

curl -i -XPOST https://cmr.sit.earthdata.nasa.gov/search/collections -d "dataset_id[]=Example%20DatasetId&dataset_id[]=Dataset2"

Search Response as Granule Timeline

Granule timeline queries allow clients to find time intervals with continuous granule coverage per collection. The intervals are listed per collection and contain the number of granules within each interval. A timeline search can be performed by sending a GET request with query parameters or a POST request with query parameters form encoded in request body to the granules/timeline route. The utility of this feature for clients is in building interactive timelines. Clients need to display on the timeline where there is granule data and where there is none.

It supports all normal granule parameters. It requires the following parameters.

The response format is in JSON. Intervals are returned as tuples containing three numbers like [949363200,965088000,4]. The two numbers are the start and stop date of the interval represented by the number of seconds since the epoch. The third number is the number of granules within that interval.

Example Request:

curl -i "https://cmr.sit.earthdata.nasa.gov/search/granules/timeline?concept_id=C1-PROV1&start_date=2000-01-01T00:00:00Z&end_date=2002-02-01T00:00:00.000Z&interval=month""

Example Response

[{"concept-id":"C1200000000-PROV1","intervals":[[949363200,965088000,4],[967766400,970358400,1],[973036800,986083200,3],[991353600,1072915200,3]]}]

Retrieve Provider Holdings

Provider holdings can be retrieved as XML or JSON.

All provider holdings

curl "https://cmr.sit.earthdata.nasa.gov/search/provider_holdings.xml"

Provider holdings for a list of providers

curl "https://cmr.sit.earthdata.nasa.gov/search/provider_holdings.json?provider-id\[\]=PROV1&provider-id\[\]=PROV2"

Search with JSON Query

Search for collections with JSON in a POST request body. The JSON must conform to the schema
that is defined in https://cmr.sit.earthdata.nasa.gov/search/site/JSONQueryLanguage.json. Only collection search is
supported, not granule search.

curl -XPOST -H "Content-Type: application/json" https://cmr.sit.earthdata.nasa.gov/search/collections
-d '{"condition": { "and": [{ "not": { "or": [{ "provider": "TEST" },
                                              { "and": [{ "project": "test-project",
                                                          "platform": {"short_name": "mars-satellite"}}]}]}},
                            { "bounding_box": [-45,15,0,25],
                              "science_keywords": { "category": "EARTH SCIENCE" }}]}}'

Search with AQL

Search collections or granules with AQL in POST request body. The AQL must conform to the schema
that is defined in https://cmr.sit.earthdata.nasa.gov/search/site/IIMSAQLQueryLanguage.xsd.

curl -i -XPOST -H "Content-Type: application/xml" https://cmr.sit.earthdata.nasa.gov/search/concepts/search -d '<?xml version="1.0" encoding="UTF-8"?>
<query><for value="collections"/><dataCenterId><all/></dataCenterId>
<where><collectionCondition><shortName><value>S1</value></shortName></collectionCondition></where></query>'

Document Scoring

Collection search results are scored when any of the following parameters are searched:

Any terms found in the those parameters are used to score results across other fields in the search results. A term is a contiguous set of characters not containing whitespace. A series of filters are executed against each document. Each of these has an associated boost value. The boost values of all the filters that match a given document are multiplied together to get the final document score.

The terms are separated between keywords found in the keywords field and additional terms found in the fields listed above.

The filters are case insensitive, support wild-cards * and ?, and are given below:

  1. All keyword terms are contained in the long-name field OR one of the keyword terms exactly matches the short-name field OR one of the additional terms is contained in the short-name or long-name - weight 1.4
  2. The keyword term field is a single string that exactly matches the entry-id field OR one of the additional terms is contained in the entry-id - weight 1.4
  3. All keyword terms are contained in the Project/long-name field OR one of the keyword terms exactly matches the Project/short-name field OR one of the additional terms is contained in the Project/short-name or Project/long-name - weight 1.3
  4. All keyword terms are contained in the Platform/long-name field OR one of the terms exactly matches the Platform/short-name field OR one of the additional terms is contained in the Platform/short-name or Platform/long-name - weight 1.3
  5. All keyword terms are contained in the Platform/Instrument/long-name field OR one of the keyword terms exactly matches the Platform/Instrument/short-name field OR one of the additional terms is contained in the Platform/Instrument/short-name or Platform/Instrument/long-name - weight 1.2
  6. All keyword terms are contained in the Platform/Instrument/Sensor/long-name field OR one of the keyword terms exactly matches the Platform/Instrument/Sensor/short-name field OR one of the additional terms is contained in the Platform/Instrument/Sensor/short-name or Platform/Instrument/Sensor/long-name - weight 1.2
  7. The keyword term field is a single string that exactly matches the science-keyword field OR an additional term is contained in the science-keyword field - weight 1.2
  8. The keyword term field is a single string that exactly matches the spatial-keyword field OR an additional term is contained in the spatial-keyword field - weight 1.1
  9. The keyword term field is a single string that exactly matches the temporal-keyword field OR an additional term is contained in the temporal-keyword field - weight 1.1

Facets

Facets are counts of unique values from fields in items matching search results. Facets are supported with collection search results and are enabled with the include_facets parameter. There are three different types of facet responses. There are flat facets, hierarchical facets, and v2 (as in version two) facets.

Flat and hierarchical facets are supported on all collection search response formats except for the opendata response format. When echo_compatible=true parameter is also present, the facets are returned in the catalog-rest search_facet style in XML or JSON format.

Several fields including science keywords, data centers, platforms, instruments, and location keywords can be represented as either flat or hierarchical fields. By default facets are returned in a flat format showing counts for each nested field separately. In order to retrieve hierarchical facets pass in the parameter hierarchical_facets=true.

Version 2 Facets Response Format

Version 2 facets are enabled by setting the include_facets=v2 parameter. With version 2 facets the CMR makes no guarantee of which facets will be present, whether the facets returned are hierarchical or flat in nature, how many values will be returned for each field, or that the same facets will be returned from release to release. The rules for processing v2 facets are as follows.

The collection response will contain a field, "facets" containing the root node of the facets tree structure. Every node in the tree structure contains the following minimal structure:

var treeNode = {
  "title": "Example",         // A human-readable representation of the node
  "type": "group|filter|..."  // The type of node represented
};

Currently, the filter response type defines two node types: "group" and "filter". More may be added in the future, and clients must be built to ignore unknown node types.

Group Nodes

Group nodes act as containers for similar data. Depending on context, this data may, for instance, be all facet parameters (the root facet node), top-level facets, or children of existing facets. Group nodes further have a

var groupNode = { // Inherits treeNode fields
  "applied": true,            // true if the filter represented by this node (see Filter Nodes) or any of its descendants has been applied to the current query
  "has_children": true,       // true if the tree node has child nodes, false otherwise
  "children": [               // List of child nodes, provided at the discretion of the CMR (see below)
  ]
}

Children

In order to avoid sending unnecessary information, the CMR may in the future opt to not return children for group nodes that have facets, returning only the first few levels of the facet tree. It will, however, allow clients to appropriately display incomplete information and query the full tree as necessary.

Relevance

By default, clients should assume that the CMR may limit facet results to only include the most relevant child nodes in facet responses. For instance, if there are hundreds of science keywords at a particular depth, the CMR may choose to only return those that have a substantial number of results. When filtering children, the CMR makes no guarantees about the specific quantities or values of facets returned, only that applied filters attempt to surface the choices that typical users are most likely to find beneficial.

Filter Nodes

Filter nodes are group nodes that supply a single query condition indicated by a string (the node title). They further have a field, "applied," which indicates if the query value has already been applied to the current query.

var filterNode = { // Inherits groupNode fields
  "count": 1234,                                                          // Count of results matching the filter
  "links": {
    "apply": "https://cmr.sit.earthdata.nasa.gov/search/collections?instrument[]=MODIS", // A URL containing the filter node applied to the current query. Returned only if the node is not applied.
    "remove": "https://cmr.sit.earthdata.nasa.gov/search/collections"                    // A URL containing the filter node removed from the current query. Returned only if the node is applied.
  },
}

Note that while two potential queries are listed in "links", in practice only one would be returned based on whether the node is currently applied.

Full Example

The following example is a sample response for a query using the query parameters API which has the "instruments=ASTER" filter applied as well as a page size of 10 applied by the client. The example is hand-constructed for example purposes only. Real-world queries would typically be more complex, counts would be different, and the facet tree would be much larger.

{
  "facets": {
    "title": "Browse Collections",
    "type": "group",
    "applied": true, // NOTE: true because the tree does have a descendant node that has been applied
    "has_children": true,
    "children": [
      {
        "title": "Instruments",
        "type": "group",
        "applied": true,
        "has_children": true,
        "children": [
          {
            "title": "MODIS",
            "type": "filter",
            "applied": false,
            "count": 200,
            "links": { "apply": "https://example.com/search/collections?page_size=10&instruments[]=ASTER&instruments[]=MODIS" },
            "has_children": false
          },
          {
            "title": "ASTER",
            "type": "filter",
            "applied": true,
            "count": 2000,
            "links": { "remove": "https://example.com/search/collections?page_size=10" }, // NOTE: Differing response for an applied filter
            "has_children": false
          }
        ]
      },
      {
        "title": "Keywords",
        "type": "group",
        "applied": false,
        "has_children": true,
        "children": [
          {
            "title": "EARTH SCIENCE",
            "type": "filter",
            "applied": false,
            "count": 1500,
            "links": { "apply": "https://example.com/search/collections?page_size=10&instruments[]=ASTER&science_keywords[0][category_keyword]=EARTH%20SCIENCE" },
            "has_children": true,
            "children": [ // NOTE: This is an example of how the CMR may handle children at different levels of a hierarchy.
              {           //       For usability reasons, this should only be done if absolutely necessary, preferring to just collapse the hierarchy when possible
                "title": "Topics",
                "type": "group",
                "applied": false,
                "has_children": true,
                "children": [
                  {
                    "title": "OCEANS",
                    "type": "filter",
                    "applied": false,
                    "count": 500,
                    "links": { "apply": "https://example.com/search/collections?page_size=10&instruments[]=ASTER&science_keywords[0][category_keyword]=EARTH%20SCIENCE&science_keywords[0][topic]=OCEANS" },
                    "has_children": true // NOTE: The node has children, but the CMR has opted not to return them
                  }
                ]
              },
              {
                "title": "Variables",
                "type": "group",
                "applied": false,
                "has_children": true,
                "children": [
                  {
                    "title": "WOLVES",
                    "type": "filter",
                    "applied": false,
                    "count": 2,
                    "links": { "apply": "https://example.com/search/collections?page_size=10&instruments[]=ASTER&science_keywords[0][detailed_variable]=WOLVES" },
                    "has_children": false
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
};

Humanizers

Humanizers define the rules that are used by CMR to provide humanized values for various facet fields and also support other features like improved relevancy of faceted terms. The rules are defined in JSON. Operators with Admin privilege can update the humanizer instructions through the update humanizer API.

Updating Humanizers

Humanizers can be updated with a JSON representation of the humanizer rules to https://cmr.sit.earthdata.nasa.gov/search/humanizers along with a valid ECHO token. The response will contain a concept id and revision id identifying the set of humanizer instructions.

curl -XPUT -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/humanizers -d \
'[{"type": "trim_whitespace", "field": "platform", "order": -100},
  {"type": "alias", "field": "platform", "source_value": "AM-1", "replacement_value": "Terra", "reportable": true, "order": 0}]'

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 48

{"concept_id":"H1200000000-CMR","revision_id":2}
Retrieving Humanizers

The humanizers can be retrieved by sending a GET request to https://cmr.sit.earthdata.nasa.gov/search/humanizers.

curl -i https://cmr.sit.earthdata.nasa.gov/search/humanizers?pretty=true

HTTP/1.1 200 OK
Content-Length: 224
Content-Type: application/json; charset=UTF-8

[ {
  "type" : "trim_whitespace",
  "field" : "platform",
  "order" : -100
}, {
  "type" : "alias",
  "field" : "platform",
  "source_value" : "AM-1",
  "replacement_value" : "Terra",
  "reportable" : true,
  "order" : 0
} ]

Humanizers Report

The humanizers report provides a list of fields that have been humanized in CSV format. The report format is: provider, concept id, product short name, product version, original field value, humanized field value.

curl "https://cmr.sit.earthdata.nasa.gov/search/humanizers/report"

Note that this report is currently generated every 24 hours with the expectation that this more than satisfies weekly usage needs.

An administrator with INGEST_MANAGEMENT_ACL update permission can force the report to be regenerated by passing in a query parameter regenerate=true.

Facets in XML Responses

Facets in XML search response formats will be formatted like the following examples. The exception is ATOM XML which is the same except the tags are in the echo namespace.

Flat XML Facets
<facets>
  <facet field="data_center">
    <value count="28989">LARC</value>
    <value count="19965">GSFC</value>
  </facet>
  <facet field="archive_center">
    <value count="28989">LARC</value>
    <value count="19965">GSFC</value>
  </facet>
  <facet field="project">
    <value count="245">MANTIS</value>
    <value count="132">THUNDER</value>
    <value count="13">Mysterio</value>
  </facet>
  <facet field="platform">
    <value count="76">ASTER</value>
  </facet>
  <facet field="instrument">
    <value count="2">MODIS</value>
  </facet>
  <facet field="sensor">...</facet>
  <facet field="two_d_coordinate_system_name">...</facet>
  <facet field="processing_level_id">...</facet>
  <facet field="category">...</facet>
  <facet field="topic">...</facet>
  <facet field="term">...</facet>
  <facet field="variable_level_1">...</facet>
  <facet field="variable_level_2">...</facet>
  <facet field="variable_level_3">...</facet>
  <facet field="detailed_variable">...</facet>
</facets>
Hierarchical XML Facets

Fields that are not hierarchical are returned in the same format as the flat response, but hierarchical fields are returned in a nested structure. Fields which are returned hierarchically include platforms, instruments, data centers, archive centers, and science keywords.

<facets>
  <facet field="project"/>
  ...
  <facet field="science_keywords">
    <facet field="category">
      <value-count-maps>
        <value-count-map>
          <value count="31550">EARTH SCIENCE</value>
          <facet field="topic">
            <value-count-maps>
              <value-count-map>
                <value count="8166">ATMOSPHERE</value>
                <facet field="term">
                  <value-count-maps>
                    <value-count-map>
                      <value count="785">AEROSOLS</value>
                    </value-count-map>
                  </value-count-maps>
                </facet>
              </value-count-map>
              <value-count-map>
                <value count="10269">OCEANS</value>
                <facet field="term">
                  <value-count-maps>
                    <value-count-map>
                      <value count="293">AQUATIC SCIENCES</value>
                    </value-count-map>
                  </value-count-maps>
                </facet>
              </value-count-map>
            </value-count-maps>
          </facet>
        </value-count-map>
      </value-count-maps>
    </facet>
  </facet>
</facets>

Facets in JSON Responses

Facets in JSON search response formats will be formatted like the following examples.

Flat JSON facets
{
  "feed": {
    "entry": [...],
    "facets": [{
      "field": "data_center",
      "value-counts": [
        ["LARC", 28989],
        ["GSFC", 19965]
      ]
    }, {
      "field": "archive_center",
      "value-counts": [
        ["LARC", 28989],
        ["GSFC", 19965]
      ]
    }, {
      "field": "project",
      "value-counts": [
        ["MANTIS", 245],
        ["THUNDER", 132],
        ["Mysterio", 13]
      ]
    }, {
      "field": "platform",
      "value-counts": [["ASTER", 76]]
    }, {
      "field": "instrument",
      "value-counts": [["MODIS", 2]]
    }, {
      "field": "sensor",
      "value-counts": [...]
    }, {
      "field": "two_d_coordinate_system_name",
      "value-counts": [...]
    }, {
      "field": "processing_level_id",
      "value-counts": [...]
    }, {
      "field": "category",
      "value-counts": [...]
    }, {
      "field": "topic",
      "value-counts": [...]
    }, {
      "field": "term",
      "value-counts": [...]
    }, {
      "field": "variable_level_1",
      "value-counts": [...]
    }, {
      "field": "variable_level_2",
      "value-counts": [...]
    }, {
      "field": "variable_level_3",
      "value-counts": [...]
    }, {
      "field": "detailed_variable",
      "value-counts": [...]
    }]
  }
}
Hierarchical JSON facets

Fields that are not hierarchical are returned in the same format as the flat response, but hierarchical fields are returned in a nested structure.

    "facets" : [ {
      "field" : "project",
      "value-counts" : [ ]
    ...
    }, {
      "field" : "science_keywords",
      "subfields" : [ "category" ],
      "category" : [ {
        "value" : "EARTH SCIENCE",
        "count" : 31550,
        "subfields" : [ "topic" ],
        "topic" : [ {
          "value" : "ATMOSPHERE",
          "count" : 8166,
          "subfields" : [ "term" ],
          "term" : [ {
            "value" : "AEROSOLS",
            "count" : 785 } ]
          }, {
          "value" : "OCEANS",
          "count" : 10269,
          "subfields" : [ "term" ],
          "term" : [ {
            "value" : "AQUATIC SCIENCES",
            "count" : 293
          } ]
        } ]
      } ]
    } ]

Search for Tiles

Tiles are geographic regions formed by splitting the world into rectangular regions in a projected coordinate system such as Sinusoidal Projection based off an Authalic Sphere. CMR supports searching of tiles which fall within a geographic region defined by a given input geometry. Currently, only tiles in MODIS Integerized Sinusoidal Grid(click here for more details on the grid) can be searched. The input geometry could be either a minimum bounding rectangle or one of point, line or polygon in spherical coordinates. The input coordinates are to be supplied in the same format as in granule and collection spatial searches (See under "Find granules by Spatial").

A query could consist of multiple spatial parameters, two points and a bounding box for example. All the spatial parameters are OR'd in a query meaning a query will return all the tiles which intersect at-least one of the given geometries.

Here are some examples:
Find the tiles which intersect a polygon.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/tiles?polygon=10,10,30,10,30,20,10,20,10,10"

Find the tiles which intersect a bounding rectangle.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/tiles?bounding_box=-10,-5,10,5"

Find the tile which contains a point.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/tiles?point=-84.2625,36.013"

Find all the tiles which a line intersects.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/tiles?line=1,1,10,5,15,9"

The output of these requests is a list of tuples containing tile coordinates, e.g: [[16,8],[16,9],[17,8],[17,9]], in the JSON format. The first value in each tuple is the horizontal grid coordinate(h), i.e. along east-west and the second value is the vertical grid coordinate(v), i.e. along north-south.

Retrieve Controlled Keywords

The keyword endpoint is used to retrieve the full list of keywords for each of the controlled vocabulary fields. The controlled vocabulary is cached within CMR, but the actual source is the GCMD Keyword Management System (KMS). Users of this endpoint are interested in knowing what the CMR considers as the current controlled vocabulary, since it is the cached CMR values that will eventually be enforced on CMR ingest.

The keywords are returned in a hierarchical JSON format. The response format is such that the caller does not need to know the hierarchy, but it can be inferred from the results. Keywords are not guaranteed to have values for every subfield in the hierarchy, so the response will indicate the next subfield below the current field in the hierarchy which has a value. It is possible for the keywords to have multiple potential subfields below it for different keywords with the same value for the current field in the hierarchy. When this occurs the subfields property will include each of the subfields.

Supported keywords include platforms, instruments, projects, temporal_keywords, location_keywords, science_keywords, archive_centers, and data_centers. The endpoint also supports providers which is an alias to data_centers and spatial_keywords which is an alias to location_keywords.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/keywords/instruments?pretty=true"

Example Response

{
  "category" : [ {
    "value" : "Earth Remote Sensing Instruments",
    "subfields" : [ "class" ],
    "class" : [ {
      "value" : "Active Remote Sensing",
      "subfields" : [ "type" ],
      "type" : [ {
        "value" : "Altimeters",
        "subfields" : [ "subtype" ],
        "subtype" : [ {
          "value" : "Lidar/Laser Altimeters",
          "subfields" : [ "short_name" ],
          "short_name" : [ {
            "value" : "ATM",
            "subfields" : [ "long_name" ],
            "long_name" : [ {
              "value" : "Airborne Topographic Mapper",
              "uuid" : "c2428a35-a87c-4ec7-aefd-13ff410b3271"
            } ]
          }, {
            "value" : "LVIS",
            "subfields" : [ "long_name" ],
            "long_name" : [ {
              "value" : "Land, Vegetation, and Ice Sensor",
              "uuid" : "aa338429-35e6-4ee2-821f-0eac81802689"
            } ]
          } ]
        } ]
      } ]
    }, {
      "value" : "Passive Remote Sensing",
      "subfields" : [ "type" ],
      "type" : [ {
        "value" : "Spectrometers/Radiometers",
        "subfields" : [ "subtype" ],
        "subtype" : [ {
          "value" : "Imaging Spectrometers/Radiometers",
          "subfields" : [ "short_name" ],
          "short_name" : [ {
            "value" : "SMAP L-BAND RADIOMETER",
            "subfields" : [ "long_name" ],
            "long_name" : [ {
              "value" : "SMAP L-Band Radiometer",
              "uuid" : "fee5e9e1-10f1-4f14-94bc-c287f8e2c209"
            } ]
          } ]
        } ]
      } ]
    } ]
  }, {
    "value" : "In Situ/Laboratory Instruments",
    "subfields" : [ "class" ],
    "class" : [ {
      "value" : "Chemical Meters/Analyzers",
      "subfields" : [ "short_name" ],
      "short_name" : [ {
        "value" : "ADS",
        "subfields" : [ "long_name" ],
        "long_name" : [ {
          "value" : "Automated DNA Sequencer",
          "uuid" : "554a3c73-3b48-43ea-bf5b-8b98bc2b11bc"
        } ]
      } ]
    } ]
  } ]
}

Find collections that have been deleted after a given date

To support metadata harvesting, a harvesting client can search CMR for collections that are deleted after a given date. The only search parameter supported is revision_date and its format is slightly different from the revision_date parameter in regular collection search in that only one revision date can be provided and it can only be a starting date, not a date range. The only supported result format is xml references. The response is the references to the highest non-tombstone collection revisions of the collections that are deleted. e.g.

The following search will return the last revision of the collections that are deleted since 01/20/2017.

curl -i "https://cmr.sit.earthdata.nasa.gov/search/deleted-collections?revision_date=2017-01-20T00:00:00Z&pretty=true"

Example Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
CMR-Hits: 3

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <hits>3</hits>
    <took>10</took>
    <references>
        <reference>
            <name>Dataset1</name>
            <id>C1200000001-PROV1</id>
            <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000001-PROV1/4</location>
            <revision-id>4</revision-id>
        </reference>
        <reference>
            <name>Dataset2</name>
            <id>C1200000002-PROV1</id>
            <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000002-PROV1/1</location>
            <revision-id>1</revision-id>
        </reference>
        <reference>
            <name>Dataset3</name>
            <id>C1200000003-PROV1</id>
            <location>https://cmr.sit.earthdata.nasa.gov/search/concepts/C1200000003-PROV1/8</location>
            <revision-id>8</revision-id>
        </reference>
    </references>
</results>

Tagging

Tagging allows arbitrary sets of collections to be grouped under a single namespaced value. The sets of collections can be recalled later when searching by tag fields.

Tags have the following fields:

Tag Access Control

Access to tags is granted through the TAG_ACL system object identity. Users can only create, update, or delete a tag if they are granted the appropriate permission in ECHO. Associating and dissociating collections with a tag is considered an update.

Creating a Tag

Tags are created by POSTing a JSON representation of a tag to https://cmr.sit.earthdata.nasa.gov/search/tags along with a valid ECHO token. The user id of the user associated with the token will be used as the originator id. The response will contain a concept id identifying the tag along with the tag revision id.

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags -d \
'{
  "tag_key": "org.ceos.wgiss.cwic.quality",
  "description": "This is a sample tag."
 }'

HTTP/1.1 201 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 48

{"concept_id":"T1200000000-CMR","revision_id":1}

Retrieving a Tag

A single tag can be retrieved by sending a GET request to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key> where tag-key is the tag key of the tag.

curl -i https://cmr.sit.earthdata.nasa.gov/search/tags/org.ceos.wgiss.cwic.quality?pretty=true

HTTP/1.1 200 OK
Content-Length: 216
Content-Type: application/json;charset=ISO-8859-1

{
  "originator_id" : "mock-admin",
  "tag_key": "org.ceos.wgiss.cwic.quality",
  "description" : "This is a sample tag for indicating some data is high quality."
}

Updating a Tag

Tags are updated by sending a PUT request with the JSON representation of a tag to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key> where tag-key is the tag key of the tag. The same rules apply when updating a tag as when creating it but in addition tag key and originator id cannot be modified. The response will contain the concept id along with the tag revision id.

curl -XPUT -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/org.ceos.wgiss.cwic.quality -d \
'{
  "tag_key": "org.ceos.wgiss.cwic.quality",
  "description": "This is a sample tag for indicating some data is high quality."
 }'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 48

{"concept_id":"T1200000000-CMR","revision_id":2}

Deleting a Tag

Tags are deleted by sending a DELETE request to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key> where tag-key is the tag key of the tag. Deleting a tag creates a tombstone that marks the tag as deleted. The concept id of the tag and the revision id of the tombstone are returned from a delete request. Deleting a tag dissociates all collections with the tag.

curl -XDELETE -i  -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/org.ceos.wgiss.cwic.quality

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 48

{"concept_id":"T1200000000-CMR","revision_id":3}

Tag Association

A tag can be associated with collections through either a JSON query or a list of collection concept revisions. Tag association by query only supports tagging the latest revision of collections. Tag association by collections supports tagging any specified collection revisions. The tag association request normally returns status code 200 with a response consists of a list of individual tag association responses, one for each tag association attempted to create. Each individual tag association response has a tagged_item field and either a tag_association field with the tag association concept id and revision id when the tag association succeeded or an errors field with detailed error message when the tag association failed. The tagged_item field value has the collection concept id and the optional revision id that is used to identify the collection during tag association. Here is a sample tag association request and its response:

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/org.ceos.wgiss.cwic.native_id/associations -d \
'[{"concept_id": "C1200000005-PROV1", "data": "Global Maps of Atmospheric Nitrogen Deposition, 2016"},
  {"concept_id": "C1200000006-PROV1", "data": "Global Maps of Atmospheric Nitrogen Deposition"}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "tag_association":{
      "concept_id":"TA1200000009-CMR",
      "revision_id":1
    },
    "tagged_item":{
      "concept_id":"C1200000005-PROV1"
    }
  },
  {
    "errors":[
      "Collection [C1200000006-PROV1] does not exist or is not visible."
    ],
    "tagged_item":{
      "concept_id":"C1200000006-PROV1"
    }
  }
]

On occassions when tag association cannot be processed at all due to invalid input, tag association request will return a failure status code. e.g.

Status code 400 is returned when:
* content type is unsupported
* request body is invalid json

Status code 404 is returned when:
* the tag with the given tag key does not exist
* the tag with the given tag key has been deleted

Status code 422 is returned when:
* request body is empty
* there are conflicts of tagging on collection level and collection revision in the same request

Associating Collections with a Tag by query

Tags can be associated with collections by POSTing a JSON query for collections to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key>/associations/by_query where tag-key is the tag key of the tag. All collections found will be added to the current set of associated collections with a tag. Tag associations are maintained throughout the life of a collection. If a collection is deleted and re-added it will maintain its tags.

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/edsc.in_modaps/associations/by_query -d \
'{
  "condition": {"provider": "PROV1"}
 }'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "tag_association":{
      "concept_id":"TA1200000009-CMR",
      "revision_id":1
    },
    "tagged_item":{
      "concept_id":"C1200000000-PROV1"
    }
  },
  {
    "tag_association":{
      "concept_id":"TA1200000008-CMR",
      "revision_id":1
    },
    "tagged_item":{
      "concept_id":"C1200000001-PROV1"
    }
  }
]

Associating Collections with a Tag by collection concept ids and optional revision ids

Tags can be associated with collections by POSTing a JSON array of collection concept-ids and optional revision ids to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key>/associations where tag-key is the tag key of the tag. User can also provide arbitrary JSON data which is optional during tag association. The max length of JSON data used for tag association is 32KB. All referenced collections will be added to the current set of associated collections with a tag. Tag associations are maintained throughout the life of a collection. If a collection is deleted and re-added it will maintain its tags. If a tag is already associated with a collection without revision, it cannot be associated with a specific revision of that collection again, and vice versa. Tags cannot be associated on tombstoned collection revisions.

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/gov.nasa.gcmd.review_status/associations -d \
'[{"concept_id": "C1200000005-PROV1", "revision_id": 2, "data": "APPROVED"},
  {"concept_id": "C1200000006-PROV1", "revision_id": 1, "data": "IN_REVIEW"},
  {"concept_id": "C1200000007-PROV1", "revision_id": 1, "data": "REVIEW_DISPUTED"}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "tag_association":{
      "concept_id":"TA1200000008-CMR",
      "revision_id":1
    },
    "tagged_item":{
      "concept_id":"C1200000005-PROV1",
      "revision_id":2
    }
  },
  {
    "tag_association":{
      "concept_id":"TA1200000009-CMR",
      "revision_id":1
    },
    "tagged_item":{
      "concept_id":"C1200000006-PROV1",
      "revision_id":1
    }
  },
  {
    "errors":[
      "Collection with concept id [C1200000007-PROV1] revision id [1] does not exist or is not visible."
    ],
    "tagged_item":{
      "concept_id":"C1200000007-PROV1",
      "revision_id":1
    }
  }
]

Tag Dissociation

A tag can be dissociated from collections through either a JSON query or a list of collection concept revisions similar to tag association requests. Tag dissociation by query only supports tag dissociation of the latest revision of collections. Tag dissociation by collections supports tag dissociation from any specified collection revisions. The tag dissociation response looks the same as tag association response. It normally returns status code 200 with a response of a list of individual tag dissociation responses, one for each tag association attempted to delete. Each tag dissociation response has a tagged_item field and either a tag_association field with the tag association concept id and revision id when the tag dissociation succeeded or an errors or warnings field with detailed message when the tag dissociation failed or inapplicable. The tagged_item field is the collection concept id and the optional revision id that is used to identify the collection during tag dissociation. Here is a sample tag dissociation request and its response:

curl -XDELETE -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/edsc.in_modaps/associations -d \
'[{"concept_id": "C1200000005-PROV1"},
  {"concept_id": "C1200000006-PROV1"},
  {"concept_id": "C1200000007-PROV1"}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "tag_association":{
      "concept_id":"TA1200000008-CMR",
      "revision_id":2
    },
    "tagged_item":{
      "concept_id":"C1200000005-PROV1"
    }
  },
  {
    "warnings":[
      "Tag [edsc.in_modaps] is not associated with collection [C1200000006-PROV1]."
    ],
    "tagged_item":{
      "concept_id":"C1200000006-PROV1"
    }
  },
  {
    "errors":[
      "Collection [C1200000007-PROV1] does not exist or is not visible."
    ],
    "tagged_item":{
      "concept_id":"C1200000007-PROV1"
    }
  }
]

On occasions when tag dissociation cannot be processed at all due to invalid input, tag dissociation request will return a failure status code. e.g.

Status code 400 is returned when:
* content type is unsupported
* request body is invalid json

Status code 404 is returned when:
* the tag with the given tag key does not exist
* the tag with the given tag key has been deleted

Status code 422 is returned when:
* request body is empty
* there are conflicts of tagging on collection level and collection revision in the same request

Dissociating a Tag from Collections by query

Tags can be dissociated from collections by sending a DELETE request with a JSON query for collections to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key>/associations/by_query where tag-key is the tag key of the tag. All collections found in the query will be removed from the current set of associated collections.

curl -XDELETE -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/edsc.in_modaps/associations/by_query -d \
'{
  "condition": {"provider": "PROV1"}
 }'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "tag_association":{
      "concept_id":"TA1200000007-CMR",
      "revision_id":2
    },
    "tagged_item":{
      "concept_id":"C1200000000-PROV1"
    }
  },
  {
    "tag_association":{
      "concept_id":"TA1200000008-CMR",
      "revision_id":2
    },
    "tagged_item":{
      "concept_id":"C1200000001-PROV1"
    }
  }
]

Dissociating a Tag from Collections by collection concept ids

Tags can be dissociated from collections by sending a DELETE request with a JSON array of collection concept-ids to https://cmr.sit.earthdata.nasa.gov/search/tags/<tag-key>/associations/by_query where tag-key is the tag key of the tag. All collections found in the query will be removed from the current set of associated collections.

curl -XDELETE -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/tags/gov.nasa.gcmd.review_status/associations -d \
'[{"concept_id": "C1200000005-PROV1", "revision_id": 1},
  {"concept_id": "C1200000006-PROV1", "revision_id": 2}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "warnings":[
      "Tag [gov.nasa.gcmd.review_status] is not associated with the specific collection concept revision concept id [C1200000005-PROV1] and revision id [1]."
    ],
    "tagged_item":{
      "concept_id":"C1200000005-PROV1",
      "revision_id":1
    }
  },
  {
    "tag_association":{
      "concept_id":"TA1200000008-CMR",
      "revision_id":2
    },
    "tagged_item":{
      "concept_id":"C1200000006-PROV1",
      "revision_id":2
    }
  }
]

Searching for Tags

Tags can be searched for by sending a request to https://cmr.sit.earthdata.nasa.gov/search/tags.

Tag search results are paged. See Paging Details for more information on how to page through tag search results.

Tag Search Parameters

The following parameters are supported when searching for tags.

Standard Parameters:
Tag Matching Parameters

These parameters will match fields within a tag. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of tag_key[]=key1&tag_key[]=key2.

Tag Search Response

The response is always returned in JSON and includes the following parts.

Tag Search Example
curl -g -i "https://cmr.sit.earthdata.nasa.gov/search/tags?pretty=true&tag_key=org\\.ceos\\.*&options[tag_key][pattern]=true"

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 292

{
  "items" : [ {
    "concept_id" : "T1200000000-CMR",
    "revision_id" : 1,
    "tag_key" : "org.ceos.wgiss.cwic",
    "description" : "This is a sample tag.",
    "originator_id" : "mock-admin"
  } ],
  "took" : 5,
  "hits" : 1
}

Variable

Variable is some of the measurement variables that belongs to collections/granules that can be processed by a service.

Variable have the following fields:

Variable Access Control

Access to variable and variable association is granted through the INGEST_MANAGEMENT_ACL system object identity. Users can only create, update, or delete a variable if they are granted the appropriate permission in ECHO. Associating and dissociating collections with a variable is considered an update.

Variable Association

A variable can be associated with collections through a list of collection concept revisions. The variable association request normally returns status code 200 with a response consists of a list of individual variable association responses, one for each variable association attempted to create. Each individual variable association response has a associated_item field and either a variable_association field with the variable association concept id and revision id when the variable association succeeded or an errors field with detailed error message when the variable association failed. The associated_item field value has the collection concept id and the optional revision id that is used to identify the collection during variable association. Here is a sample variable association request and its response:

curl -XPOST -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/variables/totcldh2ostderr/associations -d \
'[{"concept_id": "C1200000005-PROV1"},
  {"concept_id": "C1200000006-PROV1"}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "variable_association":{
      "concept_id":"VA1200000009-CMR",
      "revision_id":1
    },
    "associated_item":{
      "concept_id":"C1200000005-PROV1"
    }
  },
  {
    "errors":[
      "Collection [C1200000006-PROV1] does not exist or is not visible."
    ],
    "associated_item":{
      "concept_id":"C1200000006-PROV1"
    }
  }
]

On occassions when variable association cannot be processed at all due to invalid input, variable association request will return a failure status code. e.g.

Status code 400 is returned when:
* content type is unsupported
* request body is invalid json

Status code 404 is returned when:
* the variable with the given variable name does not exist
* the variable with the given variable name has been deleted

Status code 422 is returned when:
* request body is empty
* there are conflicts of variable on collection level and collection revision in the same request

Variable Dissociation

A variable can be dissociated from collections through either a JSON query or a list of collection concept revisions similar to variable association requests.

curl -XDELETE -i -H "Content-Type: application/json" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/variables/totcldh2ostderr/associations -d \
'[{"concept_id": "C1200000005-PROV1"},
  {"concept_id": "C1200000006-PROV1"},
  {"concept_id": "C1200000007-PROV1"}]'

HTTP/1.1 200 OK
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 168

[
  {
    "variable_association":{
      "concept_id":"VA1200000008-CMR",
      "revision_id":2
    },
    "associated_item":{
      "concept_id":"C1200000005-PROV1"
    }
  },
  {
    "warnings":[
      "Variable [totcldh2ostderr] is not associated with collection [C1200000006-PROV1]."
    ],
    "associated_item":{
      "concept_id":"C1200000006-PROV1"
    }
  },
  {
    "errors":[
      "Collection [C1200000007-PROV1] does not exist or is not visible."
    ],
    "associated_item":{
      "concept_id":"C1200000007-PROV1"
    }
  }
]

On occasions when variable dissociation cannot be processed at all due to invalid input, variable dissociation request will return a failure status code. e.g.

Status code 400 is returned when:
* content type is unsupported
* request body is invalid json

Status code 404 is returned when:
* the variable with the given variable name does not exist
* the variable with the given variable name has been deleted

Status code 422 is returned when:
* request body is empty
* there are conflicts of variable on collection level and collection revision in the same request

Community Usage Metrics

Community usage metrics are metrics showing how many times a particular version of a collection has been accessed. Storing these metrics offers improved relevancy based on collection popularity. The metrics are obtained from the ESDIS Metrics System (EMS) and ingested into the system through this API.

Updating Community Usage Metrics

Community usage metrics can be updated using the https://cmr.sit.earthdata.nasa.gov/search/community-usage-metrics endpoint with a valid ECHO token. The content is a CSV file obtained from the EMS. The 'Product', 'Version', and 'Hosts' columns are parsed from the CSV file and stored as 'short-name', 'version', and 'access-count' respectively in the CMR. Entries with the same Product (short-name) and Version will have the access count aggregated to form a total access count for that collection and version, stored as one entry in the CMR.

Note that when sending the data, use the --data-binary option so that the linebreaks in the CSV data are not removed. See the example below.

The response will contain a concept id and revision id identifying the set of community usage metrics.

curl -XPUT -i -H "Content-Type: text/csv" -H "Echo-Token: XXXXX" https://cmr.sit.earthdata.nasa.gov/search/community-usage-metrics --data-binary <csv-file-location>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 48

{"concept_id":"H1200000000-CMR","revision_id":2}

Retrieving Community Usage Metrics

The community usage metrics can be retrieved by sending a GET request to https://cmr.sit.earthdata.nasa.gov/search/community-usage-metrics. The metrics are returned in JSON format.

curl -i https://cmr.sit.earthdata.nasa.gov/search/community-usage-metrics?pretty=true

HTTP/1.1 200 OK
Content-Length: 224
Content-Type: application/json; charset=UTF-8

[ {
  "short-name" : "AMSR-L1A",
  "version" : "3",
  "access-count" : 100
}, {
  "short-name" : "MAPSS_MOD04_L2",
  "version" : "1",
  "access-count" : 85
} ]

Administrative Tasks

These tasks require an admin user token with the INGEST_MANAGEMENT_ACL with read or update
permission.

Clear the cache

curl -i -XPOST https://cmr.sit.earthdata.nasa.gov/search/clear-cache

Reset the application to the initial state

Every CMR application has a reset function to reset it back to it's initial state. Currently this only clears the cache so it is effectively the the same as the clear-cache endpoint.

curl -i -XPOST https://cmr.sit.earthdata.nasa.gov/search/reset

Querying caches

Endpoints are provided for querying the contents of the various caches used by the application.
The following curl will return the list of caches:

curl -i https://cmr.sit.earthdata.nasa.gov/search/caches

The following curl will return the keys for a specific cache:

curl -i https://cmr.sit.earthdata.nasa.gov/search/caches/cache-name

This curl will return the value for a specific key in the named cache:

curl -i https://cmr.sit.earthdata.nasa.gov/search/caches/cache-name/cache-key

Check application health

This will report the current health of the application. It checks all resources and services used by the application and reports their health in the response body in JSON format. For resources, the report includes an "ok?" status and a "problem" field if the resource is not OK. For services, the report includes an overall "ok?" status for the service and health reports for each of its dependencies. It returns HTTP status code 200 when the application is healthy, which means all its interfacing resources and services are healthy; or HTTP status code 503 when one of the resources or services is not healthy. It also takes pretty parameter for pretty printing the response.

curl -i -XGET https://cmr.sit.earthdata.nasa.gov/search/health?pretty=true

Example healthy response body:

{
  "echo" : {
    "ok?" : true
  },
  "internal-metadata-db" : {
    "ok?" : true,
    "dependencies" : {
      "oracle" : {
        "ok?" : true
      },
      "echo" : {
        "ok?" : true
      }
    }
  },
  "index-set" : {
    "ok?" : true,
    "dependencies" : {
      "elastic_search" : {
        "ok?" : true
      },
      "echo" : {
        "ok?" : true
      }
    }
  }
}

Example un-healthy response body:

{
  "echo" : {
    "ok?" : true
  },
  "internal-metadata-db" : {
    "ok?" : true,
    "dependencies" : {
      "oracle" : {
        "ok?" : true
      },
      "echo" : {
        "ok?" : true
      }
    }
  },
  "index-set" : {
    "ok?" : false,
    "dependencies" : {
      "elastic_search" : {
        "ok?" : false,
        "problem" : "Unable to get elasticsearch cluster health, caught exception: Connection refused"
        }
      },
      "echo" : {
        "ok?" : true
      }
    }
  }
}