1. Rechercher via l’API STAC

L’API STAC GEODES est accessible depuis la landing page : https://geodes-portal.cnes.fr/api/stac.

Elle expose les endpoints :

• /collections : Permet de rechercher des jeux de données
• /items: Permet de rechercher des produits
• /collections/#collectionId : Permet de rechercher une collection spécifique à partir de son id
• /collections/#collectionId/items:  Permet de rechercher les items d’une une collection spécifique à partir de son id
• /collections/#collectionId/items/#itemId:  Permet de rechercher un item spécifique d’une une collection spécifique à partir de l’id de la collection et de l’id de l’item.

Les opérateurs supportés par l’API STAC GEODES sont :

Mot clé	Utilité	Exemple
eq	Chercher une valeur exacte	“sat:relative_orbit” : {“eq”:51}
neq	Chercher les valeurs différentes	“platform”:{“neq”:”S1B”}
in	Chercher plusieurs valeurs	“sar:polarizations”: {“in”: [“VV”,”VV VH”]}
contains	Contient une valeur	“mission”: {“contains”:”theia”}
lte	Cherche des valeurs inférieures ou égales à	“eo:cloud_cover”:{“lte”:30}
gte	Cherche des valeurs supérieures ou égales à	“start_datetime”:{“gte”:”2027-01-01T00:00:00Z”}

1.1 Rechercher des jeux de données

La liste des collections GEODES est accessible ici :https://geodes-portal.cnes.fr/api/stac/collections

Les métadonnées des collections GEODES sont présentées ci-dessous :

Attribut	Type	Recherche	Description	Valeurs possibles ou exemple ou pattern
title	String	oui	Titre de la collection	“PEPS Sentinel-1 Level1”
description	String	oui	Description de la collection	“Sentinel-1 Level-1 products are the baseline products […] ”
dataset	String	oui	Référence de la collection	“PEPS_S1_L1”
gsd	String		Résolution spatiale le plus fine, en mètres	5
platform	String	oui	Plateformes d’acquisition des données	sentinel-2, multisat
processing:level	String	oui	Niveau de produit	LEVEL1
constellation	String		Nom de la mission	sentinel-1, sentinel-2, etc…
instruments	String		Capteur	C-SAR
temporal_resolution	String		Résolution temporelle en jours	144
total_items	Number		nombre de produits dans cette collection	10
keywords	String	oui	Mots clés associés à la collection	[“s1″,”sentinel-1″,”l1″,”sar”,”grd”,”slc”]
missions	String		Projets chapeau	spécifique Postel (cyclopes, polder, …)
providers	JSON		Fournisseurs de la collection
missions	String	oui	Projet en charge de la collection

Il est possible de rechercher des jeux de données du catalogue et leurs métadonnées avec une requête de type :

curl -k -H "Content-Type: application/json" -X POST -d '{"page":1, "query": { <ATTRIBUTS RECHERCHES> }}' "https://geodes-portal.cnes.fr/api/stac/collections"

Le nombre de collections correspondantes aux critères de recherche est disponible dans l’attribut “matched” de la réponse.

Exemples

La requête suivante permet de trouver une collection dont les mots-clés contiennent l’expression “grd” :

curl -k -H "Content-Type: application/json" -X POST -d '{"page":1, "query": {"keywords": {"contains":"grd"}}}' "https://geodes-portal.cnes.fr/api/stac/collections"

La requête peut être également lancer avec un get  pour un résultat rapide:

curl -k -X GET "https://geodes-portal.cnes.fr/api/stac/collections"X POST -d '{"page":1, "query": {"keywords": {"contains":"grd"}}}' "https://geodes-portal-prod.cnes.fr/api/search/collections"

1.2 Rechercher des produits

La liste des produits GEODES est accessible ici :https://geodes-portal.cnes.fr/api/stac/items

La liste des métadonnées de produits offertes par l’API GEODES est accessible ici: https://geodes.cnes.fr/metadonnees-offertes-par-lapi-stac-de-geodes/

Il est possible de rechercher des produits du catalogue et leurs métadonnées avec la requête suivante:

curl -s -k -H "Content-Type: application/json" -X POST -d '{sortBy: [{ direction: " <SENS> ", field: " <ATTRIBUT DE TRI> " }],"page":1,"query":{ <ATTRIBUTS RECHERCHES> }}' https://geodes-portal.cnes.fr/api/stac/items

