SeDAS API – Python Client
Emily Selwood
Did you know the SeDAS system has an API to allow programs to search and download data from it? It hasn’t had a lot of use outside of the Catapult and Airbus. So, we took the time to pull our internal client code out into its own library that we could publish. Hopefully this will make it easier for everyone else to use.
We have now released this client library on to Github and PyPI for anyone to use freely.
Prerequisites
To work through the rest of this you will need a working python 3 installation and an account on the SeDAS system.
Adding the library to the project
Adding the library to an existing project is relatively easy. You should just need to add a reference to the sedas_pyapi package and install it.
setup.py
Add sedas_pyapi to the install_requires list
pip
pip install sedas_pyapi
(You are using an environment aren’t you?)
Creating a client object
The first step of using this is to create a client object. This needs to be told your username and password. We recommend using something like getpass so that the password doesn’t end up being recorded somewhere.
from getpass import getpass
# This is a suggestion for how to get your username and password
_username = input(“Please enter your username:”)
__password = getpass(“Please enter your password:”)
sedas = SeDASAPI(_username, __password)
Now we have the SeDASAPI object we can use that to find the scenes we are looking for.
Queries
To perform a query you need an area of the world you are interested in and a time window. You will also probably need to know which kind of data you are interested in – the processing you are likely to do will be very different when working with Sentinel 1 data compared to Sentinel 2 data.
The area of interest needs to be defined as a Well Known Text (WKT) string. The following covers an area around the Harwell campus where the catapult is based.
wkt = “POLYGON ((-1.3295 51.5881,” \
“-1.3020 51.5621,” \
“-1.3300 51.5622,” \
“-1.3295 51.5881))”
startDate = “2019-04-30T00:00:00Z”
endDate = “2019-05-12T23:59:59Z”
For this example, we will look for Sentinel 2 optical images available of the area we defined above.
print(json.dumps(result_optical, sort_keys=True, indent=4, separators=(‘,’, ‘: ‘)))
This also prints out the result so you can get an idea of what it looks like. Documentation about the result can be found here. Any of the fields here can be passed as named parameters to the search functions to filter things down. Note that some of them may not cause an error but will cause strange results. E.G asking for optical images with a sarProductType or polarisation.
Now you have some information about possible images you will probably want to download one.
Downloading images
If you have asked for a recent image hopefully the search result you got will contain a download URL field. This means you can use the download method on the API
However if you have asked for something more than a few months ago probably won’t have a download URL and you’ll need to get it from the Long Term Archive. This means a request will need to be submitted to ask for the information, and you’ll then need to check until the data has been retrieved.
There are two methods to do this. Pass the search result object to the request method of the api and then call is_request_ready with the resulting id until it returns you a download URL.
However, this can become a little cumbersome when dealing with large numbers of images, so we created a bulk download tool to take care of this process for you.
Bulk Downloads
import queue
done_queue = queue.Queue()
downloader = SeDASBulkDownload(sedas, output_path, parallel=3, done_queue=done_queue)
downloader.add(result_optical[‘products’])
while not downloader.is_done():
try:
print(completed)
except queue.Empty:
downloader.shutdown()
First we create a Queue so we can be told when downloads have completed. Then we create a SeDASBulkDownload object giving it our api object, a path where it should save the data, the maximum number of simultaneous downloads to do and the queue to be notified when we are done.
If you do not need to be notified when done, you can skip providing the done_queue. The correct value for the parallel download parameter will probably depend on your internet connection and machine but doing more than one download at a time is often faster.
The bulk downloader will spawn background threads to deal with the downloads in parallel. It will also take care of waiting for LTA requests to complete while downloading further data.
The SeDASBulkDownload class will log some status messages at info and debug levels. If you find this too chatty turn it down, but it is useful to know what is going on sometimes.
Conclusion
So now we know how to connect, search for, and download sentinel data for an area of interest we have provided. Please let us know if this is useful. We would love to hear from you. Contact the SEDAS team here.
