Multi-feature search support added to CMR api calls #1109

tiagodc · 2025-10-07T22:35:30Z

This pull request adds multi-feature querying support for all spatial types. The python_cmr library already supports querying with multiple features simultaneously, which are parsed from list inputs in the _build_url function. This CMR functionality enables easy multipolygon [...] support with minimal code changes.

I created five new methods in the DataGranules class to enable explicit search of granules from multi-feature spatial inputs:

multi_bounding_box
multipolygon
multipoint
multicircle
multiline

Those functions run the single-feature methods internally and update the params attribute inherited from the Query class of python_cmr, thus bulding single GET request URLs following the CMR standard.

Tests are provided for all the new methods and the documentation was updated to illustrate how to use them.

I recently found out about earthaccess. It's an amazing tool and I hope this PR will be useful :)

📚 Documentation preview 📚: https://earthaccess--1109.org.readthedocs.build/en/1109/

github-actions · 2025-10-07T22:35:41Z

👈 Launch a binder notebook on this branch for commit 5739564

I will automatically update this comment whenever this PR is modified

asteiker · 2025-10-07T23:15:00Z

Thank you very much @tiagodc ! We appreciate your first contribution to earthaccess and for your positive words about the library. I linked to the related #490 enhancement Issue in our backlog.

chuckwondo

@tiagodc, thank you for your contribution, and apologies that it has taken so long to get it reviewed.

I've made comments, but I've also solicited some other maintainers for input as well, so let's see what they have to say about my suggestions and questions.

chuckwondo · 2025-11-04T15:59:14Z

earthaccess/search.py

+        points = []
+
+        for x, y in lon_lat_pairs:
+            self.point(x, y)
+            points.append(self.params.pop('point')[0])
+
+        self.params['point'] = points


This should be unnecessary because the point method already performs an append each time it is called. That is, the point method is already implemented to support being called multiple times, adding a new point to the list of points on each call.

Therefore, this should be all that's required:

Suggested change

points = []

for x, y in lon_lat_pairs:

self.point(x, y)

points.append(self.params.pop('point')[0])

self.params['point'] = points

for x, y in lon_lat_pairs:

self.point(x, y)

chuckwondo · 2025-11-04T16:00:40Z

earthaccess/search.py

        """
        return super().point(lon, lat)

+    def multipoint(self, lon_lat_pairs: Sequence[PointLike]) -> Self:


Please add an or_ kwarg so the caller can explicitly set the option, instead of assuming it should be set to True (and please update the docstring to include it):

Suggested change

def multipoint(self, lon_lat_pairs: Sequence[PointLike]) -> Self:

def points(self, lon_lat_pairs: Sequence[PointLike], *, or_: bool | None = None) -> Self:

I would prefer or_ to be a kwarg because passing a bool value without a keyword is not intuitive.

However, making it a positional arg allows for it to be set like so (whereas this is not possible when or_ is a kwarg):

earthaccess.search_data( short_name="ATL06", polygons=(polygons, True), )

Again, it's not intuitive as to what True means here, so I'd like some input from others on this point (cc: @betolink, @mfisher87, @jhkennedy).

I don't like the "bare" boolean argument, but on the other hand, I don't like that (sub)kwargs cannot be specified via search_data.

In order to pass or_ when it is a kwarg, the caller cannot use search_data, and must instead directly construct a DataGranules instance, like so:

query = ( DataGranules() .short_name("ATL06") .polygons(polygons, or_=True) )

(Alternatively, renaming or_ to any_ might make it even more readable -- i.e., any/all is more intuitive than or/and, no?)

chuckwondo · 2025-11-04T16:05:30Z

earthaccess/search.py

+            points.append(self.params.pop('point')[0])
+
+        self.params['point'] = points
+        self.options['point'] = {'or': True}        


I would prefer not to assume the caller wants the or option to be set to True, so let's add an or_ kwarg, defaulted to None:

Suggested change

self.options['point'] = {'or': True}

self.option("point", "or", or_)

chuckwondo · 2025-11-04T16:17:30Z

earthaccess/search.py

        """
        return super().polygon(coordinates)

+    def multipolygon(self, multi_coordinates: Sequence[Sequence[PointLike]]) -> Self:


Please add an or_ kwarg, as I've described in my comment on the multipoint method:

Suggested change

def multipolygon(self, multi_coordinates: Sequence[Sequence[PointLike]]) -> Self:

def polygons(self, polygons_: Sequence[Sequence[PointLike]], *, or_: bool | None = None) -> Self:

chuckwondo · 2025-11-04T16:20:06Z

earthaccess/search.py

+            polygons.append(self.params.pop('polygon'))
+
+        self.params['polygon'] = polygons
+        self.options['polygon'] = {'or': True}        


Suggested change

self.options['polygon'] = {'or': True}

self.option("polygon", "or", or_)

