Support stac output format for granule search

nasa · Aug 30, 2024 · e702451 · e702451
1 parent b03f9a0
commit e702451
Show file tree

Hide file tree

Showing 4 changed files with 152 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- Support STAC format output ([#81](https://github.com/nasa/python_cmr/issues/81))
 - Add `Query` method `option` for setting parameter options as described both in
   [CMR Search API Parameter Options](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#parameter-options)
   and in other sections of the CMR Search API documentation, thus supporting

diff --git a/cmr/queries.py b/cmr/queries.py
@@ -36,7 +36,6 @@
 FloatLike: TypeAlias = Union[str, SupportsFloat]
 PointLike: TypeAlias = Tuple[FloatLike, FloatLike]
 
-
 class Query:
     """
     Base class for all CMR queries.
@@ -47,9 +46,10 @@ class Query:
     _format = "json"
     _valid_formats_regex = [
         "json", "xml", "echo10", "iso", "iso19115",
-        "csv", "atom", "kml", "native"
+        "csv", "atom", "kml", "native", "stac",
     ]
 
+
     def __init__(self, route: str, mode: str = CMR_OPS):
         self.params: MutableMapping[str, Any] = {}
         self.options: MutableMapping[str, MutableMapping[str, Any]] = defaultdict(dict)
@@ -238,6 +238,7 @@ def concept_id(self, IDs: Union[str, Sequence[str]]) -> Self:
 
         return self
 
+
     def provider(self, provider: str) -> Self:
         """
         Filter by provider.
@@ -397,12 +398,12 @@ def _format_date(
     ) -> Tuple[str, str]:
         """
         Format dates into expected format for date queries.
-        
+
         :param date_from: earliest date of temporal range
         :param date_to: latest date of temporal range
         :returns: Tuple instance
         """
-        
+
         iso_8601 = "%Y-%m-%dT%H:%M:%SZ"
 
         # process each date into a datetime object
@@ -442,7 +443,7 @@ def convert_to_string(date: Optional[DateLike], default: datetime) -> str:
         # if we have both dates, make sure from isn't later than to
         if date_from and date_to and date_from > date_to:
             raise ValueError("date_from must be earlier than date_to.")
-        
+
         return date_from, date_to
 
     def revision_date(
@@ -462,7 +463,7 @@ def revision_date(
         :param exclude_boundary: whether or not to exclude the date_from/to in the matched range
         :returns: GranueQuery instance
         """
-        
+
         date_from, date_to = self._format_date(date_from, date_to)
 
         # good to go, make sure we have a param list
@@ -495,7 +496,7 @@ def temporal(
         :param exclude_boundary: whether or not to exclude the date_from/to in the matched range
         :returns: GranueQuery instance
         """
-        
+
         date_from, date_to = self._format_date(date_from, date_to)
 
         # good to go, make sure we have a param list
@@ -548,16 +549,16 @@ def point(self, lon: FloatLike, lat: FloatLike) -> Self:
         By default, query results will include items that include _all_ given points.
         To return items that include _any_ given point, set the option on your `query`
         instance like so: `query.options["point"] = {"or": True}`
- 
+
         :param lon: longitude of geographic point
         :param lat: latitude of geographic point
         :returns: self
         """
-        
+
         # coordinates must be a float
         lon = float(lon)
         lat = float(lat)
-        
+
         if "point" not in self.params:
             self.params["point"] = []
 
@@ -914,12 +915,34 @@ def readable_granule_name(
 
         return self
 
+    def collection_concept_id(self, IDs: Union[str, Sequence[str]]) -> Self:
+        """
+        STAC output requires collection_concept_id
+
+        :param IDs: concept ID(s) to search by. Can be provided as a string or list of strings.
+        :returns: self
+        """
+
+        if isinstance(IDs, str):
+            IDs = [IDs]
+
+        # verify we weren't provided any granule concept IDs
+        for ID in IDs:
+            if ID.strip()[0] not in self.concept_id_chars:
+                raise ValueError(
+                    f"Only concept IDs that begin with '{self.concept_id_chars}' can be provided: {ID}"
+                )
+
+        self.params["collection_concept_id"] = IDs
+
+        return self
+
     @override
     def _valid_state(self) -> bool:
 
         # spatial params must be paired with a collection limiting parameter
         spatial_keys = ["point", "polygon", "bounding_box", "line"]
-        collection_keys = ["short_name", "entry_title"]
+        collection_keys = ["short_name", "entry_title", "collection_concept_id"]
 
         if any(key in self.params for key in spatial_keys):
             if not any(key in self.params for key in collection_keys):

diff --git a/tests/fixtures/vcr_cassettes/TestGranuleClass.test_stac_output.yaml b/tests/fixtures/vcr_cassettes/TestGranuleClass.test_stac_output.yaml
@@ -0,0 +1,101 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate, br, zstd
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: https://cmr.earthdata.nasa.gov/search/granules.stac?point%5B%5D=-105.78,35.79&temporal%5B%5D=2021-02-01T00:00:00Z,2021-03-01T23:59:59Z&collection_concept_id%5B%5D=C2021957657-LPCLOUD&page_size=2000
+  response:
+    body:
+      string: '{"type":"FeatureCollection","stac_version":"1.0.0","numberMatched":2,"numberReturned":2,"features":[{"properties":{"datetime":"2021-02-04T17:38:36.830Z","start_datetime":"2021-02-04T17:38:36.830Z","end_datetime":"2021-02-04T17:39:00.717Z","eo:cloud_cover":14},"bbox":[-106.1119251,35.1499121,-104.8915104,36.14489625125828],"assets":{"data3":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B11.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B11.tif"},"data14":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B05.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B05.tif"},"data12":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.SZA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.SZA.tif"},"data10":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B03.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B03.tif"},"data7":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B10.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B10.tif"},"data8":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.VZA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.VZA.tif"},"data2":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.VAA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.VAA.tif"},"browse":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.jpg","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.jpg","type":"image/jpeg"},"data6":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B09.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B09.tif"},"data4":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B02.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B02.tif"},"data13":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B07.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B07.tif"},"data1":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B06.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B06.tif"},"data9":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.Fmask.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.Fmask.tif"},"data5":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B01.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B01.tif"},"metadata":{"href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147556158-LPCLOUD.xml","type":"application/xml"},"data11":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.B04.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.B04.tif"},"data":{"title":"Download
+        HLS.L30.T13SDV.2021035T173836.v2.0.SAA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021035T173836.v2.0/HLS.L30.T13SDV.2021035T173836.v2.0.SAA.tif"}},"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-106.0982929,35.1499121],[-104.8928408,35.1548427],[-104.8915104,36.1448493],[-106.1119251,36.1397366],[-106.0982929,35.1499121]]]},"stac_extensions":["https://stac-extensions.github.io/eo/v1.0.0/schema.json"],"id":"G2147556158-LPCLOUD","stac_version":"1.0.0","collection":"C2021957657-LPCLOUD","links":[{"rel":"self","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147556158-LPCLOUD.stac"},{"rel":"parent","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/C2021957657-LPCLOUD.stac"},{"rel":"collection","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/C2021957657-LPCLOUD.stac"},{"rel":"root","href":"https://cmr.earthdata.nasa.gov:443/search/"},{"rel":"via","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147556158-LPCLOUD.json"},{"rel":"via","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147556158-LPCLOUD.umm_json"}]},{"properties":{"datetime":"2021-02-20T17:38:32.415Z","start_datetime":"2021-02-20T17:38:32.415Z","end_datetime":"2021-02-20T17:38:56.302Z","eo:cloud_cover":2},"bbox":[-106.1119251,35.1499121,-104.8915104,36.14489625125828],"assets":{"data3":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B06.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B06.tif"},"data14":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B10.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B10.tif"},"data12":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B02.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B02.tif"},"data10":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B03.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B03.tif"},"data7":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B05.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B05.tif"},"data8":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.VZA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.VZA.tif"},"data2":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B09.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B09.tif"},"browse":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.jpg","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-public/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.jpg","type":"image/jpeg"},"data6":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B04.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B04.tif"},"data4":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.SZA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.SZA.tif"},"data13":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B07.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B07.tif"},"data1":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B11.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B11.tif"},"data9":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.SAA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.SAA.tif"},"data5":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.VAA.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.VAA.tif"},"metadata":{"href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147455974-LPCLOUD.xml","type":"application/xml"},"data11":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.B01.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.B01.tif"},"data":{"title":"Download
+        HLS.L30.T13SDV.2021051T173832.v2.0.Fmask.tif","href":"https://data.lpdaac.earthdatacloud.nasa.gov/lp-prod-protected/HLSL30.020/HLS.L30.T13SDV.2021051T173832.v2.0/HLS.L30.T13SDV.2021051T173832.v2.0.Fmask.tif"}},"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-106.0982929,35.1499121],[-104.8928408,35.1548427],[-104.8915104,36.1448493],[-106.1119251,36.1397366],[-106.0982929,35.1499121]]]},"stac_extensions":["https://stac-extensions.github.io/eo/v1.0.0/schema.json"],"id":"G2147455974-LPCLOUD","stac_version":"1.0.0","collection":"C2021957657-LPCLOUD","links":[{"rel":"self","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147455974-LPCLOUD.stac"},{"rel":"parent","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/C2021957657-LPCLOUD.stac"},{"rel":"collection","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/C2021957657-LPCLOUD.stac"},{"rel":"root","href":"https://cmr.earthdata.nasa.gov:443/search/"},{"rel":"via","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147455974-LPCLOUD.json"},{"rel":"via","href":"https://cmr.earthdata.nasa.gov:443/search/concepts/G2147455974-LPCLOUD.umm_json"}]}],"links":[{"rel":"self","href":"https://cmr.earthdata.nasa.gov:443/search/granules.stac?point%5B%5D=-105.78%2C35.79&temporal%5B%5D=2021-02-01T00%3A00%3A00Z%2C2021-03-01T23%3A59%3A59Z&collection_concept_id%5B%5D=C2021957657-LPCLOUD&page_size=2000&page_num=1"},{"rel":"root","href":"https://cmr.earthdata.nasa.gov:443/search/"}],"context":{"returned":2,"limit":1000000,"matched":2}}'
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Access-Control-Expose-Headers:
+      - CMR-Hits, CMR-Request-Id, X-Request-Id, CMR-Scroll-Id, CMR-Search-After, CMR-Timed-Out,
+        CMR-Shapefile-Original-Point-Count, CMR-Shapefile-Simplified-Point-Count
+      CMR-Hits:
+      - '2'
+      CMR-Request-Id:
+      - 4a24576d-c853-495e-bc73-bf0fe2435e77
+      CMR-Took:
+      - '1294'
+      Connection:
+      - keep-alive
+      Content-MD5:
+      - 1b2a435290accaffaf57f8f289205d9a
+      Content-SHA1:
+      - e79245d9eae7f057c5faf871fdf7fc0803b5924e
+      Content-Type:
+      - application/json; profile=stac-catalogue; charset=utf-8
+      Date:
+      - Fri, 30 Aug 2024 05:48:08 GMT
+      Server:
+      - ServerTokens ProductOnly
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubDomains; preload
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding, User-Agent
+      Via:
+      - 1.1 6f51dc97d58041fe23fd6f71e2f76dd4.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id:
+      - 50RnmzzQxLwCCa_CxsVJK12VBW58HG_lZY3qIAqXvnQfcenexpbpnA==
+      X-Amz-Cf-Pop:
+      - HIO50-C2
+      X-Cache:
+      - Miss from cloudfront
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - SAMEORIGIN
+      X-Request-Id:
+      - 50RnmzzQxLwCCa_CxsVJK12VBW58HG_lZY3qIAqXvnQfcenexpbpnA==
+      X-XSS-Protection:
+      - 1; mode=block
+      content-length:
+      - '10545'
+    status:
+      code: 200
+      message: OK
+version: 1
diff --git a/tests/test_granule.py b/tests/test_granule.py
@@ -457,6 +457,22 @@ def _test_get(self):
 
         self.assertEqual(len(results), 10)
 
+    def test_stac_output(self):
+        """ Test real query with STAC output type """
+        # HLSL30: https://cmr.earthdata.nasa.gov/search/concepts/C2021957657-LPCLOUD 
+        query = GranuleQuery()
+        search = query.parameters(point=(-105.78, 35.79),
+                           temporal=('2021-02-01','2021-03-01'),
+                           collection_concept_id='C2021957657-LPCLOUD'
+        )
+        results = search.format("stac").get()
+        feature_collection = json.loads(results[0])
+
+        self.assertEqual(len(results), 1)
+        self.assertEqual(feature_collection['type'], 'FeatureCollection')
+        self.assertEqual(feature_collection['numberMatched'], 2)
+        self.assertEqual(len(feature_collection['features']), 2)
+
     def _test_hits(self):
         """ integration test for hits() """