Chapter 2: Getting Started

This chapter will discuss

• creating and managing user accounts
• CMR session management - creating, using, and deleting tokens to provide authorization

If searching for and retrieving publicly available data is the only desired operation, this section can be skipped and the reader can go straight to Chapter 3.

User Accounts

User accounts are used to get access to restricted data, manage privileges, or to interact with other services and tools provided by the CMR or ECHO. User accounts for the CMR system are created and manage by the EARTHDATA Login (URS) system. If you need an account and don't already have one, please click on EARTHDATA Login to create one. Once created you can always go back to EARTHDATA Login to manage it. If you are part of a Data Provider group or other team the team administrator can set up permissions for you to access their restricted data. If you need special privileges you can always contact the CMR operational team at support@earthdata.nasa.gov and they can help you. 

Creating and Managing CMR Sessions

The CMR uses tokens in request messages - the http call to CMR - to validate per request who the requester is and what privileges they have. For most searches, a token is not needed because the metadata records are open to everyone. When certain metadata records are restricted a token is needed so that privileged users can see and access those records.  A Session is nothing more than a series of requests that use the same token meaning that you can use the same token for many requests before you delete it. All tokens expire at the end of a time period; At the time of this writing the duration is 30 days. Because the token is used to track your session, it must be protected by client applications with the same level of security that you use for your login name and password.

To conduct a session the normal steps are:

• Create a token
• Do one or more of the following in any order:
  • Search for records
  • Retrieve records
• Delete the token 

Create a Token

Now that the client partner has created a token, they can search and retrieve records, and conduct other functionality through the CMR or ECHO APIs. This functionality is covered in later chapters of this document. Once finished interacting with the CMR the token can be deleted.

Delete the Token

Interacting with the CMR

The REST way

You can interact with any CMR-REST resource using guest by simply GETing, POSTing, PUTing or DELETEing the resource. Some of these operations will fail if guest does not have the authority to perform them. In cases, where you want to use a registered user you should acquire a CMR token above and attach it as a header to the request you make. For example,

Request headers:
Content-Type: application/xml
CMR-Token: CMR-TOKEN-ID
 
Request:
GET https://api.cmr.nasa.gov/cmr-rest/providers
 
Response headers:
Status Code: 200 OK
 
Response Body:
<?xml version="1.0" encoding="UTF-8"?>
<providers type="array">
  <provider>
   ...
  </provider>
</providers>

The SOAP way

Interacting with the rest of the CMR API follows the same pattern as logging in and logging out except that it requires that you pass a valid CMR token to each operation. The following example shows logging in, retrieving the version number of the CMR system and logging back out.

// Login
String token = authenticationService.login("jdoe", "mypass", new ClientInformation("A Client", "192.168.1.1"), null, null);
// Print out CMR version number.
System.out.println("CMR's version number: " + authenticationService.getCMRVersion(token));
// Logout using token from previous login
authenticationService.logout(token);
token = null;

Chapter 3: Searching for metadata

Client partners can search the CMR for metadata.  Currently clients can search for collection and granule metadata.  In the future clients will also be able to search for metadata describing services, visualizations, parameters (variables), and documents.

CMR Environment URLs

The CMR system has three environments: The Systems Integration Test environment is where the CMR development team tests new functionality. This is the environment that first gets the newest upgrades, but it is the least stable. Once the CMR software has been tested it gets deployed to the User Acceptance Test environment. The environment here is quite stable and it is tested as a system for a couple of weeks before the software is deployed to the operational environment. Client Partners can test their software in either the SIT or UAT environment depending the level of integration and testing. The operational environment is the live system available to users around the world.  All of the examples provided in the rest of the document are using the Systems Integration Test environment.  To run the commands in the other environments just replace the SIT URL with either the UAT or OPS URL to use the API in the respective environments.

Headers

Headers are a part of HTTP requests and for the CMR they provide information such as the content of the message (Content-Type), tokens to allow increased privileges (Echo-Token), the format of the data that gets returned (accept), etc. Content-Type is a standard HTTP header that specifies the content type of the body of the request for POST method messages. Search and retrieval requests support the following Content-Types. If the Content-Type is not specified, XML is assumed.

 Content-Type headers

The Echo-Token allows the CMR to know who is making a request. The Token is in the format of XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.  A token must first be generated as described in the previous section. Once the requester has the token, the token can be placed into the http header for the necessary API calls.

If the caller wishes to control in what format and or specification the data gets returned they can use the Accept header.  The following table lists the valid values.  If this header or an alternative method is not used, the returned outcome will be a reference list of results in XML format.

Accept Headers

For more information about the types please see the CMR API documentation.

Client-Id is another header that allows the client to specify a name.  This helps the CMR operations team monitor query performance per client and it can also make it easier for them to identify your requests if you contact them for assistance.

Following are some examples for using the headers. The purple part of the example will be explained in this section, the rest will be described later:

The following curl command issues a search request with the search parameters contained in a file called searchterms in the current directory. The Content-Type - the specification and format of the searchterms file - is using the json format to specify the search parameters. The accept header states that we want the results as a reference list using the XML format. The Echo-Token header allows the CMR to know who is making the request for authorization purposes. The Client-Id header allows the operations team to monitor performance and allows them to quickly find your requests should you need help.

In the next example a user is issuing a search request using publicly available data and is returned an expanded list of results. Notice that only the Accept header is needed.

In the next example a user is issuing a search request using publicly available data and the default result reference list.  Notice that no headers are needed.

As an alternate to using the Accept header are extensions where the client can use the Type Received name in the query to get the same results. Instead of using "Accept: application/opendata+json", "opendata" can be used at the end of the main query before parameters are specified. 

Other examples use the DIF 10 specification and the ISO specification respectively.

To change what is wanted in the request just replace the header as needed per the tables above.

Results

There are several types of results that can be returned:

1. A reference list of results and 
2. An expanded list of results

The following is an example of a reference list of results

The results specify

1. how many metadata records were found by the "hits" tag
2. how long the query took in milliseconds
3. a list of metadata record results specified by the "reference" tag

With in each reference tag a limited information about the metadata is provided.

1. The metadata name which corresponds to the UMM Entry Title
2. The CMR profile or concept ID -  a CMR generated unique ID.  The ID is encoded by a letter of the profile or concept (C for collection, G for granule, S for service), followed by a CMR generated number, followed by a "-" and then followed by the ID of the metadata provider.
3. The exact CMR location to download the metadata
4. The latest revision number of the metadata record.

The following is an example of an expanded list of results in the ECHO 10 specification using the XML format.

The results specify

1. how many metadata records were found by the "hits" tag
2. how long the query took in milliseconds
3. a list of metadata record results specified by the "result" tag

Within each result tag three attributes are shown about the metadata record followed by the full metadata record. The attributes display the CMR concept id (profile ID), the specification and format of the metadata, and the revision number of the shown metadata record.  For more information about the result specifications and formats available please see the CMR API documentation.

Searching

There are several ways to search the CMR system all using the RESTful principles:

1. Using the API calls and parameters with the GET or POST methods
2. Using a JSON query language with a POST method
3. Using the Alternative Query Language (AQL)

API calls and parameters GET method

The most popular and preferred way is to use the API calls and parameters with the GET or POST methods. For detailed documentation the API documentation is located at https://cmr.earthdata.nasa.gov/search/site/search_api_docs.html.

The CMR uses jetty as its application server and it is currently set to take roughly 500k characters in the URL. 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 method for searching instead of the GET method. First we will describe search using the GET method.

The basic search command is shown in the following example 

The query returns the first 10 publicly available collection results in a reference list using the XML format.  As described in the header section to see restricted data, if you have the privileges you will need to use a token.

There are search parameters that can be applied to provide more functionality.  They are listed below

• page_size - The number of results per page - the default is 10. 0 and 2000 are the minimum and maximum values respectively.  For example: page_size=100 shows 100 result records per page if that many results exist.
• page_num - The page number to return. For example: page_num=1 is the first page of results;  page_num=2 is the second page of results; page_num=10 is the 10th page of results.
• sort_key - Indicates one or more elements to sort on. For example: sort_key[]=platform  (the brackets "[" and "]" may need to be escaped by using the \ character)
• pretty - Returns formatted - readable - results if set to true.  For example pretty=true.  For all the returned examples in this document this flag is used.
• token - Specifies the client token. This is an alternative to using the Echo-Token header.
• echo-compatible - This is used by systems requiring ECHO results. To get the best use out of CMR Client Partners shouldn't use this parameter.