chuckwondo · 2025-11-04T16:40:23Z

earthaccess/search.py

+        """Filter by granules that overlap any bounding box from an input list.
+
+        Parameters:
+            boxes: list of tuples of (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)


Suggested change

boxes: list of tuples of (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)

bboxes: list of tuples of (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)

chuckwondo · 2025-11-04T17:05:02Z

earthaccess/search.py

+        lines = []
+
+        for line in multi_coordinates:
+            self.line(line)
+            lines.append(self.params.pop('line'))
+
+        self.params['line'] = lines


Suggested change

lines = []

for line in multi_coordinates:

self.line(line)

lines.append(self.params.pop('line'))

self.params['line'] = lines

self.params["line"] = [

self.polygon(line).params.pop("line") for line in lines_

]

chuckwondo · 2025-11-04T17:05:13Z

earthaccess/search.py

+        """Filter by granules that overlap any series of connected points from an input list.
+
+        Parameters:
+            multi_coordinates: a list of lists of (lon, lat) tuples


Suggested change

multi_coordinates: a list of lists of (lon, lat) tuples

lines_: a list of lists of (lon, lat) tuples

chuckwondo · 2025-11-04T17:07:35Z

earthaccess/search.py

+        circles = []
+
+        for circle in multi_circles:
+            self.circle(*circle)
+            circles.append(self.params.pop('circle'))
+
+        self.params['circle'] = circles


Suggested change

circles = []

for circle in multi_circles:

self.circle(*circle)

circles.append(self.params.pop('circle'))

self.params['circle'] = circles

self.params["circle"] = [

self.circle(*circle).params.pop("circle") for circle in circles_

]

chuckwondo · 2025-11-04T17:07:47Z

earthaccess/search.py

+        """Filter by granules that overlap any circle from an input list.
+
+        Parameters:
+            multi_circles: list of tuples of (lon, lat, radius)


Suggested change

multi_circles: list of tuples of (lon, lat, radius)

circles_: list of tuples of (lon, lat, radius)

tiagodc · 2025-11-06T15:56:32Z

Thank you for reviewing it @chuckwondo. I'll wait to see what the other reviewers say before committing further changes - mainly the _or kwarg.

I set up the or to be true by default as I didn't see a way to enable a kwarg in search_data without updating the method itself - which i tried to avoid in a 1st PR, so I assumed or to be the most common use case. Setting the argument explicitly by the user would be ideal - and perhaps setting _any=True by default?

Regardless if it may require further changes to search_data, I'll be happy to go with whatever solution works best in your view.

chuckwondo · 2025-11-12T20:49:13Z

@mfisher87, @betolink, @jhkennedy, any of you able to look over this? I took a first pass, but I added a question to get input from others about how we want to approach something: https://github.com/nsidc/earthaccess/pull/1109/files#r2491099493.

@tiagodc, in the meantime, would you mind merging the latest changes from the main branch into your branch?

tiagodc added 5 commits October 7, 2025 16:33

support for multifeature querying on CMR calls

10c9f86

multifeature search tests added

da1025b

multi circle support aded

bbbbfd8

multi-feature search documentation updated

37f0b25

changelog updated

5739564

asteiker linked an issue Oct 7, 2025 that may be closed by this pull request

Support multiple-point searches #491

Open

asteiker requested review from betolink, chuckwondo and mfisher87 October 7, 2025 23:15

chuckwondo requested changes Nov 4, 2025

View reviewed changes

	def multipoint(self, lon_lat_pairs: Sequence[PointLike]) -> Self:
	def points(self, lon_lat_pairs: Sequence[PointLike], *, or_: bool \| None = None) -> Self:

	self.options['point'] = {'or': True}
	self.option("point", "or", or_)

	def multipolygon(self, multi_coordinates: Sequence[Sequence[PointLike]]) -> Self:
	def polygons(self, polygons_: Sequence[Sequence[PointLike]], *, or_: bool \| None = None) -> Self:

	self.options['polygon'] = {'or': True}
	self.option("polygon", "or", or_)

	boxes: list of tuples of (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)
	bboxes: list of tuples of (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)

	multi_coordinates: a list of lists of (lon, lat) tuples
	lines_: a list of lists of (lon, lat) tuples

	multi_circles: list of tuples of (lon, lat, radius)
	circles_: list of tuples of (lon, lat, radius)

Multi-feature search support added to CMR api calls #1109

Are you sure you want to change the base?

Multi-feature search support added to CMR api calls #1109

Uh oh!

Conversation

tiagodc commented Oct 7, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 7, 2025

Uh oh!

asteiker commented Oct 7, 2025

Uh oh!

chuckwondo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiagodc commented Nov 6, 2025

Uh oh!

chuckwondo commented Nov 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tiagodc commented Oct 7, 2025 •

edited by github-actions bot

Loading