Le nombre de produits correspondants aux critères de recherche est disponible dans l’attribut “matched” de la réponse.

La limite d’affichage est configurable avec une valeur maximale de 80. Au delà de 80 éléments, il faut parcourir les pages de réponses pour obtenir la suite.

Chaque requête retourne une liste de produits et leurs métadonnées au format JSON.

Le filtre sortBy est optionnel et permet d’ordonner la réponse selon les valeurs d’un attribut spécifié :

“direction” correspond au sens choisi pour le tri. Il y a 2 valeurs possibles : “asc” pour ascendant et “dsc” pour descendant. 

“field” correspond à l’attribut choisi pour le tri. Il doit faire partie de la liste d’attribut donnée précédemment.  

Exemples

• Trouver des produits de type S1A SLC dont la date de début d’acquisition est entre le 20 Juin 2023 à 4h21m51s et le 28 Juin 2023 à  4h21m51s et dont la polarisation est VV et le mode de capteur est soit IW soit EW :

curl -k -H "Content-Type: application/json" -X POST -d '{"page":1,"query":{"start_datetime":{"lte":"2023-06-28T04:21:51.000Z","gte":"2023-06-20T04:21:51.000Z"},"sar:polarizations" : {"in": ["VV"]}, "platform": {"in": ["S1A"]},"product:type": {"in": ["SLC"]},"sar:instrument_mode": {"in": ["IW","EW"]}}}' "https://geodes-portal.cnes.fr/api/stac/items"

• Trouver 10 produits SENTINEL2 L1C dont la couverture nuageuse est inférieure à 50% et dont l’emprise intersecte une bbox donnée :

curl -k -H "Content-Type: application/json" -X POST -d '{ "page":1,"limit":10, "bbox":[148,-30,153,-28], "query": {"dataset": {"in":["PEPS_S2_L1C"]}, "eo:cloud_cover": {"lte":50}}}' "https://geodes-portal.cnes.fr/api/stac/items"

• Trouver le produit dont le nom est S2A_MSIL1C_20230303T071811_N0509_R006_T39UYU_20230303T080614:

curl -k -H "Content-Type: application/json" -X POST -d '{ "page":1,"limit":10, "bbox":[148,-30,153,-28], "query": {"identifier":{"contains":"S2A_MSIL1C_20230303T071811_N0509_R006_T39UYU_20230303T080614"}}' "https://geodes-portal.cnes.fr/api/stac/items"

• Trouver 10 produits SENTINEL2 L1C dont la couverture nuageuse est inférieure à 10% et ordonné selon le taux de couverture nuageuse :

curl -k -H "Content-Type: application/json" -X POST -d '{ "page":1,"limit":10, sortBy: [{ direction: "asc", field: "eo:cloud_cover" }] ,"query": {"dataset": {"in":["PEPS_S2_L1C"]}, "eo:cloud_cover": {"lte":10}}}' "https://geodes-portal.cnes.fr/api/stac/items"

• Trouver les produits SENTINEL2 L1C diffusés par GEODES en janvier 2022 (exemple de requête utile pour du moissonnage)

curl -k -H "Content-Type: application/json" -X POST -d '{"page":1,"query":{"dataset":{"in":["PEPS_S2_L1C"]}, "datetime":{"lte":"2022-01-31T23:59:59.999Z"}, "datetime":{"gte":"2022-01-01CT00:00:00.000Z"}}}' https://geodes-portal.cnes.fr/api/stac/items

1.3 Découvrir les métadonnées d’une collection spécifique

La liste des métadonnées d’une collection spécifique est accessible ici :https://geodes-portal.cnes.fr/api/stac/collections/#collectionId

CollectionId représente l’id d’une collection qui peut être récupérer avec une requête sur les collections.

Exemple :

• Trouver les métadonnées de la collection “Sentinel-1 Level 1” :

curl -k -X GET "https://geodes-portal.cnes.fr/api/stac/collections/PEPS_S1_L1"

1.4 Rechercher des items une collection spécifique

La liste des produits d’une collection spécifique est accessible ici :https://geodes-portal.cnes.fr/api/stac/collections/#collectionId/items

CollectionId représente l’id d’une collection qui peut être récupérer avec une requête sur les collections.

Exemple :

• Trouver les produits de la collection “Sentinel-1 Level 1”: https://geodes-portal.cnes.fr/api/stac/collections/PEPS_S1_L1/items

curl -k -X GET "https://geodes-portal.cnes.fr/api/stac/collections/PEPS_S1_L1/items"