These search parameters are for collection requests only.

• include_has_granules - Includes a has-granules tag or attribute in the response so the client knows if the collection encompasses any granules. E.g. include_has_granules=true
• include_granule_counts - Includes a granule-counts tag or attribute in the response with the number of granules represented by the collection. E.g. include_granule_counts=true
• include_facets - Includes a list of facets and their counts at the end of the results. This is mainly used for collection search displays. E.g. include_facets=true
• include_facets with hierarchical_facets - Includes a list of facets preserving the hierarchical order. This is mainly used for collection search displays. E.g include_facets=true&hierarchical_facets=true

 In next example box we will see a set of examples conducting a basic search with using the search parameters just described. The first example shows a client wanting to see 50 metadata references per page. The second example shows 50 metadata references per page using the formatted print.  The third example shows page 2 of 20 results per page showing full records in the echo 10 specification using formatted print. The fourth example issues a request including token and client id headers and does a basic search sorting the results using the platform element.  The request returns page 2 results of 20 results per page showing full records in the ISO 19115 specification using the XML format in a formatted fashion. As one can see the ? character separates the URL from the search parameters and the search parameters are separated by the & character.  The parameters can be in any order. 

Now to refine our searches we can use another set of search parameters documented in the table below. All of these parameters have the brackets next to them and may need to be escaped (\[\]).  All of CMR time search parameters (temporal, updated_since and revision_date) formats are specified as yyyy-MM-ddTHH:mm:ss.SSSZ format. Where yyyy is year; MM is month; dd is day; T is the date time separator character; HH is the hour; mm is the minute; ss is the second; SSS is the milliseconds (the .SSS can be omitted); and Z specifies Zulu time.  January 2 2000 at 5 seconds and 4 minutes past 3 O'clock in the morning Zulu time is represented as 2000-01-02T03:04:05Z.

In the following example we wish to find all collection metadata records that contain an AQUA platform and we would like the to see only a formatted reference list of results that contain 20 references.

In the next example we wish to find all collection metadata records that contain an AQUA or an AURA platform and we would like the to see only a formatted reference list of results that contain 20 references.

There are a couple of extra options that certain search parameters have to aid the user.  To use these options the syntax is: options[parameter name][option_key]=value. Parameter name is the name of the search parameter to be affected such as platform. Value is either set to true or false.  Option_key is one of the following:

The following is an example of using options with the platform search parameter.  This example will find any platform that matches A followed by any number of alphanumeric characters and ends with A. This will find both platforms of AQUA and AURA. 

This next example demonstrates a user looking to find records that only contain an instrument that matches "HELLO" in uppercase letters.

Besides science_keywords, if any of the parameters that are searched are repeated, the metadata records that have ANY of the values will match.  The following example demonstrates that the CMR system will match any metadata record containing either value.

For a complete set of examples using all of the search parameters please see the API documentation: https://cmr.earthdata.nasa.gov/search/site/search_api_docs.html

API calls and parameters POST method

The API using the POST method is the same as with the GET method with the exception being the method used is POST instead of GET and the parameters are in the body of the message without a length constraint instead of existing in the URL string.  Using the curl command the following example shows the query.xml file that contains the query we want to execute followed by the curl search request. In the query.xml file the parameters can be left as one long set or formatted to be more easily read - so long as syntax remains the same. Also notice in this example we did not escape the brackets ([ ])

query.xml:

Notice in this specific instance that the Content-Type header is not used.  Don't use it, it will cause an error.

JSON query language with a POST method

JSON query language with a POST method

Table 2: Query Return Result Types

Formatting Your Query Results

You can specify a subset of the information in the result set by using different parameters for the operations
ExecuteQuery and GetQueryResults. 
The following elements are used to specify the format and content of a result set:

Table 3: Result Set Content Elements

Metadata results are returned as XML that conforms to one of the following DTDs:

