How to Set the Maximum Granules per Order for a Collection in Earthdata Search

[Earthdata - wxedward]

This describes how to limit the number of granules per order for a collection in Earthdata Search by setting a tag on the collection.

This functionality allows providers to specify collection-specific order limits as needed to prevent large orders from adversely impacting provider operations.

For a properly tagged collection, clicking "Download Granules" in Earthdata Search when too many granules are selected will display an error message, and the order will not be allowed.

The tag is edsc.limited_collections, and the order limit is specified in the tag data field "limit".

Step-by-step guide

1. The ability to tag collections is granted through the TAG_GROUP system object identity. In MMT, this is obtained via membership in the permissions group "Tagging Group SYS." If you need tagging access, contact CMR or Earthdata Search developer operations.
2. If you do not already have one, generate an ECHO token. (Note: the id field in the response to the following command is your new token.)
   
   curl -XPOST \
   <a href="https://cmr.earthdata.nasa.gov/legacy-services/rest/tokens">https://cmr.earthdata.nasa.gov/legacy-services/res...</a> \
   -H 'cache-control: no-cache'\
   -H 'content-type: application/xml'\
   -d '<token>
   <username>my_earthdata-username</username>
   <password>my_earthdata_password</password>
   <client_id>client_id_of_my_choosing</client_id>
   <user_ip_address>valid_ip_address_of_my_choosing_example_127.0.0.1</user_ip_address>
   </token>’
3. Tag each collection to be limited with the edsc.limited_collections tag, setting desired the order limit:
   --- Example: to tag a single collection C12345-DAAC_NAME with the edsc.limited_collections tag and set the order limit to 2000 granules, create a tag association as follows:
   
   curl -XPOST \
   -i \
   -H "Content-Type: application/json"\
   -H "Echo-Token: <token from first step>"\
   <a href="https://cmr.earthdata.nasa.gov/search/tags/edsc.limited_collections/associations">https://cmr.earthdata.nasa.gov/search/tags/edsc.li...</a> \
   -d '[{"concept_id":"C12345-DAAC_NAME", "data":{"limit":2000}}]'
   
   ---to tag multiple collections and set limits,
   
   curl -XPOST \
   -i \
   -H "Content-Type: application/json"\
   -H "Echo-Token: <token from first step>"\
   <a href="https://cmr.earthdata.nasa.gov/search/tags/edsc.limited_collections/associations">https://cmr.earthdata.nasa.gov/search/tags/edsc.li...</a> \
   -d '[{"concept_id":"C00001-DAAC_NAME", "data":{"limit":2000}}, \
   "C00002-DAAC_NAME", "data":{"limit":2000}}, \
   "C00003-DAAC_NAME", "data":{"limit":1000}}, \
   "C00004-DAAC_NAME", "data":{"limit":3000}}, \
   "C00005-DAAC_NAME", "data":{"limit":2300}}, \
   "C00006-DAAC_NAME", "data":{"limit":100}}, \
   "C00007-DAAC_NAME", "data":{"limit":2000}}, \
   "C00008-DAAC_NAME", "data":{"limit":5000}}, \
   "C00009-DAAC_NAME","data":{"limit":500}}, \
   < "C00010-DAAC_NAME", "data":{"limit":800}}]'

! To show all tags for a collection (tags will be returned in the field labeled "tags"):
curl -s "https://cmr.earthdata.nasa.gov/search/collections.json?include_tags=*&concept_id=C12345-DAAC_NAME"

! To show all collections that have the order limit tag:
curl "https://cmr.earthdata.nasa.gov/search/collections?tag_key=edsc.limited_collections"