1.5 Rechercher un item spécifique

La liste des métadonnées d’un produit spécifique est accessible ici :https://geodes-portal.cnes.fr/api/stac/collections/#collectionId/items/#itemId

itemId représente l’id d’un item, il est de la forme “URN:…”

Exemple :

• Trouver les métadonnées du produit “S1A_IW_SLC__1SDV_20230205T213855_20230205T213925_047106_05A6BD_61EA”:

curl -k -X GET "https://geodes-portal.cnes.fr/api/stac/collections/PEPS_S1_L1/items/URN:FEATURE:DATA:gdh:d0264bba-0719-35da-8d48-d65a72cfa58e:V1"

2. Générer une clé d’API

2.1. S’authentifier sur le portail GEODES

Dans un premier temps, vous devez vous connecter au portail GEODES afin de générer une clé d’API.

Voici les étapes à suivre :

1. Ouvrir votre navigateur internet
2. Accéder au portail GEODES en utilisant le lien suivant :  https://geodes-portal.cnes.fr
3. S’authentifier via le bouton Log In en haut à droite :

Une fois redirigé sur la page de connexion, veuillez saisir votre adresse e-mail, votre mot de passe, puis cliquer sur le bouton “Login” :

Si vous possédez déjà un compte GEODES, passez directement à l’étape “3.3 Générer une clé d’API“.

2.2. Créer un compte

Afin de créer un compte, veuillez cliquer sur le bouton “Create account”,

Puis, renseignez les informations ci-dessous :

Attention, tous les champs sont obligatoires. Le mot de passe doit contenir au moins une majuscule, un chiffre et un caractère spécial et atteindre une longueur d’au moins 8 caractères.

Un email de vérification vous sera envoyé avec un lien de validation de compte. Dès réception du mail, veuillez cliquer sur le lien afin de valider votre compte.

2.3. Générer une clé d’API

Veuillez cliquer sur votre nom en haut à droite et choisir l’option “My information” :

Vous pouvez désormais choisir de générer une clé d’API en cliquant sur le bouton “Generate” :

Ensuite, la clé d’API sera générée et apparaîtra dans l’IHM.

Vous pouvez alors le copier dans le presse papier en cliquant sur l’icône dédiée.

Ensuite, vous devrez exporter une variable d’environnement APIKEY avec la clé d’API générée à l’étape “2.3 Générer une clé d’API“.

Voici un exemple :

export APIKEY="sSDFSGcxvjqRSDGFDDFGDFGDFGWSDFFSDGDFG"

Pour modifier votre clé d’API, cliquez sur l’icône de régénération. Votre clé d’API sera régénérée et remplacera l’ancienne clé dans l’IHM.

3. Télécharger un produit via l’API

Optionnel :

• Si vous utilisez les services de téléchargement depuis un terminal, il peut être pratique d’exporter une variable d’environnement APIKEY avec la clé d’API.

export APIKEY="Copier_ici_votre_clé_API"

L’API GEODES de recherche renvoie un JSON contenant des informations sur les produits correspondant à la recherche et notamment le lien de téléchargement des produits. Il est possible via un simple ensemble d’instructions Shell d’extraire le nom de l’archive du produit (contenant son identifiant) ainsi que son lien de téléchargement, en utilisant la commande suivante :

<COMMANDE CURL> | sed 's/,/\n/g' | grep zip | sed 's/assets\":{/\n/g' | grep href  | sed 's/{"href"://g'

Par exemple : 

curl -k -H "Content-Type: application/json" -X POST -d '{ "page":1,"limit":10, "query": {"dataType": {"in":["PEPS_S2_L1C"]}}}' "https://geodes-portal.cnes.fr/api/stac/search" | sed 's/,/\n/g' | grep zip | sed 's/assets\":{/\n/g' | grep href  | sed 's/{"href"://g'


Cela permet d’obtenir un résultat sous la forme :

“archive1″:”lien1”
“archive2″:”lien2”
“archive3″:”lien3”
“archive4″:”lien4”
“archive5″:”lien5”
“archive6″:”lien6”
“archive7″:”lien7”
“archive8″:”lien8”
“archive9″:”lien9”
“archive10″:”lien10”

en prenant en compte le “limit”: 10 de la requête.

Il suffit ensuite pour télécharger le produit de récupérer le lien désiré et de l’incorporer à la requête de la forme suivante :