Granule metadata conforms to the Granule Results DTD—refer to Appendix F, Results DTDs (also located at: http://api.cmr.nasa.gov/cmr/dtd/CMRGranuleResults.dtd).
Collection metadata conforms to the Collection Results DTD Appendix F, Results DTDs (also located at: http://api.cmr.nasa.gov/cmr/dtd/CMRCollectionResults.dtd). 
Metadata attributes are made up of two values: the XML metadata attribute name and a primitive type name. The CMR currently ignores the type name. The allowable metadata attribute names are specified in the appropriate DTD (CMRGranuleResults.dtd for granules and CMRCollectionResults.dtd for collections). If you specify a metadata attribute name that has sub-attributes, all of the sub-attributes will be included as well. For example, if you specify Platform, the following elements will be included in the metadata:

• Platform
• PlatformShortName
• Instrument
• InstrumentShortName
• Sensor
• SensorShortName
• SensorCharacteristics
• SensorCharacteristicName
• SensorCharacteristicValue

OperationMode
When you specify a sub-attribute, the CMR will return the ―parent‖ attribute in the hierarchy as well as the sub-attribute. This allows you to ensure that data are correctly scoped. For example, if you specify Sensor, the following elements will be included in the metadata:

• Platform
• PlatformShortName
• Instrument
• InstrumentShortName
• GranuleUR
• GranuleURMetaData

Detailed spatial attributes cannot be used as MetadataAttributes; only their containing element may be specified. For example, you cannot use BoundingBox as a MetadataAttribute, but you can use HorizontalSpatialDomainContainer. The following spatial elements cannot be specified as MetadataAttributes:

• Point
• Circle
• BoundingRectangle
• GPolygon
• Polygon
• PointLongitude
• PointLatitude
• CenterLongitude
• CenterLatitude
• Radius
• WestBoundingCoordinate
• NorthBoundingCoordinate
• EastBoundingCoordinate
• SouthBoundingCoordinate
• Boundary
• ExclusiveZone
• SinglePolygon
• MultiPolygon
• OutRing
• InnerRing

Specifying GranuleURMetaData as a MetadataAttribute is equivalent to not specifying any MetadataAttributes; the result set includes all the elements in the result DTD. 
The following code snippet shows how to execute a query for all of the metadata for matching items.

// Execute a query to get results
QueryResponse response = catalogService.executeQuery(userToken, queryString, ResultType.RESULTS,
    10, // Iterator
    0, // Cursor
    3000, // max results
    null); // no metadata attributes specified
 
MetadataAttribute[] attributes = new MetadataAttribute[] { new MetadataAttribute(
    "HorizontalSpatialDomainContainer", null) };
 
QueryResponse response = catalogService.executeQuery(userToken, queryString, ResultType.RESULTS,
    10, // Iterator
    0, // Cursor
    3000, // max results
    attributes);

Given the CMR's large store of Earth Science data, it is possible for queries to return very large result sets. The CMR supports retrieving the results from a query in a number of ways. The simplest is to ask the CMR to return the results directly from the ExecuteQuery request by passing RESULTS as the ResultType. However, to prevent a single query from monopolizing CMR resources, the CMR limits the number of results available in response to a query. By default, this limit is 2,000 items. CMR Operations may change this limit depending on CMR usage patterns. 
For larger results, the CMR supports a paging mechanism. This allows you to page through the available data in page sizes that you select (up to the CMR Operations configurable limit). For all ResultTypes, the CMR will create and store a result set and return the corresponding GUID. You can page through the result set using the GetQueryResults operation. The arguments to GetQueryResults are similar to ExecuteQuery with the exception that you specify the result set GUID rather than a new query. 
Result sets may change after they are created. Providers are continually changing the data they have registered in the CMR. New records may appear or may be removed from a result set. Because of this, you should watch the fields Cursor and CursorAtEnd when paging through a large result set: 
Cursor specifies the index of the first record to be returned in the result set. For example, a value of 5 will return results starting from the fifth record. If none is specified, it defaults to 1. If you repeat the same query later, use the same Cursor value. 
Use CursorAtEnd to determine when you have reached the end of the result set. This Boolean field is TRUE if the returned results were the last available results in the result set. 
The following code illustrates paging through a result set and displaying it to the user.

final int ITERATOR_SIZE = 10;
try
    {
        CatalogServiceLocator catalogServiceLocator = new CatalogServiceLocator();
        CatalogServicePort catalogService = catalogServiceLocator.getCatalogServicePort();
        QueryResponse response = catalogService.executeQuery(userToken, userQuery,
        ResultType.RESULT_SET_GUID, 0, 0, 1000, null);
        String resultSetGuid = response.getResults().getResultSetGuid();
        // begin paging through results
        int cursor = 1;
        boolean atEnd = false;
        while (!atEnd)
        {
            //Get next ITERATOR_SIZE results
            QueryResults results = catalogService.getQueryResults(userToken,
                resultSetGuid, null, ITERATOR_SIZE, cursor);
            //Print out results
            System.out.println(results.getReturnData());
            //Set cursor to next index
            cursor = results.getCursor();
            //Check if at end of result set
            atEnd = results.isCursorAtEnd();
        }
        System.out.println("All results retrieved");
    }
    catch (CMRFault e)
    {
        e.printStackTrace();
    }
    catch (ServiceException e)
    {
        e.printStackTrace();
    }
    catch (RemoteException e)
    {
        e.printStackTrace();
    }

Visibility of Results

When you execute a query, the query is applied to all the data in the CMR. However, when the results are retrieved, you may not see all of the items. What you can see depends on the rules defined by the Data Partners and the privileges granted to you.

Restricted Items

If a particular item in your result set is restricted for you (i.e., you are not allowed to see it), based on your privileges, it will not be returned.

Deleted Items

It is possible that between the time you execute a query and the time you view the results some of the matched items may have been deleted from the CMR or restricted due to a request from the Data Partner who owns the metadata. In that case, the item will not be returned in your result set. For more information about notification of deleted or restricted order items, refer to section 7.8.1, Restricted or Deleted Order Items.

Querying for Orderable Data

The CMR allows you to exclude from your query data that cannot be ordered. Refer to section 1.1.1.

Searching for Orbit Data

4.4.1 Backtrack Orbit Search Algorithm

Orbit searching is by far the most accurate way to search for level 0-2 orbital swath data. Unfortunately orbital mechanics is a quite difficult field, and the most well known orbit model, the NORAD Propagator, is quite complex. The NORAD Propagator is designed to work with a wide range of possible orbits, from circular to extremely elliptical, and consequently requires quite a bit of information about the orbit to model it well. 
To facilitate earth science, the orbits of satellites gathering earth science data are quite restricted compared to the variety of orbits the NORAD Propagator is designed to work with. Generally, the earth science community would like global coverage, with a constant field of view, at the same time every day. For this reason, most earth science satellites are in a sun-synchronous, near-polar orbit. Even missions that are not interested in global coverage, e.g., the Tropical Rainfall Measuring Mission (TRMM), are still interested in having a constant field of view so the coverage of the sensor is at a constant resolution. For this reason, ALL earth science satellites are in circular orbits. 
The Backtrack Orbit Search Algorithm, designed and developed by Ross Swick, exploits this fact to simplify the orbit model by modeling an orbit as a great circle under which the Earth rotates. This reduces the number of orbital elements required for the model from 22 to three. Moreover, the NORAD Propagator is designed to predict future orbits based on current status, and consequently must be reinitialized periodically to correct for cumulative error as the model spins forward. As the name implies Backtrack spins the orbit backwards, and in practice spins backwards at most one orbit, so there is no cumulative error.
For more information on Backtrack, please see  http://geospatialmethods.org/bosa/.

Figure 2. Typical Orbit Path Represented on a Globe and the same Path on a Map

Backtrack orbit model 

Three parameters to define an orbit: 

1. Instrument swath width (in kilometers)
2. Satellite declination or inclination (in degrees)
3. Satellite period (in minutes)

Orbit data representation

Three parameters to represent orbit data:

1. Equatorial crossing longitude
2. Start circular latitude (or start latitude and start direction)
3. End circular latitude (or end latitude and end direction)

How the CMR Searches for Orbit Data

• The user specifies a regular spatial window

Figure 3. Spatial Window

• Backtrack then calculates from both ascending and descending a path for equatorial longitude crossings and start/end circular latitudes according to user's query window.

Sample queries

The following are sample queries that you can execute against the CMR. Note that the provider and the datasets used in these samples are representative only; you should modify the query to suit your needs. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v{*}10{*})//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd">
<!- Search for collections from ORNL_DAAC that have parameter value that contains 'IMAGERY'--> 
<query>
    <for value="collections"/> 
        <dataCenterId>
            <list>
                <value>ORNL_DAAC</value>
            </list> 
        </dataCenterId>
    <where>
        <collectionCondition>
            <parameter>
                <textPattern>'%Imagery%'</textPattern>
            </parameter>
        </collectionCondition>
    </where>
</query>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v{*}10{*})//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd">
<!-- Search for collections from GSFCECS and ORNL_DAAC that have processing level 1A or 2 --> 
<query>
    <for value="collections"/> 
    <dataCenterId>
        <list>
            <value>GSFCECS</value> 
            <value>ORNL_DAAC</value>
        </list>
    </dataCenterId>
    <where>
        <collectionCondition negated="y"> 
            <processingLevel>
                <list>
                    <value>'1A'</value>
                    <value>'2'</value>
                </list>
            </processingLevel>
        </collectionCondition>
    </where>
</query>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v{*}10{*})//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd">
<!--
 Search for collections from ORNL_DAAC with: temporal range: periodic 
range between Jan 1, 1990 and Dec. 31 1998from the 1st to the 300th day 
of each year, AND spatial extent: bounding box 60S, 70W to 60N, 70E. 
-->
<query>
    <for value="collections"/> 
    <dataCenterId>
        <value>ORNL_DAAC</value> 
    </dataCenterId>
    <where>
        <collectionCondition>
            <temporal>
                <startDate>
                    <Date YYYY="1990" MM="01" DD="01"/> 
                </startDate>
                <stopDate>
                    <Date YYYY="1998" MM="12" DD="31"/> 
                </stopDate>
                <startDay value="1"/> 
                <endDay value="300"/>
            </temporal>
        </collectionCondition> 
        <collectionCondition negated="n">
        <spatial operator="RELATE"> 
            <IIMSPolygon>
                <IIMSLRing>
                    <IIMSPoint long='-10' lat='85'/> <IIMSPoint long='10' lat='85'/> <IIMSPoint long='10' lat='89'/> <IIMSPoint long='-10' lat='89'/> <IIMSPoint long='-10' lat='85'/>
                </IIMSLRing>
            </IIMSPolygon>
        </spatial>
    </collectionCondition>
    </where>
</query>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v{*}10{*})//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd">
<!-- Search for collections from ORNL_DAAC with
temporal range: periodic range between Jan 1, 1990 and Dec. 31 1998 from the 1st to the 300th day of each year, AND
some days of January. source name: L7 or AM-1 AND
spatially covering any 'temperate' region or USA -->
<query>
    <for value="collections"/> 
    <dataCenterId>
        <list>
            <value>ORNL/value>
        </list>
    </dataCenterId>
    <where>
        <collectionCondition>
            <temporal>
                <startDate>
                    <Date YYYY="1990" MM="01" DD="01"/> 
                </startDate>
                <stopDate>
                    <Date YYYY="1998" MM="12" DD="31"/> 
                </stopDate>
                <startDay value="1"/> 
                <endDay value="300"/>
            </temporal>
        </collectionCondition> 
        <collectionCondition negated='n'>
            <sourceName>
                <list>
                    <value>'L7'</value> 
                    <value>'AM-1'</value>
                </list>
            </sourceName>
        </collectionCondition>
        <collectionCondition>
            <spatialKeywords>
                <list>
                    <value>'temperate'</value>
                    <value>'USA'</value>
                </list>
            </spatialKeywords>
        </collectionCondition>
        <collectionCondition>
            <temporalKeywords>
                <textPattern>'%january%'</textPattern>
            </temporalKeywords>
        </collectionCondition>
    </where>
</query>

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE query PUBLIC "-//CMR CatalogService (v10)//EN" 
"http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd"> 
<query>
    <for value="collections"/> 
    <dataCenterId>
        <value>ORNL_DAAC</value> 
    </dataCenterId>
    <where>
        <collectionCondition>
            <additionalAttributeNames>
                <list> 
                    <value>'Provider_Specific_Attribute_1'</value> 
                    <value>'Provider_Specific_Attribute_3'</value>
                </list>
            </ additionalAttributeNames > 
        </collectionCondition>
    </where>
</query>

Chapter 4: Retrieving Metadata

Chapter 5: Alternative Query Language

