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.
CMR Environment | Base API URL |
---|---|
Operational (OPS) | |
User Acceptance Test (UAT) | |
Systems Integration Test (SIT) |
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
Body format | Content-Type |
---|---|
XML | application/xml |
JSON | application/json |
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
Type Received | Accept HeaderValue | Comments |
---|---|---|
XML | application/xml | returns a reference list of results using the XML format |
JSON | application/json | returns an expanded list of results using the JSON format |
echo10 | application/echo10+xml | returns an expanded list of results in the echo 10 specification using the XML format |
iso | application/iso19115+xml | returns an expanded list of results in the ISO 19115-2 (MENDS) specification using the XML format |
iso19115 | application/iso19115+xml | returns an expanded list of results in the ISO 19115-2 (MENDS) specification using the XML format |
dif | application/dif+xml | supported for collections only and returns an expanded list of results in the DIF 9 specification using the XML format |
dif10 | application/dif10+xml | supported for collections only and returns an expanded list of results in the DIF 10 specification using the XML format |
csv | text/csv | supported for granules only and returns an expanded list of results in a comma separated value format |
atom | application/atom+xml | returns an expanded list of results in the ATOM specification using the XML format |
opendata | application/opendata+json | supported for collections only and returns an expanded list of results in the open data specification using the JSON format |
kml | application/vnd.google-earth.kml+xml | returns an expanded list of results using the KML specification in the XML format |
native | application/metadata+xml | returns an expanded list of results in their individual native specification using the XML format |
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.
curl -v -XPOST -H "Content-Type: application/json" -H "Echo-Token: 75E5CEBE-6BBB-2FB5-A613-0368A361D0B6" -H "Accept: application/xml" -H "Client-Id: Test_Team" -d @searchterms
-i https://cmr.sit.earthdata.nasa.gov/search/collections
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.
curl -v -H "Accept: application/metadata+xml" -i https://cmr.sit.earthdata.nasa.gov/search/collections
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.
curl -v -i https://cmr.sit.earthdata.nasa.gov/search/collections
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.
curl -v -i "https://cmr.sit.earthdata.nasa.gov/search/collections.opendata"
Other examples use the DIF 10 specification and the ISO specification respectively.
curl -v -i "https://cmr.sit.earthdata.nasa.gov/search/collections.dif10"
curl -v -i "https://cmr.sit.earthdata.nasa.gov/search/collections.iso"
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:
- A reference list of results and
- An expanded list of results
The following is an example of a reference list of results
<results>
<hits>2215</hits>
<took>16</took>
<references>
<reference>
<name>100m Digital Elevation Model Data V001</name>
<id>C1000000803-DEV08</id>
<location>https://cmr.sit.earthdata.nasa.gov:443/search/concepts/C1000000803-DEV08>
<revision-id>8</revision-id>
</reference>
<reference>
<name>100m Digital Elevation Model Data V001</name>
<id>C1000000719-EDF_OPS</id>
<location>https://cmr.sit.earthdata.nasa.gov:443/search/concepts/C1000000719-EDF_OPS>
<revision-id>8</revision-id>
</reference>
...
</references>
</results>
The results specify
- how many metadata records were found by the "hits" tag
- how long the query took in milliseconds
- a list of metadata record results specified by the "reference" tag
With in each reference tag a limited information about the metadata is provided.
- The metadata name which corresponds to the UMM Entry Title
- 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.
- The exact CMR location to download the metadata
- 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.
<results>
<hits>2215</hits>
<took>53</took>
<result concept-id="C1000000803-DEV08"
format="application/echo10+xml" revision-id="8">
<Collection>
<ShortName>DEM_100M</ShortName>
<VersionId>1</VersionId>
<InsertTime>2002-04-27T15:27:55.293Z</InsertTime>
<LastUpdate>2013-10-04T08:49:26.783Z</LastUpdate>
<LongName>100m Digital Elevation Model Data</LongName>
...
</Collection>
</result>
<result concept-id="C1000000719-EDF_OPS"
format="application/echo10+xml" revision-id="8">
<Collection>
<ShortName>DEM_100M</ShortName>
</result>
</results>
The results specify
- how many metadata records were found by the "hits" tag
- how long the query took in milliseconds
- 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:
- Using the API calls and parameters with the GET or POST methods
- Using a JSON query language with a POST method
- Using the Alternative Query Language (AQL)
API calls and parameters
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
curl -v -i "https://cmr.earthdata.nasa.gov/search/collections"
It just 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.
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.
curl -v -i "https://cmr.earthdata.nasa.gov/search/collections?page_size=50"
curl -v -i "https://cmr.earthdata.nasa.gov/search/collections?page_size=50&pretty=true"
curl -v -i "https://cmr.earthdata.nasa.gov/search/collections.echo10?page_num=2&page_size=20&pretty=true"
curl -v -i -H "Echo-Tocken: 75E5CEBE-6BBB-2FB5-A613-0368A361D0B6" -H "Client-Id: Test_Team" "https://cmr.earthdata.nasa.gov/search/collections.iso?sort_key\[\]=platform&page_num=2&page_size=20&pretty=true"
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.
Search Parameters | Example | Notes | Supports Pattern (wild card) | Supports case insensitivity | Supports AND (all values have to be present within an element) | Supports finding multiple values in the same element (OR) |
---|---|---|---|---|---|---|
concept_id | concept_id\[\]=C123456-LPDAAC_ECS | YES | ||||
echo_collection_id | echo_collection_id\[\]=C1000000001-CMR_PROV2 | uses concept_id | ||||
entry_title | entry_title\[\]=this is a title | YES | YES | NO | ||
dataset_id | dataset_id\[\]=this is a title | uses entry_title | N/A | N/A | NO | |
entry_id | entry_id\[\]=SHORT_V5 | NO | ||||
dif_entry_id | dif_entry_id\[\]=SHORT_V5 | matches either entry_id or associated difs | NO | |||
archive_center | archive_center\[\]=SEDAC | YES | YES | NO | ||
temporal | temporal\[\]=2000-01-01T10:00:00Z,2010-03-10T12:00:00Z,30,60 or temporal\[\]=2000-01-01T10:00:00Z/P10Y2M10DT2H,30,60 | format is: begin datetime, end datetime, period, duration or: begin datetime/ISO 8601 time interval One can leave out the begin time or end time or both the period and duration ranges are inclusive unless otherwise specified | N/A | N/A | NO | YES |
project | project\[\]=ESI | YES | YES | YES | YES | |
campaign | campaign\[\]=ESI | uses project | YES | YES | YES | YES |
updated_since | updated_since=2000-01-01T01:00:00Z | The time is inclusive. | NO | N/A | NO | YES |
revision_date | revision_date\[\]=2000-01-01T01:00:00Z, | can specify an inclusive range | NO | N/A | YES | YES |
processing_level_id | processing_level_id\[\]=1B | YES | YES | NO | YES | |
platform | platform\[\]=AQUA | platform short name | YES | YES | YES | YES |
instrument | instrument\[\]=CERES | instrument short name | YES | YES | YES | YES |
sensor | sensor\[\]=CCD | sensor short name | YES | YES | YES | YES |
spatial_keyword | spatial_keyword\[\]=VA | YES | YES | YES | YES | |
science_keywords | ||||||
two_d_coordinate_system_name | ||||||
two_d_coordinate_system[name] | ||||||
collection_data_type | ||||||
online_only | ||||||
downloadable | ||||||
browse_only | ||||||
browsable | ||||||
provider | ||||||
short_name | ||||||
version | ||||||
polygon | ||||||
bounding_box | ||||||
point | ||||||
line | ||||||
keyword |
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.
curl -v -i -H "Echo-Tocken: 75E5CEBE-6BBB-2FB5-A613-0368A361D0B6" -H "Client-Id: Test_Team" "https://cmr.earthdata.nasa.gov/search/collections.iso?platform\[\]=AQUA&page_size=20&pretty=true"
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.
curl -v -i -H "Echo-Tocken: 75E5CEBE-6BBB-2FB5-A613-0368A361D0B6" -H "Client-Id: Test_Team" "https://cmr.earthdata.nasa.gov/search/collections.iso?platform\[\]=AQUA&platform\[\]=AURA&page_size=20&pretty=true"
Most of the search parameters listed in the Search Parameters table works in this fashion.
To refine your search start using the supported
concept-id | |
provider-id | |
entry-title | |
collection-data-type | |
short-name | |
long-name | |
two-d-coord-names | |
summary | |
version-id | |
version-description | |
processing-level-id | |
archive-centers | |
science-keywords | |
attrib-keywords (name value and description from additional attributes) | |
spatial-keywords | |
temporal-keywords | |
associated-difs | |
project-long-names | |
project-short-names | |
platform-short-names | |
platform-long-names | |
instrument-short-names | |
instrument-long-names | |
instrument-techiques | |
sensor-short-names | |
sensor-long-names | |
sensor-techniques | |
characteristic-names | |
characteristic-descs |
Table 2: Query Return Result Types
Value | Description |
---|---|
RESULTS | Returns the detailed metadata for items that match the query directly in the response. When using this option, you may choose to limit the actual metadata values returned. In addition, the CMR will return a result set identifier (ResultSetGUID) for subsequent retrievals of the results or for paging through the result list. Note that CMR Operations limits the maximum number of items returned to 2,000 at a time. The complete results are stored in your result set which you can retrieve by using the GetQueryResults operation. |
RESULT_SET_GUID | Returns the result set guid of the results that are stored on the server. The CMR will generate a result set but will not return any results. You must subsequently retrieve the results using the GetQueryResults operation. |
HITS | Returns the number of hits (matches) to the query and a ResultSetGUID for the results stored on the server. The CMR will generate a result set but will not return any results. The number of records may be a statistically determined for large result sets. You must subsequently retrieve the results using the GetQueryResults operation. Hits is a relatively expensive operation therefore if the client only needs to know if some data exists, it is faster to simply query for ITEM_GUIDS with a small iterator size. |
ITEM_GUIDS | Returns the Catalog Item GUIDs that match the specified query. Note: No ResultSetGUID is returned since results do not persist in the system. All the GUIDs of the granules/collections that satisfy the query are returned to the client. It is the client‘s responsibility to request the metadata for each individual granule/collection using the GetCatalogItemMetadata operation discussed later. |
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
Argument | Description |
---|---|
IteratorSize | Specifies the number of results to be returned from a single operation. This does not limit the number of items a query may match (see MaxResults) but limits to 2,000 the number of matching items returned in the result set, starting from the Cursor position. This field is only used if the result type is set to RESULTS. |
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. This field is only used if the result type is set to RESULTS. |
MetadataAttributes | Specifies which fields of the CMR Metadata you actually want to return. By only requesting the parts of the metadata you are interested in, you can increase query performance substantially. By default, the CMR returns all of the metadata for each item. This field is only used if the result type is set to RESULTS. |
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);
Handling Large Result Sets
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(); }
Like ExecuteQuery, GetQueryResults takes an array of MetadataAttributes. Internally, the CMR only stores in a result set the item IDs that match a given query. This means that you may pull different metadata from a single result set with each call by varying what you pass to the MetadataAttribute array without needing to re-query the CMR . It is highly recommended you use the MetadataAttribute array to restrict the information the CMR returns and thus improve performance.
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:
- Instrument swath width (in kilometers)
- Satellite declination or inclination (in degrees)
- Satellite period (in minutes)
Orbit data representation
Three parameters to represent orbit data:
- Equatorial crossing longitude
- Start circular latitude (or start latitude and start direction)
- 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
< granuleCondition > < spatial > < IIMSPolygon > < IIMSLRing > < IIMSPoint lon = "-90" lat = "49" /> < IIMSPoint lon = "-90" lat = "39" /> < IIMSPoint lon = "-70" lat = "39" /> < IIMSPoint lon = "-70" lat = "49" /> < IIMSPoint lon = "-90" lat = "49" /> </ IIMSLRing > </ IIMSPolygon > < SpatialType > < list > < value >ORBIT</ value > </ list > </ SpatialType > </ spatial > </ granuleCondition > |
- 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>