curl -vvv -k -L -H "X-API-Key: $APIKEY" -XGET "<LIEN TELECHARGEMENT>" --output <chemin vers fichier sortie>

Par exemple : 

curl -vvv -k -L -H "X-API-Key: $APIKEY" -XGET "https://geodes-portal.cnes.fr/api/download/URN:FEATURE:DATA:gdh:01202b44-2d76-36b8-9453-56bf907882bf:V1/files/6e5ffa91b66775844607711eae4e0483" --output SENTINEL2C_20250922-171411-673_L2A_T14SQE_C_V4-0.zip

Important : dans les scripts, bien penser à échapper le caractère ':' avec %3A  

4. Consulter la disponibilité d’un produit

Certains produits diffusés par GEODES sont stockés sur bande (Tier3) tandis que d’autres sont stockés sur disque (Tier2). Les APIs suivantes permettent de consulter le mode de stockage afin d’anticiper un téléchargement direct ou un téléchargement après restauration sur disque.

4.1. Disponibilité d’un produit

L’endpoint pour connaitre disponibilité d’un produit est : /availability/{NOM_DU_PRODUIT}

Il s’agit d’une requête GET.

curl -XGET -k -H "Content-Type:application/json" -H "X-API-Key: $APIKEY" -H "Prefer:respond-async" "<URL_DU_PORTAIL>/availability/{NOM_DU_PRODUIT}"

un exemple de requête

curl -XGET -k -H "Content-Type:application/json" -H "X-API-Key: $APIKEY" -H "Prefer:respond-async" "https://geodes-portal.cnes.fr/availability/S2A_MSIL1C_20161106T094202_N0500_R036_T32NNM_20230926T184801"

4.2. Disponibilité d’une liste de produits

Pour connaître le mode de stockage d’une liste de produits, utiliser une requête POST sur l’endpoint : /availability avec un body pouvant prendre la forme suivante : 

{     "product_ids": [         "URN_DU_PRODUIT_1",         "URN_DU_PRODUIT_2"     ] }

La requête retourne une réponse sous la forme :

{     "products": [{         "id": URN_DU_PRODUIT,         "files": [{           CHECKSUM           AVAILABLE           EXPIRATION_DATE         }]     }] }

Ci-dessous un exemple de requête 

curl -XPOST -k --data "@body.json" -H "Content-Type:application/json" -H "X-API-Key: $APIKEY" -H "Prefer:respond-async" "https://geodes-portal.cnes.fr/availability"

avec body.json :

{     "product_ids": [         "URN:FEATURE:DATA:gdh:d2101fa8-f135-3d12-bf1f-1a556a7d004e:V1",         "URN:FEATURE:DATA:gdh:b10f6b56-2ced-3702-ac30-18084223a08d:V1"     ] }

La réponse retournée est de la forme suivante :

{   "products": [     {       "id": "URN:FEATURE:DATA:gdh:b10f6b56-2ced-3702-ac30-18084223a08d:V1",       "files": [         {           "checksum": "44cd7c9f00a9bfae6ffa7695be2d4a60",    //fichier du quicklook           "available": true         },         {           "checksum": "c30b12f15728216f20854d126bfd098f",    //le produit URN:FEATURE:DATA:gdh:b10f6b56-2ced-3702-ac30-18084223a08d:V1 est disponible au téléchargement           "available": true,           "expiration_date": "2025-03-21T09:39:31Z"         }       ]     },     {       "id": "URN:FEATURE:DATA:gdh:d2101fa8-f135-3d12-bf1f-1a556a7d004e:V1",       "files": [         {           "checksum": "2d363e1cd6ba42a5b67c52c36ca1b13f",   //fichier du quicklook           "available": true         },         {           "checksum": "491e775f56609aa38e7806dbfabc5499",   //le produit URN:FEATURE:DATA:gdh:d2101fa8-f135-3d12-bf1f-1a556a7d004e:V1 est stocké sur le glacier Tier3           "available": false         }       ]     }   ] }

5. Pour les utilisateurs Python

PyGEODES est un outil de recherche et téléchargement des produits catalogués dans GEODES.

L’ensemble des informations pour installer et utiliser cet outil est disponible sur Github : pygeodes — pygeodes v0.1.0 Manual

Vous trouverez également dans cette documentation des exemples pour vous accompagner dans sa prise en main.

En cas de questions/remarques sur l’outil PyGEODES, merci de nous contacter via le formulaire de contact.