yannforget / asarapi

Search and download ERS-1, ERS-2, and Envisat products.

Description

ASARapi is a simple Python command-line program that allows you to search the ESA Online Catalogue for SAR images produced by the ERS-1 (1991-2000), ERS-2 (1995-2011), or Envisat (2002-2012) satellites and to download them.

The following collections are supported:

• ASA_IMP_1P: Level 1 products for ENVISAT ASAR Image Mode Precision Image.
• ASA_IMS_1P: Level 1 products for ENVISAT ASAR Image Mode Single-Look Complex.
• SAR_IMP_1P: Level 1 products for ERS SAR Precision Image.
• SAR_IMS_1P: Level 1 products for ERS SAR Single-Look Complex.

Installation

ASARapi can be installed using pip.

pip install asarapi

Usage

Sync database

ASARapi is designed to work with a local SQLite dump of the ESA Online Catalogue in order to speed up spatial queries. Therefore, the database must be downloaded before using the program by running the sync subcommand.

asarapi sync

The file will be stored in your user data directory, e.g. ~/.local/share/asarapi on Linux, /Users/<user>/Library/Application Support/asarapi on OSX, or C:\Users\<user>\AppData\Local\asarapi on Windows.

Please see yannforget/esa-online-catalogue for further details regarding the scraping of the ESA Online Catalogue.

Search the catalog

Usage

Usage: asarapi search [OPTIONS]

  Search for ERS and Envisat products.

Options:
  --geojson PATH                  GeoJSON footprint.
  --start TEXT                    Start date (YYYY-MM-DD).
  --stop TEXT                     Stop date (YYYY-MM-DD).
  --latlon FLOAT...               Decimal lat/lon.
  --bounds FLOAT...               (max_lat, max_lon, min_lat, min_lon).
  --platform TEXT                 Platform of interest (ERS or ENVISAT, default = all)
  --product TEXT                  Product type (Precision (default) or Single-Look).
  --polarisation TEXT             Polarisation channels (default = all).
  --orbit [ascending|descending]  Orbit direction (default = all).
  --contains                      Footprint contained by input geom (default = False).
  --limit INTEGER                 Max. number of results (default = 500).
  --output PATH                   Output CSV file.
  --help                          Show this message and exit.

By default, asarapi search will output the product IDs that satisfy the query. A CSV file containing the metadata and the footprint of each scene can be generated with the --output option.

Examples

# All available products between 1995 and 1999 according to an area of interest
# defined in a GeoJSON file.
asarapi search --start 1995-01-01 --stop 1999-12-31 --geojson aoi.geojson

# All available products between 1995 and 1999 that intersect the given location
asarapi search --start 1995-01-01 --stop 1999-12-31 --latlon 16.27 -0.04

# Envisat Single-Look Complex images for a given AOI
asarapi search --start 2002-01-01 --stop 2005-01-01 --geojson aoi.geojson \
        --platform envisat --product single-look --orbit descending

# Write the result of a query in a .CSV file
asarapi search --start 1995-01-01 --stop 1999-12-31 --geojson aoi.geojson \
        --output products.csv

Download a product

Usage

To download products, you will need ESA SSO credentials. Register for free here.

Usage: asarapi download [OPTIONS] PRODUCT

  Download an ERS or Envisat product.

Options:
  -u, --username TEXT   ESA SSO username.
  -p, --password TEXT   ESA SSO password.
  -o, --outputdir PATH  Output directory.
  --help                Show this message and exit.

Example

asarapi download -u <esa_sso_username> -p <esa_sso_password> \
        "SAR_IMP_1PNESA20030215_091621_00000015A081_00465_40900_0000"

API

ASARapi can also be used in custom Python scripts:

from datetime import datetime
from shapely.geometry import Point
from asarapi.catalog import query
from asarapi.download import log_in, log_out, request_download

username = esa_sso_username
password = esa_sso_password
output_dir = '../data'
location = Point(16.84, -0.04)

results = query(
    area=location.wkt,
    start=datetime(1999, 1, 1),
    stop=datetime(2002, 1, 1),
    orbit='ascending'
)

session = log_in(username, password)
for product_id in results.index:
    request_download(session, product_id, output_dir)
log_out(session)