Logging in, setting up and getting started
This section contains information and examples that are common to most CMR client applications, such as basic Login and Logout and creation and management of user accounts.
CMRTokens & User Contexts
There are two types of users in the CMR: registered users and guests. LBN: Is this still valid or is URS now required? Registered users can have access to restricted data and services but requires the creation of a URS profile. Guest users do not require a URS profile but their access is limited in some areas.
CMR tokens are generated whenever a user interacts with a CMR API. A token is a transient representation of either your URS credentials or your guest status.
In both CMR-REST and CMR-SOAP LBN: Does CMR have a SOAP API? APIs registered access requires the creation of a CMR token and then use of that token throughout your interaction with the CMR.
In the case of CMR-REST, guest token creation is carried out behind the scenes of the API. In the case of CMR-SOAP a client must manually create their token to interact with the API.
User Accounts
Create your user credentials in URS and use them to interact with the CMR using your user name and password.
Creating and Managing CMR Sessions
When using the Web Services API, you need to request a CMR token for all but CMR-REST guest access.
This token acts as your session key and must be passed to all other CMR operations. All clients interfacing with the system are required to pass client identifier information to the CMR. The client identifier is a short description and/or name of the client. Client developers are encouraged to keep this information as concise as possible and to work with the CMR Operations Group to create an appropriate identifier.
A token is obtained when logging into the CMR (see Logging Into the CMR). This is also done when setting user and provider context.
When done working in the CMR, be sure to logoff (see Logging Out of the CMR).
NOTE: If client identifier information is not provided, submitted orders will fail.
Logging Into the CMR
The REST way
Create a token via a POST to the token resource
Request headers: Content-Type: application/xml Request: POST https://api.cmr.nasa.gov/cmr-rest/tokens Request body: <token> <username>Your URS username</username> <password>Your URS password</password> <client_id>An arbitrary ID to identify yourself</client_id> <user_ip_address>Your IP address</user_ip_address> </token>
If you want to perform operations as a provider then you need the provider id and the credentials of a user that has provider privileges.
Request headers: Content-Type: application/xml Request: POST https://api.cmr.nasa.gov/cmr-rest/tokens Request body: <token> <username>Your URS username</username> <password>Your URS password</password> <client_id>An arbitrary ID to identify yourself</client_id> <user_ip_address>Your IP address</user_ip_address> <behalfOfProvider>Your provider ID</behalfOfProvider> </token>
The CMR token will be returned to you as follows in the response body,
<?xml version="1.0" encoding="UTF-8"?> <token> <id>CMR-TOKEN-ID</id> <username>Your URS username</username> <client_id>An arbitrary ID to identify yourself</client_id> <user_ip_address>Your IP address</user_ip_address> </token>
You will use the value of CMR-TOKEN-ID to interact with the CMR REST API.
The SOAP way
To obtain a token, call the Login operation of the Authentication Service. A new token is created and returned each time Login is invoked. Code Listing 1 is an example of logging in to the CMR and creating a session token for a guest user.
Parameters:
- username - Username of the user logging in.
- password - Password of the user.
- clientInfo - The string identifier of the CMR client used to make this request.
- actAsUserName - name of the user an Admin wants to act as, null for non CMR administrator users.
- behalfOfProvider - provider the user wants to act as, null for guests and registered users with no ProviderRoles.
A Security Token is returned that is used for all subsequent calls to the CMR using the same Token profile.
// Client information is optional information provided by the // client to the CMR when a user logs in ClientInformation clientInfo = new ClientInformation(); clientInfo.setClientId("A Client"); clientInfo.setUserIpAddress("192.168.1.1"); // Call login with guest as username, email as password, and // client information String token = authenticationService.login("guest", "john@doe.com", clientInfo, null, null);
Code Listing 2 is an example of logging in to the CMR and creating a session token for a guest user.
// Client information is optional information provided by the // client to CMR when a user logs in ClientInformation clientInfo = new ClientInformation(); clientInfo.setClientId("A Client"); clientInfo.setUserIpAddress("192.168.1.1"); // Call login with jdoe as username, mypass as password, and // client information String token = authenticationService.login("jdoe", "mypass", clientInfo, null, null);
Logging Out of the CMR
The REST way
To logout of your session simply delete your CMR token.
DELETE https://api.cmr.nasa.gov/cmr-rest/tokens/CMR-TOKEN-ID Response: Status Code: 204 No Content
The SOAP way
When you are finished with a token, for example, you have finished a session with the CMR; destroy the token using the Logout operation.
Parameter(s):
- token - security token
// Logout and set token to null because it is not useful anymore authenticationService.logout(token); token = null;
You do not need to destroy a token after each call; you may reuse a token until it is destroyed with the Logout operation or the token expires. 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.
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;
Querying for earth science metadata
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>