ISDeform STAC API documentation¶
ISDeform offers three access points:
- The STAC Browser interface is available at http://isdeform.opgc.fr/browser/. It is a simple way to access the data but the search is limited.
- The API allows advanced users to explore the data programatically, using Python "pystac_client". The URL for the API is http://isdeform.opgc.fr/pgstac.
- The Download tool is an accessory tool that lists the files for a given product, both the original data and the STAC versions. This tool can be consulted at http://isdeform.opgc.fr/download/.
This page provides some examples on how to use the API.
Note about the API¶
At the moment, the API is using the PostgreSQL STAC API stac-fastapi-pgstac to execute the requests and return the responses, but STAC Browser is not. The reason is that pgstac does not, at the moment, allow for hierarchical STAC content (ie. collections within collections). The data for ISDeform is meant to be structured in a more complexe way, and this is why STAC Browser relies on the STAC files directly and not on their equivalent in the database.
When we ingest data in PostgreSQL, we have to flatten the collections to respect the expected format (Catalog > Collection > Item). The benefit of using stac-fastapi-pgstac is that it offers advanced search options that are not available in STAC Browser with the standard files.
It has been decided that we would store both the files both in STAC format and in a PostgreSQL database for the moment, and that STAC Browser would represent the data as they are meant to be seen. An advanced user can use the API to search for collections and items, or download the STAC files from the download tool and parse them directly.
Prerequisites¶
pystac-client is a Python tool to interrogate STAC APIs. This is the best and easiest way to use the API, as this will automatically retrieve the data and deal with pagination. If you do not or can not use pystac-client, you can always use classic HTTP POST/GET requests.
To start using the API, you should create your environment and install pystac-client:
python -m venv .venv
source .venv/bin/activate
pip install pystac-client
Note that pystac-client can also be used on Windows, Mac and Jupyter Notebooks.
The documentation for pystac-client is available here. Make sure to consult it to adapt the code to your needs.
Examples¶
Get the main catalog¶
In [4]:
# load the client
from pystac_client import Client
# open the client
url = "http://isdeform.opgc.fr/pgstac/"
catalog = Client.open(url)
# display the catalog as a STAC object
catalog
Out[4]:
<Client id=stac-fastapi>
List of all the available collections¶
In [10]:
for collection in catalog.get_collections():
print(f"• {collection.id} : {collection.title}")
• 05ef8d62-da41-11ee-9f22-0242c0a87004 : Earthquake Iran 2017 • 0ea80444-088f-11ef-89f9-0242c0a87003 : FROM JOB 1490 • 153a6570-c4c1-11ee-afa4-0242c0a87002 : NONREG_La_Reunion_2023 • 1939da31-5ef6-4d24-8517-ae728cf64604 : Earthquake Iran 2017 • 1b1ccb1f-32ab-429c-a765-c21c5964e70a : 1b1ccb1f-32ab-429c-a765-c21c5964e70a • 1c1b0a64-8a52-11ef-960d-0242c0a87003 : Amatrice_D22_v1 • 2bc06e78-b45b-11ee-ad34-0242c0a87002 : NONREG_Equateur_2022 • 7f3d1c26-d8a6-11ee-9099-0242c0a87004 : ColcaValley_D25 • 8a8de3f9-2da7-4715-abbc-ef8d13a84c57 : 8a8de3f9-2da7-4715-abbc-ef8d13a84c57 • 93434689-5a76-4e79-b141-e15f5dc9d693 : 93434689-5a76-4e79-b141-e15f5dc9d693 • 97576bee-c43e-11ee-b749-0242c0a87002 : Earthquake Morocco September 2023 • b9ec4510-1742-11ef-8833-0242c0a87003 : Colca Valley landslides • c5bd5e76-9d88-11ee-a5c3-0242c0a87002 : FROM JOB 1278 • c8560cb7-9c16-4cef-a1ea-44eabecae9ac : c8560cb7-9c16-4cef-a1ea-44eabecae9ac • c8f09a4c-04b4-4d50-891c-3ad77c08b72f : c8f09a4c-04b4-4d50-891c-3ad77c08b72f • cbb9f2be-db0c-11ee-8d50-0242c0a87004 : Turquie 2023 • ccae7598-e59a-4877-ac34-cb94efe66642 : ccae7598-e59a-4877-ac34-cb94efe66642 • ccaf4f62-b45a-11ee-b91d-0242c0a87002 : NONREG_Merapi_2022 • d99bfb2a-c12f-4ef0-80e9-7a2ab2f57a18 : d99bfb2a-c12f-4ef0-80e9-7a2ab2f57a18 • df6d97d8-4b7f-4ee0-becb-8b2a3fa0dd9f : df6d97d8-4b7f-4ee0-becb-8b2a3fa0dd9f • e817a8c7-a65d-4855-b2d7-1bc3308861d6 : e817a8c7-a65d-4855-b2d7-1bc3308861d6 • ebded694-da09-11ee-af92-0242c0a87004 : ridgecrest • ed6f089c-6935-11ef-8dd0-0242c0a87003 : berarde88a • f03cdf92-c1a9-11ee-969b-0242c0a87002 : NONREG_Arcachon_2022 • fd40f570-c1a9-11ee-8b10-0242c0a87002 : NONREG_Mexico_2021
Get a single collection, using its id¶
In [11]:
catalog.get_collection("1939da31-5ef6-4d24-8517-ae728cf64604")
Out[11]:
<CollectionClient id=1939da31-5ef6-4d24-8517-ae728cf64604>
All the items of a collection¶
In [13]:
collection_id = "1939da31-5ef6-4d24-8517-ae728cf64604"
items = catalog.get_collection(collection_id).get_items()
print(f"Items for collection \"{collection_id}\":")
i = 0
for item in items:
print(f"• {i+1}: {item.id}")
i += 1
print(f"{i} items were returned")
Items for collection "1939da31-5ef6-4d24-8517-ae728cf64604": • 1: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_inw_item • 2: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_inwf_item • 3: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_inu_item • 4: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_coh_item • 5: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_aux_lut_item • 6: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_aux_dem_item • 7: 1939da31-5ef6-4d24-8517-ae728cf64604_radar_aux_cosenu_item • 8: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_interferogram_20171107_20171119_4rlks_inw_item • 9: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_interferogram_20171107_20171119_4rlks_inwf_item • 10: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_interferogram_20171107_20171119_4rlks_inu_item • 11: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_interferogram_20171107_20171119_4rlks_coh_item • 12: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_aux_lut_item • 13: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_aux_dem_item • 14: 1939da31-5ef6-4d24-8517-ae728cf64604_geo_aux_cosenu_item 14 items were returned
An item of a collection¶
In [14]:
collection_id = "1939da31-5ef6-4d24-8517-ae728cf64604"
item_id = "1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_coh_item"
catalog.get_collection(collection_id).get_item(item_id)
Out[14]:
<Item id=1939da31-5ef6-4d24-8517-ae728cf64604_radar_interferogram_20171107_20171119_4rlks_coh_item>
List of the properties of an item¶
Take an item and read its properties. We assume that all items have the same set of properties.
Properties can be used in the search.
In [22]:
properties = {}
for collection in catalog.get_collections():
for item in collection.get_items():
for key in item.properties.keys():
properties[key] = type(item.properties[key]).__name__
break
break
print("Item properties and type:")
for key in sorted(properties):
print(f"• {key}: {properties[key]}")
Item properties and type: • First_line_utc: str • Last_line_utc: str • acquisitionInformation: list • alongTrackBaseline: str • antennaSide: str • appliedAlgorithmDescription: str • appliedCorrections: str • azimuthPixelSize: str • bandDescription: list • boundingBoxFeature: str • boundingBoxRadar: str • completionDate: str • constellation: str • created: str • date: str • datesOfSARScenes: str • datetime: str • description: str • digitalElevationModelId: str • farRangeLookAngle: str • footprintBoundingBox: str • geographicCSTypeCode: str • instruments: list • keywords: list • license: str • licenses: str • links: dict • lookupTableId: str • mainReference: str • mapOfLOSVectorId: str • masterSARImageId: str • mode: str • nearRangeLookAngle: str • numberOfBursts: str • numberOfLooksAzimuth: str • numberOfLooksRange: str • orbitDirection: str • parallelBaseline: str • parameters: dict • parent_collection: str • perpendicularBaseline: str • platforms: list • polarisation: str • processing:level: str • processingId: str • productFormat: str • productId: str • productSize: str • productType: str • providers: list • rangePixelSize: str • relativeOrbitNumber: str • sar:center_frequency: float • sar:frequency_band: str • sar_ext:wavelength: float • sat:orbit_state: str • sat:platform_international_designator: str • sat_ext:platform_international_designators: list • sci:publications: list • self_href: str • sensor: str • serviceUsedForGeneration: str • slaveSARImageId: str • softwareVersion: str • spatialResolution: list • startDate: str • status: str • superMasterSARImageId: str • title: str • updated: str • usedDigitalElevationModel: str • userId: str • uuid: str • valueUnit: list • wavelength: str
Search for collections, using different parameters¶
Apply some of the following parameters to restrain the search, otherwise all the collections will be returned
cf. https://pystac-client.readthedocs.io/en/stable/api.html#collection-search
In [24]:
collections = catalog.collection_search(
#max_collections = None, # by default, all the collections are retrieved in several GET requests
#limit = 100, # number of results per page
#bbox = [25.7699333533499, 35.8988513697479, 44.883429385201396, 42.26308036891345],
#datetime = ["2024-12-07T00:00:00.000Z", "2024-12-09T00:00:00.000Z"], # DateTime objects are also allowed
q = "iran", # free-text search, the tag will be searched in the id, title and keywords
sortby = "-title"
)
print(f"{collections.matched()} collections found:")
for collection in collections.collections():
print(f"• {collection.id} ({collection.title})")
2 collections found: • 1939da31-5ef6-4d24-8517-ae728cf64604 (Earthquake Iran 2017) • 05ef8d62-da41-11ee-9f22-0242c0a87004 (Earthquake Iran 2017)
Search for items, using different parameters¶
Apply one or more of the following parameters to restrain the search
cf. https://pystac-client.readthedocs.io/en/stable/api.html#item-search
In [27]:
items = catalog.search(
max_items = 25, # by default, all the items are retrieved in several requests
#limit = 100, # number of results per page
#ids = ["Earthquake Iran 2017_4_range_looks_radar_digital_elevation_model"], # search items per ids
#collections = ["Earthquake Iran 2017_auxiliary_data_collection"], # return 3 items
bbox = [25.7699333533499, 35.8988513697479, 44.883429385201396, 42.26308036891345],
#datetime = ["2024-12-07T00:00:00.000Z", "2024-12-09T00:00:00.000Z"], # DateTime objects are also allowed
#query = { # search for specific properties
# "processing:id" : {"eq": "GDMSARUGA_df6d97d8-4b7f-4ee0-becb-8b2a3fa0dd9f"}, # this alone returns 55 items
# "gsd": {"ne": 0},
# "keywords": {"eq": ["wrapped","interferogram"]}, # possible to match a list, but not search for one element in the list
#},
sortby = "-id"
)
# print(f"{items.matched()} items found:") # the total number of result is not known until the iterator is fully read
for item in items.items():
print(f"• {item.id}")
• cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230209_20230221_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230209_20230221_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230209_20230221_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230221_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230221_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230221_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230209_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230209_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_interferogram_20230128_20230209_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_aux_tcoh_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_aux_lut_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_aux_dem_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_radar_aux_cosenu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230209_20230221_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230209_20230221_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230209_20230221_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230221_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230221_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230221_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230209_2rlks_inw_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230209_2rlks_inwf_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_interferogram_20230128_20230209_2rlks_inu_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_aux_tcoh_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_aux_lut_item • cbb9f2be-db0c-11ee-8d50-0242c0a87004_geo_aux_cosenu_item