You can run this notebook in a live session with Binder.

Search for products by tile

eodag allows to search for products by geometric features that match a location query, see the API user guide for an introduction to this concept.

In this tutorial we will use a shapefile that represents the Sentinel 2 tiling grid to search for Sentinel 2 Level-1C products with PEPS at a specific tile. In this shapefile each tile is defined by its centroid and a tile_id attribute (e.g. 29PMT). This shapefile was created by downloading first the Sentinel 2 tiling grid (MGRS) provided by ESA as a KML file. It was then converted as a shapefile and processed to compute the centroids. We use the tile’s centroid here as eodag returns products that intersects the user defined search area. Since tiles overlap with each other, using the polygons instead of the centroids would return more tiles than just the one we target.

import os
from zipfile import ZipFile

# Interactive mapping
import folium
from folium.plugins import TimestampedGeoJson
# pyshp: to read shapefiles
import shapefile

from eodag import EODataAccessGateway
from eodag import setup_logging


A workspace directory is created to store the files that will be generated.

workspace = "eodag_workspace_locations_tiles"
if not os.path.isdir(workspace):

You should have an auxdata folder next to this tutorial’s file. It contains a shapefile that is needed to run this tutorial correctly.

sentinel2_grid_zip = os.path.join("auxdata", "sentinel2_tiling_grid_centroids.zip")
if not os.path.isfile(sentinel2_grid_zip):
    raise FileNotFoundError("Auxdata not found, please check your configuration.")
# We unzip the archived shapefile.
with ZipFile(sentinel2_grid_zip, "r") as fzip:

In this tutorial products will just be searched for, not downloaded. We don’t need to set up PEPS credentials to search for products. If you wish to download them, you should set the credentials beforehand, using these two environment variables for instance.


Logging is activated to better inspect what eodag does internally.

setup_logging(2)  # INFO level

The default search criteria consists of a time period in June 2018 and eodag’s product type identifier for Sentinel 2 Level-1C products.

default_search_criteria = dict(

Add a locations configuration

We check and store the content of this shapefile.

sentinel2_shp = os.path.join('auxdata', 'sentinel2_tiling_grid_centroids.shp')
with shapefile.Reader(sentinel2_shp) as shp:
    print(shp, "\n")
    print("fields:", shp.fields)
    shaperecs = shp.shapeRecords()
shapefile Reader
    56686 shapes (type 'POINT')
    56686 records (2 fields)

fields: [('DeletionFlag', 'C', 1, 0), ['tile_id', 'C', 5, 0]]

It has about 57 000 tiles/polygons and a field tile_id.

We create a YAML file to configure this new location selector, we will refer to it with s2_tile_centroid.

# Save the locations configuration file.
locations_yaml_content = """
  - name: s2_tile_centroid
    path: {}
    attr: tile_id

locations_filepath = os.path.abspath(os.path.join(workspace, "custom_locations.yml"))

with open(locations_filepath, "w") as f_yml:

An instance of an EODataAccessGateway class is created, it makes use of this location configuration file.

dag = EODataAccessGateway(locations_conf_path=locations_filepath)
2021-04-12 21:30:54,673-15s eodag.config                     [INFO    ] Loading user configuration from: /home/maxime/.config/eodag/eodag.yml
2021-04-12 21:30:55,523-15s eodag.core                       [INFO    ] Locations configuration loaded from /home/maxime/TRAVAIL/06_EODAG/01_eodag/eodag/docs/notebooks/tutos/eodag_workspace_locations_tiles/custom_locations.yml

We want to look for Sentinel 2 Level-1C products. We can check whether this product type is offered by PEPS (as configured in eodag). If so, PEPS is set as the provider used to search for products.

"peps" in dag.available_providers("S2_MSI_L1C")