CMR Alternative Query Language (AQL) is a query language that defines the format for searches on collections and granules in the CMR system. AQL is an XML-based language. You can find the DTD for AQL at http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd or the schema at https://cmr.sit.earthdata.nasa.gov/search/site/IIMSAQLQueryLanguage.xsd.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v10)//EN" 
"http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd"> 
<query> 
    <for value= "collections"/> 
    //"granules" can be substituted for "collections" 
        <dataCenterId> 
            <all/>
        </dataCenterId> 
    <where> 
        <list of conditions ... > 
    </where> 
</query>

There is no discussion regarding the strong suggestion that clients include dataset IDs. Might want to have more high level information regarding the structure of an AQL query and general contructs (list, all, value, etc). 
You can specify the data centers that you wish to search by explicitly listing them or by using the empty element <all/> to indicate that you want all the data centers searched. This is the default condition, that is, if you do not specify a condition for the dataCenterId element, the CMR will search all data centers. Do not enclose dataCenterId values in single-quotes. Is this still needed? 
To search all data providers:

To search for collections/granules in the ORNL data provider's metadata only:

To search for collections/granules in the LPDAAC_ECS data providers' metadata only:

The list of conditions consists of collectionCondition elements for Discovery or granuleCondition elements for Inventory Search. The fields you can search on within collections occur as children of the collectionCondition element. The fields you can search on within granules occur as children of the granuleCondition element. The CMR will return only those granules or collections that satisfy all the conditions of the query, that is, the CMR applies the Boolean AND between all conditions of the query. 
The where tag can have any number of collectionCondition or granuleCondition elements. Each of these tags can contain any one of the search elements listed in the Inventory Search and Discovery Search tables below. For the query to be valid, each of the search elements may appear only once.

Code Listing 15 shows the general structure of a Discovery query with multiple constraints.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v10)//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd"> 
<query> 
    <for value="collections"/> 
        <dataCenterId> 
            <value>ORNL_DAAC</value> 
        </dataCenterId> 
    <where> 
        <collectionCondition>… </collectionCondition> 
        <collectionCondition>… </collectionCondition> 
        …
    </where> 
</query>

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE query PUBLIC "-//CMR CatalogService (v10)//EN" "http://api.cmr.nasa.gov/cmr/dtd/IIMSAQLQueryLanguage.dtd"> 
<query> 
    <for value="granules"/> 
        <dataCenterId> 
            <value>ORNL_DAAC</value> 
        </dataCenterId> 
    <where> 
        <granuleCondition>… </granuleCondition> 
        <granuleCondition>… </granuleCondition> 
        …
    </where> 
</query>

Collection/Discovery Search

Searches for collections must enclose the search criteria in a collectionCondition element. If you want to search the negated criteria, you should set the negated attribute in the collectionCondition element to 'Y'.

Code Listing 17 shows how to create a search for all collections except the ones with processing level 1, 1A, 1B, or 2. 

<collectionCondition negated='Y'> 
    <processingLevel> 
        <list> 
            <value>'1'</value>
            <value caseInsensitive="Y">'1A'</value>
            <value>'1B'</value> 
            <value>'2'</value>
        </list> 
    </processingLevel>
</collectionCondition>

Table 4: Collection Search Criteria (Discovery)

Granule/Inventory Search

Searches for granules must enclose the search criteria in the granuleCondition element. As in the case of collectionCondition, if you want to search the negated criteria, set the negated attribute in the granuleCondition element to 'Y'. You can set the negated attribute to 'Y' for any criterion. 
The following table lists the criteria you can use to search for granules. 

Table 5: Granule Search Criteria (Inventory)

Common Search Elements

You may use the following search criteria for both collection and granule searches. 
Case Insensitive Searching 
Any value or textPattern tag has an attribute caseInsensitive that you can set to Y or N to indicate whether the search value or textPattern is case insensitive. The default is N, that is, the default is case sensitive searching. Refer to the dataSet ID example on the next page for an example. 
CampaignShortName 
CampaignShortName is the name(s) of the campaign or project that gathered data associated with the collection or granule. In CampaignShortName, you can use a single-quoted string in a value, a list of single-quoted strings in a list, or a textPattern element as defined in the section 6.8, Miscellaneous Elements. 
This example shows a search for collections/granules where CampaignShortName = 'River'.

Use CMRLastUpdate to specify a search for collections or granules based on the date of their last update within the CMR. You can only specify a dateRange.

Sensor Name 
Use sensorName to search for collections or granules based on the name of the sensor. known value in a value, a list of known values in a list, or a text pattern in a textPattern. relationship between each value with the Boolean "AND" or "OR".
The "AND" relationship means that results must match every value specified.
You can search for a You can specify the 
The "OR" relationship means that results must match either or both of the values specified. "OR" is the default setting for searching with multiple values.

Instrument Short Name 
Use instrumentShortName to search for collections or granules based on the name of the instrument. You can search for a known value in a value, a list of known values in a list, or a text pattern in a textPattern. You can specify the relationship between each value with the Boolean "AND" or "OR".
The "AND" relationship means that results must match every value specified.
The "OR" relationship means that results must match either or both of the values specified. "OR" is the default setting for searching with multiple values.

Source Name 
Use sourceName to search for collections or granules based on the name of the source. You may specify the name using a value, a list of known values in a list, or a text pattern in a textPattern. You can specify the relationship between each value with the Boolean "AND" or "OR".

The "AND" relationship means that results must match every value specified.

The "OR" relationship means that results must match either or both of the values specified. "OR" is the default setting for searching with multiple values

Spatial

Use spatial constraints to restrict the search within a spatial extent of the earth. Specify the spatial extent using the elements IIMSPolygon, IIMSMultiPolygon, IIMSBox or IIMSLine. 
You may also specify a TwoDCoordinate element along with a spatial element in a spatial constraint. This is useful when you wish to find spatially coincident granules between collections that support TwoDCoordinate searches and those that do not. When you use TwoDCoordinate together with a spatial element, the CMR will return all granules that satisfy either the TwoDCoordinate constraint or the spatial element, or both. You may only use TwoDCoordinate in a spatial constraint for granule (inventory) queries, not collection queries. 
You may also use TwoDCoordinate outside of a spatial constraint. In this case, list TwoDCoordinate inside a granuleCondition. The CMR will return results that satisfy the TwoDCoordinate constraint and all other conditions (including any spatial conditions if they are present). 
A Polygon consists of one or more rings. Some rings may be embedded within others that define the interior of the polygon. The CMR system can handle polygons with only one external ring and multiple internal rings. 

Figure 6: Allowed Geometries for Spatial Data and Query Windows

To define a ring, the last point in the ring must be the same as the first point in the ring. You must specify the points in each polygonal ring in counterclockwise order. 

Figure 7: Order of Points in a Polygonal Ring

To specify multiple outer rings, use the MultiPolygon or IIMSMultiPolygon element, with each outer ring in a separate Polygon. There should be no overlap between any of the outer rings defined. Refer to Code Listing 19: A Multi-Polygon Spatial Query for examples. 
Use IIMSBox to specify a bounding box on the Earth. A bounding box contains two points. The first point is the lower left corner of the box. The second point is the upper right corner of the box. The horizontal lines of the box will follow the latitude lines of the earth. This means the points of the box will not connect by lines following great circle arcs but will curve to stay at the same latitude. 
Use IIMSLine or LString to specify a line on the Earth. You must specify the points in the line from one endpoint to the other. You can also use IIMSPoint to specify a single point on the Earth. Note that although IIMSPoint is used to describe corner points in a polygon or endpoints in a line, it also describes a specific searchable geometry. Refer to Code Listing 20: A Single Point Spatial Query and for examples. 
The table below describes Spatial Operators available in the CMR System, regarding the relationship between two objects.

Table 6: Spatial Operators

                                                                                                                                                               Figure 8: Examples of Spatial Regions

Define the query so that the user-specified spatial extent is the second object in the query.
Use CONTAINS to retrieve granules/collections that contain the specified polygon.
Use WITHIN to retrieve granules/collections that are within the specified spatial extent.
Use RELATE to retrieve granules/collections that overlap in some way. RELATE is the default operator. 
The CMR supports multiple spatial representations (or SpatialTypes). Spatial data of different spatial representations are described differently and hence are stored and queried differently. 
The SpatialType tag is an optional field in AQL used to specify the spatial type. If the user opts not to specify this field, the CMR performs a default search. By default, the CMR performs the search on NORMAL (Cartesian and Geodetic), and ORBIT. 

