L’utilisation avancée des APIs GEODES requiert à minima l’accès à un terminal et à l’outil en ligne de commande Curl.
L’outil Postman offre également une IHM facilitant la découverte du catalogue GEODES et de ses APIs.
Optionnel :
- Il peut parfois être nécessaire de configurer un proxy en exportant la variable suivante : export https_proxy=<proxy>
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:
|
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 :
- Ouvrir votre navigateur internet
- Accéder au portail GEODES en utilisant le lien suivant : https://geodes-portal.cnes.fr
- 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 :
|
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 :
|
La réponse retournée est de la forme suivante :
|
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.
