Save and load search results

[betolink]

There are use cases when we would like to store the results of a search for future use. One of such use cases is for when we are testing the same set of files or datasets, or in case CMR is down. This will look like:

results = earthaccess.search_data(params)
earthaccess.save(results, "query.json")

# later on...

results = earthaccess.load("query.json")

The query will also have the original query to CMR to compare integrity.

[asteiker]

@betolink Is this something you would still like to pursue?

[jhkennedy]

Yes, I think this is something still worth persuing and upcoming changes to search_data should make this easer.

[Sherwin-14]

Based on some conversations with @mfisher87, I concluded that the implementation of Results class will make it easier for us to add this functionality. We can add methods within the class itself that makes it easier to for us to encode this into JSON(and subsequently making use of those methods to create a save and a load function). I'm curious as to what others think of this issue? I am willing to help out in reviving this PR if it helps in solving this issue.

@chuckwondo @jhkennedy @betolink Thoughts?

[chuckwondo]

I'm not convinced we need this. In the context of testing, we use vcrpy for recording requests and responses. I believe this issue was created before we started making use of vcrpy, so perhaps there's less need for this functionality now? Is there a strong desire for such functionality outside of testing?

[mfisher87]

I could see saving and loading results being useful for reproducibility. CMR results can change, either due to mistakes, deprecation of datasets, or CMR going away entirely. Of course there's nothing we can do if a dataset is removed from its hosted location. But saving the CMR results and committing them would be useful context that would otherwise not be available to would-be reproducers in the future.

[chuckwondo]

In that case, perhaps we might consider how we might leverage requests-cache for a more general mechanism that won't require us to reinvent the wheel.

[jhkennedy]

My understanding of this issue is that it's not about caching the actual CMR responses, but being able to serialize the earthaccess search results (that is, the returned data structure). That can be used for testing, but it's also useful for a variety of purposes beyond that. Particularly, any time you're building out workflows on top of earthaccess you may want to serialize the search results so that can start from there again. Running feature tracking workflows, or InSAR workflows requires generating list of suitbale pairs, and that workflow can get complicated to get to the end "search results" you actually care about, so often requires iteration on methods that use the search results.

At it's simplest this could just be saving the all the umm_json results to disk with the search arguments as well. Although, I'd in particular like to be able to save a GeoJSON and/or (good) STAC representation of search results (asf_search does this and I pretty much always use that as part of my workflows), but that'd require a umm_json to GeoSON/STAC method, which is a different, but similar feature request (and is effectively being asked for in #305)

@Sherwin-14, I agree that if we're going to provide serialization methods, it would make sense to provide the Results class first. I have been completely pressed for time, but I could help review that PR if you revive it. And maybe help move it forward in the new year.

[mfisher87]

Something I think is important: In addition to serializing the results, we should serialize the original parameters that got those results, and the resulting CMR query. E.g.:

{
  "meta": {
    "export_version": 1,
    "earthaccess_version": "0.19.2"
  },
  "search": {
    "parameters": {
      "collection": ...,
      "temporal": ...,
      "spatial": ...
    },
    "query": {
      "url": "https://cmr.earthdata.nasa.gov/...",
	  "submitted_time": "2025-11-17T18:00:11+00:00"
    }
  },
  "results": [
    ...
  ]
}

[mfisher87]

Ooo, and it would be really nice to also encode the timestamp the query was executed to get those results. Provenance, baby! Edited example.