<spatial operator="RELATE">
    <IIMSPolygon> 
        <IIMSLRing> 
            <IIMSPoint lon="-120" lat="-30" /> 
            <IIMSPoint lon="-100" lat="-60" /> 
            <IIMSPoint lon="5" lat="-90" /> 
            <IIMSPoint lon="-120" lat="-60" /> 
            <IIMSPoint lon="160" lat="5" /> 
            <IIMSPoint lon="160" lat="60" /> 
            <IIMSPoint lon="120" lat="85" /> 
            <IIMSPoint lon="5" lat="85" /> 
            <IIMSPoint lon="-120" lat="30" /> 
            <IIMSPoint lon="-120" lat="-30" /> 
        </IIMSLRing>
        <IIMSLRing> 
            <IIMSPoint lon="80" lat="20" /> 
            <IIMSPoint lon="80" lat="60" /> 
            <IIMSPoint lon="20" lat="60" /> 
            <IIMSPoint lon="20" lat="20" /> 
            <IIMSPoint lon="80" lat="20" />
        </IIMSLRing> 
    </IIMSPolygon>
    <TwoDCoordinateSystem> 
        <TwoDCoordinateSystemName>
            <value>'WRS2'</value>
        </TwoDCoordinateSystemName> 
        <Coordinate1><range lower='15' upper='20'/></Coordinate1> <Coordinate2><range lower='33' upper='42'/></Coordinate2> 
    </ TwoDCoordinateSystem> 
    <SpatialType> 
        <list> 
            <value>NORMAL</value>
            <value>ORBIT</value> 
        </list>
    </SpatialType>
</spatial>

Spatial Type: NORMAL 
Conventional spatial data are described as shapes such as polygons, multi-polygons, boxes, or lines. NORMAL is the spatial type to use for searching this type of data. Spatial data are stored in the database as Oracle objects to record the shape, spatial locations, and coordinate system used; i.e., Cartesian or Geodetic. 
All spatial objects with the exception of Box in AQL, the CMR interprets as Geodetic. Geodetic spatial data has some restrictions. The total area of a single polygon cannot exceed half the earth. Lines, either alone or in a polygon, cannot be longer than half the circumference of the earth. 
The same points in Cartesian and Geodetic describe two different areas. Great circle arcs connect points in Geodetic. These follow the shortest paths on the earth between two points. Latitude lines connect points in Cartesian. The image below shows a geodetic area Google Earth below as a red outlined polygon overlayed over a white polygon representing the Cartesian area described with the same points.

Figure 9: Spatial differences between a Geodetic area and a Cartesian Area 

As noted previously, Geodetic and Cartesian represent polygons in different ways. There are other differences though besides how the lines define the shape. These differences stem from the fact that Geodetic and Cartesian are different representations of the earth. Geodetic is an ellipsoidal model of the earth whereas Cartesian describes the surface of the earth as a flat plane.

Figure 10: Ellipsoid

Figure 11: Flat Cartesian plane

These fundamental differences lead to some polygons being valid in Geodetic and not valid in Cartesian. Polygons and lines follow Geodesics so the CMR uses them as-is for searching geodetic data. Boxes, on the other hand, follow the latitude lines of the earth so the CMR uses them as-is for searching Cartesian data. The CMR converts polygons and lines from Geodetic for searching the Cartesian data and converts boxes from Cartesian when searching Geodetic data. The converted areas are valid approximations of the original areas. The CMR performs the conversion first by dividing the spatial area into pieces so that each new area fits within the bounds of sections of the earth. The CMR uses eight octants when converting from Geodetic to Cartesian. The CMR uses four quadrants when converting from Cartesian to Geodetic. The Cartesian graph below shows the octant bounds. The CMR divides the spatial area so that it does not cross the antimeridian, the prime meridian, or either of the poles.

Figure 12: Bounds of the eight octants 

After dividing the spatial area, the lines of the spatial area are "densified". Densification means that the CMR adds more points along the lines between the original points. This has the effect of making the lines in Cartesian space approximate the lines in geodetic space and vice versa. The CMR adds points every 10 km during densification. We found this number to be a good compromise between performance and accuracy. It is important that client developers understand that the CMR uses an approximation of the area so in a small number of cases there may be some missed or extra results. Images, shown below, illustrate the Geodetic to Cartesian Conversion process.

Figure 13: Example geodetic polygon          

Figure 14: Geodetic polygon divided by octants  

Figure 15: Cartesian polygon before densification

Figure 16: Cartesian polygon after densification 

Spatial Type: ORBIT 
Spatial data are orbit-based and generated from satellites running along orbits. Because an orbit travels at a fixed direction with a fixed declination angle and the covered area is a stripe of fixed width, the spatial coverage of a granule can be derived from the latitude where the granule starts and ends and the crossing longitude on the equator where its orbit originally starts. Thus, the orbit-based spatial data are not stored as shape objects but as the original data. The CMR uses an algorithm called ―Backtrack‖ to perform searches on orbit-based data. Spatial coverage can be as large as the entire earth surface including polar area. The CMR does simple validation against the spatial window to make sure it does not exceed the scope of the earth (the latitude is within the range –90 to 90 and the longitude is within the range –180 to 180). 
There is one limitation in the current implementation: the only supported spatial operator is RELATE. In the CMR, multi-orbit as well as single orbit searches are supported. 
This example shows a multi-polygon spatial query. 

Temporal

Use temporal constraints to specify the temporal extent of the data. The dates are stored as Gregorian dates, and the times are stored in GMT. This search allows only dates in YYYY-DD-MM format. You can specify a range of time represented by beginning and ending dates or a periodic temporal range specified by start date and end date. For a periodic temporal range, you can specify the start and end day of each year. You should use integers between 1 and 365 to specify the start and end dates, with start day =< end day. You can specify the end day as 366, but if the temporal range contains a non-leap year, then an error will be generated. 
This example shows a search for granule/collections whose temporal range overlaps with the time between May 12, 1990, and June 13, 1992.

<temporal> 
    <startDate>
        <Date YYYY="1990" MM="5" DD="12"/>
    </startDate> 
    <stopDate>
        <Date YYYY="1992" MM="2" DD="13"/>
    </stopDate> 
</temporal> 

• May 16 - July 14, 1990

• January 5 - March 5, 1991

• January 5 - February 10, 1992 
  
  

<temporal> 
    <startDate>
        <Date YYYY="1990" MM="5" DD="12"/>
    </startDate> 
    <stopDate>
        <Date YYYY="1992" MM="2" DD="10"/>
    </stopDate> 
    <startDay value="5"/> 
    <endDay value="60"/> 
</temporal> 

<versionId> 
    <value>'0'</value>
</versionId>

 <versionId> 
    <textPattern operator="LIKE">'3.%'</textPattern> 
</versionId> 

<additionalAttributes operator='AND'> 
    <additionalAttribute> 
        <additionalAttributeName>
            'AveragedFocalPlane1Temperature'
        </additionalAttributeName> 
        <additionalAttributeValue> 
            <range lower='169' upper='170'/> 
        </additionalAttributeValue>
    </additionalAttribute>
    <additionalAttribute> 
        <additionalAttributeName>
            'AveragedFocalPlane2Temperature'
        </additionalAttributeName>
        <additionalAttributeValue> 
            <range lower='269' upper='270'/> 
        </additionalAttributeValue>
    </additionalAttribute> 
</additionalAttributes> 

<additionalAttributes operator='OR'> 
    <additionalAttribute>
        <additionalAttributeName> 
            'AveragedFocalPlane1Temperature'
        </additionalAttributeName>
        <additionalAttributeValue> 
            <range lower='169' upper='170'/> 
        </additionalAttributeValue> 
    </additionalAttribute>
    <additionalAttribute>
        <additionalAttributeName> 
            'AveragedFocalPlane2Temperature'
        </additionalAttributeName> 
        <additionalAttributeValue>
            <range lower='269' upper='270'/> 
        </additionalAttributeValue> 
    </additionalAttribute>
</additionalAttributes>

This section describes elements used specifically for collection (Discovery) searches. 

Science Keywords

Use scienceKeywords to specify the science keywords associate with a collection. Science Keywords are based on the GCMD managed list of science keywords. They have the following hierarchical structure Category> Topic > Term > Variable Level 1 > Variable Level 2 > Variable Level 3 > Detailed Variable. A value at any of the specific hierarchy levels can be specified or anykeyword can be used to search all the levels. Science Keywords are all stored in upper case. Queries with science keywords will automatically be changed to upper case for searching. 
If you specify a list or a single value, then the search looks for an exact match between the string specified and the data stored. For example, if the search value is 'IMAGERY' and the data stored has the value 'SATELLITE IMAGERY', the data will not be returned since there was no exact match. In this instance, it is more useful to use the textPattern element for the search. 

<collectionCondition> 
    <scienceKeywords operator="AND">
        <scienceKeyword> 
            <categoryKeyword>
                <value>'category'</value>
            </categoryKeyword> 
            <topicKeyword>
                <value>'topic'</value> 
            </topicKeyword>
            <termKeyword>
                <value>'term'</value> 
            </termKeyword>
            <variableLevel1Keyword> 
                <value>'level1'</value>
            </variableLevel1Keyword>
            <variableLevel2Keyword> 
                <value>'level2'</value>
            </variableLevel2Keyword> 
            <variableLevel3Keyword>
                <value>'level3'</value> 
            </variableLevel3Keyword> 
            <detailedVariableKeyword>
                <value>'detailed'</value> 
            </detailedVariableKeyword>
        </scienceKeyword>
    </scienceKeywords> 
<collectionCondition>

<collectionCondition> 
    <scienceKeywords operator="AND"> 
        <scienceKeyword>
            <anyKeyword>
                <textPattern>'%WATER%'</textPattern> 
            </anyKeyword>
        </scienceKeyword> 
    </scienceKeywords>
<collectionCondition>

Use processingLevel to specify the level at which the data (collection/granule) has been processed, for example, level 0, 1, 1A, 1B, 2, 3, 4. The search can specify one or more processing levels. The values must be single-quoted strings. 
This example shows a search for all collections at processing level 1, 1A, or 1B. 

 <collectionCondition> 
    <processingLevel>
        <list>
            <value>'1'</value> 
            <value>'1A'</value>
            <value>'1B'</value> 
        </list>
    </processingLevel>
</collectionCondition>

 <collectionCondition> 
    <processingLevel> 
        <textPattern operator="LIKE">'1_'</textPattern> 
    </processingLevel> 
</collectionCondition>

Use additionalAttributeName to search for collections based on the names of the additional attributes in the collections. You can search for a known value in a value, a list of known values in a list, or a text pattern in a textPattern. 
This example shows a search for data with an additionalAttributeName value of 1 or 3. 

<collectionCondition>
    <additionalAttributeName> 
        <list>
            <value>'value_1'</value> 
            <value>'value_3'</value> 
        </list>
    </additionalAttributeName>
</collectionCondition> 

Use shortName to specify a search for the short name of collections, which may or may not be unique for a particular provider. 
This example shows a search for all collections that have shortNames starting with ‗BOREAS.' 

<collectionCondition>
    <shortName> 
        <textPattern>'BOREAS%'</textPattern>
    </shortName> 
</collectionCondition>

Use spatialKeywords to specify a word or phrase that summarizes the spatial region covered by the collection. A collection may cover several regions. 
This example shows a search for all collections that cover Africa or Bermuda or the Indian Ocean. 

<collectionCondition>
    <spatialKeywords> 
        <list>
            <value>'Africa'</value> 
            <value>'Bermuda'</value> 
            <value>'Indian Ocean'</value> 
        </list> 
    </spatialKeywords>
</collectionCondition>

<collectionCondition> 
    <spatialKeywords> 
        <textPattern operator="LIKE">'%america%'</textPattern> 
    </spatialKeywords>
</collectionCondition>

Use temporalKeywords to specify a word or phrase that summarizes the temporal characteristics referenced in the collection. 
This example shows a search for all collections that have accumulated data during the spring or fall. 

<collectionCondition> 
    <temporalKeywords>
        <list>
            <value>'spring'</value> 
            <value>'fall'</value>
        </list> 
    </temporalKeywords>
</collectionCondition>

Use archiveCenter to search for collections based on the center where a collection is archived. You may search for a known value in a value, a list of known values in a list, or a text pattern in a textPattern. 

<collectionCondition> 
    <archiveCenter> 
        <value>'ORNL_DAAC'</value> 
    </archiveCenter>
</collectionCondition>

This section describes elements used specifically for granule (Inventory) searches. 

Granules with Browse Data 

Use browseOnly to specify that you want only granules that have browse data available. 

<granuleCondition>
    <browseOnly/> 
</granuleCondition>

Use cloudCover to specify a range of percentage of scene cloud coverage in a granule. For the value in each attribute of the range, you should use a floating number between 0 and 100 that specifies the range in percentage of cloud coverage in a granule. You cannot use the negated condition for this search. 
This example shows a search for only those granules that have cloud cover between 10% and 20%. 

<granuleCondition>
    <cloudCover> 
        <range lower="10" upper="20"/> 
    </cloudCover>
</granuleCondition>

Use dayNightFlag to specify a search for granules that are gathered during daylight only, nighttime only, or both. If you do not specify this criterion, then your results will include granules gathered at all times of day. 
This example shows a search for granules gathered at least partly during daylight. 

<granuleCondition> 
    <dayNightFlag value="DAY"/>
</granuleCondition>

<granuleCondition> 
    <dayNightFlag value="NIGHT"/>
</granuleCondition>

<granuleCondition> 
    <dayNightFlag value="Both"/> 
</granuleCondition>

Use CMRGranuleID to specify an inventory search for specific granules. This search does not need to specify any spatial or temporal constraint. You can use this as a second stage query when you know the list of granules you are interested in from a previous query to hone results. The search is then limited to granules in the list. The list may contain granules from different data sets. The CMR performs the search on CMR_GRANULE_ID, a CMR-wide unique ID. You must enclose the names of the granules in single quotation marks (that is, apostrophes). 

<granuleCondition> 
    <CMRGranuleID> 
        <list> 
            <value>'G1984-ORNL_DAAC'</value>
        </list> 
    </CMRGranuleID>
</granuleCondition>

Use GranuleUR to specify an inventory search for specific granules. Like granule ID, this criterion can be used as a secondary stage query. Instead of using the CMR-specific ID for the granules, this criterion allows you to use the provider-given name for the granules. Provider-given names are more meaningful and easier to remember. Since the granule names given by the provider are not guaranteed to be unique within the CMR, if a granule with the same name exists for more than one dataCenterId specified in the query, all will be returned in the results. You must enclose the names of the granules in single quotation marks (that is, apostrophes). Note that the GranuleUR can contain value, list, textPattern or patternList children. 

<granuleCondition> 
    <GranuleUR> 
        <list> 
            <value>'ACCP_CANOPYCHEM.df_can_calc.dat'</value> 
            <value>'ANGLIA_10YRCLIMATE.cfrs1120.zip'</value>
        </list> 
    </GranuleUR>
</granuleCondition>

Use TwoDCoordinateSystem as an alternative to specifying a spatial or temporal range. For some collections, granules can be located by searching a range of values on a two dimensional grid, (for example, Path/Row for Landsat, X/Y for MODIS Grid data). 
The TwoDCoordinateSystem criterion needs three elements:

• the TwoDCoordinateSystemName

• the Coordinate1 range

• the Coordinate2 range 

Coordinate1 and Coordinate2 may also take a single value. The query returns all granules that match your specified TwoDCoordinateSystemName and overlap with the Coordinate1 and Coordinate2 ranges. Coordinate1 and Coordinate2 ranges must have both lower and upper attributes specified. 
This example shows a search for a range value. 

<granuleCondition> 
    <TwoDCoordinateSystem>
        <TwoDCoordinateSystemName>
            <value>'WRS2'</value> 
        </TwoDCoordinateSystemName> 
        <Coordinate1>
            <range lower='15' upper='20'/>
        </Coordinate1> 
        <Coordinate2>
            <range lower='33' upper='42'/>
        </Coordinate2> 
    </TwoDCoordinateSystem> 
</granuleCondition>

<granuleCondition>
    <TwoDCoordinateSystem> 
        <TwoDCoordinateSystemName> 
            <value>'WRS2'</value>
        </TwoDCoordinateSystemName> 
        <coordinate1>
            <value>15<value/>
        </coordinate1> 
        <coordinate2>
            <range lower='33' upper='42'/>
        </coordinate2> 
    </TwoDCoordinateSystem > 
</granuleCondition>

Use ProducerGranuleID to specify an inventory search for specific granules. ProducerGranuleID represents the ID assigned to data by the Science team that produced the data. Instead of using the CMR-specific IDs for the granules, this criterion allows the user to use the producer's given name for the granules. Granule names are available to the Science teams and are easier to search on. Since the granule names given by the producer are not guaranteed to be unique within the CMR, if a granule with the same name exists for more than one dataCenterId specified in the query, all will be returned in the results. You must enclose the names of the granules in single quotation marks (that is, apostrophes). Note that the ProducerGranuleID can contain value, list, textPattern or patternList children. 

<granuleCondition> 
    <ProducerGranuleID>
        <list>
            <value>'MOD03.A2000107.0930.003.2002056052717.hdf'</value> 
            <value>'MOD01.A2000107.0740.003.2002056051321.hdf'</value>
        </list> 
    </ProducerGranuleID>
</granuleCondition>

Use PGEName to search for granules based on the name of the product generation executive (PGE). You can search for a known value in a value element, a list of known values in a list, or a text pattern in a textPattern. 

<granuleCondition> 
    <PGEName> 
        <value>'test_PGEName'</value> 
    </PGEName>
</granuleCondition>

Use PGEVersion to search for granules based on the version of PGE that originally produced the granule. You can search for a known value in a value element, a list of known values in a list, or a text pattern in a textPattern. 

<granuleCondition> 
    <PGEVersion> 
        <value>'3.0.0'</value> 
    </PGEVersion>
</granuleCondition>

Use collectionShortName to search for granules based on the short name of the collection they belong to. You can search for a known value in a value element, a list of known values in a list, or a text pattern in a textPattern. 

<granuleCondition> 
    <collectionShortName> 
        <value>'MOD03'</value> 
    </collectionShortName>
</granuleCondition>

Use measuredParameters to search for granules based on one or more groups of measured science parameters. You can specify the relationship between groups of parameters with either AND or OR.

An AND relationship means that result granules must match across all groups.

An OR relationship means that result granules can match any of the groups. OR is the default setting. 
Within each measured parameter, you must specify a measuredParameterName in single quotation marks (that is, apostrophes) for exact matching. The detailed measured parameters can be value, list, and textPattern type, or range and dateRange type. 
This example shows a search that specifies an "AND" relationship between two measured parameter groups. 

<granuleCondition>
    <measuredParameters operator="AND"> 
        <measuredParameter> 
            <measuredParameterName>'EV_1KM_RefSB'</measuredParameterName>
            <operationalQualityFlag> 
                <value>'Passed'</value>
            </operationalQualityFlag> 
            <QAPercentOutOfBoundsData> <range lower='30' upper='40'/>
            </QAPercentOutOfBoundsData> 
        </measuredParameter>
        <measuredParameter> 
            <measuredParameterName>'EV_1KM_RefSB'</measuredParameterName> 
                <operationalQualityFlag>
                    <value>'Passed'</value> 
                </operationalQualityFlag>
            <QAPercentOutOfBoundsData>
                <range lower='39' upper='50'/> 
            </QAPercentOutOfBoundsData> 
        </measuredParameter>
    </measuredParameters>
</granuleCondition>

<granuleCondition>
    <measuredParameters operator="OR"> 
        <measuredParameter> 
            <measuredParameterName>'EV_1KM_RefSB'</measuredParameterName>
            <operationalQualityFlag> 
                <value>'Passed'</value>
            </operationalQualityFlag> 
            <QAPercentOutOfBoundsData> <range lower='30' upper='40'/>
            </QAPercentOutOfBoundsData> 
        </measuredParameter>
        <measuredParameter> 
            <measuredParameterName>'EV_1KM_RefSB'</measuredParameterName> 
                <operationalQualityFlag>
                    <value>'Passed'</value> 
                </operationalQualityFlag>
            <QAPercentOutOfBoundsData>
                <range lower='39' upper='50'/> 
            </QAPercentOutOfBoundsData> 
        </measuredParameter>
    </measuredParameters>
</granuleCondition>

Use providerInsertDate to search for granules that are within a desired date-time range. StartDate is a required field, and StopDate is optional. The Date format is:

Where YYYY is year; MM is month, DD is day of the month; HH is hour; MI is minute, and SS is second. 
This example shows a search using providerInsertDate. 

<granuleCondition>
    <providerInsertDate> 
        <dateRange>
            <startDate> 
                <Date YYYY="2001" MM="01" DD="01" HH="00" MI="00" SS="00"/>
            </startDate> 
            <stopDate> 
                <Date YYYY="2003" MM="12" DD="01" HH="23" MI="59" SS="59"/> 
            </stopDate>
        </dateRange> 
    </providerInsertDate>
</granuleCondition>

Use ProviderProductionDate to search for granules that are within a desired date-time range. StartDate is a required field, and StopDate is optional. The Date format is:

This example shows a search of the Data Provider's production date search element. 

<granuleCondition> 
    <providerProductionDate> 
        <dateRange>
            <startDate> 
                <Date YYYY="2001" MM="01" DD="01" HH="00" MI="00" SS="00"/> 
            </startDate>
            <stopDate> 
                <Date YYYY="2003" MM="12" DD="01" HH="23" MI="59" SS="59"/> 
            </stopDate>
        </dateRange> 
    </providerProductionDate>
</granuleCondition>

Use the following elements to search for other elements using AQL. 
List
Use List to specify a list of values. The values may be numbers, dates, or strings. Each individual value must appear as text of the value element. If you specify a list of strings, you must use a single-quoted string with no wild-card characters. The CMR searches the parent element using Oracle's IN operator for an exact match with any value in the list. 
In general, interpretation of the list will be dependent on the parent element in which it appears. 

<list> 
    <value>'Africa'</value> 
    <value>'Bermuda'</value> 
    <value>'Indian Ocean'</value>
</list>

Use patternList to specify a list of text patterns and/or values. See section 6.8.4 for rules associated with values and section 6.8.3 for rules associated with text patterns. 
The values may be numbers, dates, or strings. Each individual value must appear as text of the value element. If you specify a list of string values, you must use a single-quoted string with no wild-card characters. 
The text patterns must conform to the rules specified in section 6.8.3. The CMR searches the parent element using Oracle's IN operator for an exact match with any value in the list. 
In general, interpretation of the list will be dependent on the parent element in which it appears.

Use textPattern to search using the Oracle operator ―LIKE‖ to perform pattern matching. Because of pattern matching, exact specification of what is desired is not needed. The code listing below shows how to invoke the pattern matching. Note that you must specify the operator, and you must use a single-quoted string with or without wild-card characters. 
The wild-card characters supported are '%' and ''. The character ‗%' is a placeholder that represents any number of characters. The character ―‖ is a placeholder that represents a single character.

Table 7: AQL Wildcard Use

You can include the actual characters "%" or "" in the pattern by using the ESCAPE character '\'. If the escape character appears in the pattern before the character "%" or "", then Oracle interprets this character literally in the pattern, rather than as a special pattern-matching character. 

Table 8: Wildcard Examples with ESCAPE Character

If the parent element (collectionCondition or granuleCondition) has the attribute negated with value 'Y', then the search will look for a string NOT like the pattern specified. 

<spatialKeywords>
    <textPattern operator="LIKE" caseInsensitive="Y">'america%'</textPattern> 
</spatialKeywords>

Use value to specify one value. Refer to each individual parent element for a detailed explanation. In general, if the element represents a string pattern, the search will be case sensitive unless the caseInsensitive attribute is set to Y.

Use Date to specify a date value.

Use dateRange to specify a range of time. The range can include just a startDate, just a stopDate or both. If you only include a startDate, the CMR searches for data from that time forward with no stop date. If you only include a stopDate, the CMR searches for data from the current time up until the stop date. If you include both a startDate and a stopDate, then the CMR searches for data falling between those two dates, for example, between January 1, 2005 and January 31, 2005.

Use DifEntryId to find collections by their GCMD (Global Change Master Directory) DIF (Directory Interchange Format) Entry-ID. You can find the GCMD at the following URL:  http://gcmd.nasa.gov.

Accessing data

After identifying data of interest through catalog queries, you may place a request for that data if the data provider(s) allow it. To create an request, it is critical that you understand the parts that make up a request. 
A request is a collection of request items. Each request item consists of:

• The GUID for the catalog item you wish to request
• The quantity of the item you wish to request

Other options associated with the item:
Many catalog items belonging to many different providers may comprise a single order. Each provider may have its own validation scheme and rules for creating, validating, and submitting particular catalog items. To ensure appropriate validation – as well as to demarcate a larger request for sending to each provider – requests are split up into smaller provider requests, sometimes called sub-requests. Each provider request includes all the request items in a particular request that belong to a specific provider. Each provider request has its own provider request GUID, a unique identifier comprised of the GUID of the provider and the GUID of the request that contains the catalog items for this provider. The following figure shows the structure of a request.

CMR Request Structure 

The CMR is designed to support a variety of providers and their various requesting needs, which brings some complexity to the process of request creation. The following figure illustrates the most commonly used and direct approach for creating and submitting a request.

The most common way to obtain the catalog items needed for creating a request is through the ExecuteQuery operation found in the Catalog Service. You can also specify how the results should be displayed. When doing so, ensure that the CatalogItemID tag is returned. The string value under this tag is the actual catalog item GUID that you can use to request items from the CMR.

Access Options 

Access Options use CMR Forms (refer to  http://www.cmr.nasa.gov/data_partners/data_tools10.shtml for more information) for providers to indicate additional information required from users in order to fulfill their orders, such as the media to put the ordered data on and the specific subset of the data to order. Providers assign Order Option definitions to catalog items. When you add an order item to an order that has required order options, it must contain an option selection that corresponds to one of the assigned option definitions for the catalog item you are ordering. See section 1.3 of the CMR Forms Specification for more details. 
To list the possible options for each catalog item, use the GetCatalogItemOrderInfomation operation on the 
OrderManagementService. The operation returns one object called CatalogItemOrderInformation. This contains a list of catalog items and a list of option definitions. Not every option definition in the list applies to every catalog item returned. Each catalog item is associated with zero or more option definition GUIDs, which will be included in the list returned in CatalogItemOrderInformation. Use only one selection from one of the definitions when you add a catalog item to the order. Use your discretion when choosing the definition to use for the order and the selection from within that definition.

The code listing below shows an example of getting the order options for two granules. 

Code Listing 56: Getting Order Options for a Catalog Item

Creating an Order

Once you have collected the catalog item GUIDs and associated options, you can create an order by calling the CreateOrder operation on the OrderManagementService. Simply pass an array of item IDs to add to the order. 
Common Selection 
If you are adding one or more items to an order at the same time, and their selections are the same, you can choose a common selection for the CreateOrder, AddOrderItems, CreateAndSubmitOrder, and UpdateOrderItems operations that will be applied to all order items passed in without an option selection. This reduces the amount of data transmitted to the CMR and is less resource-intensive because the CMR will need to validate the common selection only once. 
For each item in the array, you should set the following parameters:

Parameters on a Catalog Item

The other attributes of Order Item should be empty when creating an order; the CMR will populate them automatically. The CMR will process the request and return a GUID identifying the newly created order. The code listing below shows an example of creating a simple order. 

Code Listing 57: Creating a Simple Order

Adding Order Items 
Once you have created an order, you may add other items to it using the AddOrderItems operation. This operation uses the GUID of the target order and a list of items to add. As with CreateOrder, the options other than those listed in the table above should be empty; the CMR will process the additions and return a list of GUIDs identifying these additions. The code listing below shows an example of adding items to an existing order. 

Code Listing 58: Adding Items to an Existing Order

Updating Order Items
Once you have added an item to an order, you can modify the options or quantity by calling UpdateOrderItems and passing in the modified items. In this case, you must fill in the GUID of each item since the CMR needs to findthe original item in your order to update it. To ensure you are updating the appropriate item with the correct information, follow these steps:

• Call GetOrderItems to populate the data.
• Modify the desired order items.
• Pass the results to UpdateOrderItems.

The code listing below shows an example of updating an existing item.

Code Listing 59: Updating an Item in an Order

Removing Order Items 

You may remove items from an order using the RemoveOrderItems operation as shown below: 

Code Listing 60: Removing an Item from an Order

Removing Orders and Canceling Orders

To delete a specific provider order(s), use the RemoveProviderOrders operation. You cannot delete orders that you have already submitted. For post-submittal orders, a registered user can use the CancelOrder operation on the OrderManagementService to cancel an open order. 
Guest orders cannot be deleted in the post-submittal phase; the CancelOrder operation will delete the entire order, including all associated orders.

Setting User Information for an Order

Every order must have its own user-specific information attached to it so that a data provider can process the order. Contact information, billing, and shipping addresses are all required as well as user domain and region. Each order is independent of other orders, so user information must be set up for each order created. 
You may set up user information at any point in the order process prior to submission. User information is not required until you validate, quote, or submit the order. If the required information is not present at that time, you will receive an error. You can set up user information for an order by calling the SetUserInformationForOrder operation on the OrderManagementService.

Validating an Order

To ensure that an order is complete, with all the required options and user-associated information for that order filled out, the CMR validates all orders when submitted or quoted. If you attempt to submit an invalid order, you will receive an error message. Currently, the message reflects only the first validation error encountered; you need to fix the reported error and revalidate until the order is error-free. At this point, if you change any aspect of the validated order before finally submitting it, then the order will again require validation. To validate orders, call SubmitOrder or QuoteOrder. You can manually validate orders with the ValidateOrder operation in the 
OrderManagementService.

Keep in mind that running the ValidateOrder operation may return a validation error related to one of the many provider-specific validation rules, which may change over time. You should find the error messages complete enough to help you determine what aspects of the order you need to correct. 

Note that validation errors can occur if the order specified does not exist, or does not belong to you.

Requesting a Quote for an Order

Requesting a quote is an optional step that not all providers support. A quoted order provides a binding price for the order as a whole. The binding quote response from each of the necessary providers may take a day or more to receive. You cannot make changes to an order while it is in the quoting process. If you make changes to the order subsequent to the receipt of a quote, the changes may invalidate the quoted price. You may request a quote from a provider by calling QuoteOrder.

Submitting a Data Request

Once you have fully validated a data request and have made no subsequent changes to the request, submit the request to the system using the SubmitOrder operation in the OrderManagementService. 
Specify your preference for receiving order status information using one of the NotificationLevel choices shown in Table 10: CMR Order Notification Levels

CMR Order Notification Levels

If you do not specify any notification level for a registered user's order, the CMR will use your preference value. If you, as a registered user, have not set a preference value, the default value is INFO. The notification for all guests' orders is also INFO. 
Once an order transmits to the system using the SubmitOrder operation, the CMR sends each provider order contained within your order to the appropriate provider. Each provider will decide whether to accept your provider order and how to process it. 

Tracking and Canceling Orders 
From this point on, you can track the status of an order using the GetOrders operation in the OrderManagementService. At any point before the order actually ships, you may request cancellation of the order through the CancelOrder operation. You can then use the GetOrders operation again to track whether you successfully cancelled the order. 
When the CMR sends a request to a provider to quote, submit or cancel a particular order, both the CMR and that provider must have the same ID for that order. The CMR identifies the specific provider order by the ProviderOrderGUID (which is the combination of the provider GUID and the order GUID). However, the provider may also have its own ID system for tracking a particular provider order. As a solution, the provider order in the CMR also contains a provider-tracking ID. When the provider receives the request from the CMR, the provider has the option to accept the order GUID that the CMR has assigned to that provider order, or to provide the CMR with its own unique ID. If the provider does pass back its own unique ID as the provider-tracking ID, then the CMR will use that ID in addition to the normal CMR ProviderOrderGUID to refer to this provider order. If the provider does not specify a tracking ID, then the provider order will be referenced using only the CMR ProviderOrderGUID.

Order States

An order consists of zero or many provider orders. An order state is calculated based on the state of the individual provider orders that make up the order. The table below shows the order states for orders made up of zero or one provider order or of multiple provider orders having the same provider order state. 

Order States with 0 or 1 Provider Order

Restricted or Deleted Order Items 
Some catalog items you may order only with permission. Each provider sets the restrictions and permissions on catalog item ordering. Providers may also delete catalog items at any time. Restrictions can apply to individual users, groups of users or all users. If a catalog item is not available to you, executing the 
CreateAndSubmitOrder, GetCatalogItemOrderInformation, CreateOrder, or AddOrderItems operation with this catalog item will return an error message indicating that it is not an orderable item. If an item becomes unavailable after you have created an order, you will receive an error message when you invoke the 
UpdateOrderItems, ValidateOrder, QuoteOrder, or SubmitOrder operation on that order.