Use Case - Collection Search (IDN)#
This chapter provides a comprehensive and detailed process about how to implement a WGISS OpenSearch client, which includes how to retrieve the OSDD for the collection of interest, and how to build an OpenSearch request.
IDN Systems#
The IDN, CMR OpenSearch (for IDN), and the GCMD’s Keyword Management Service (KMS) only have operational systems which end-users can access.
IDN site is available to all users. Location: https://idn.ceos.org/
OpenSearch API for IDN (via CMR). Production instance is available to all users. Location: https://cmr.earthdata.nasa.gov/opensearch/
KMS - production instance is available to all users. Location: https://gcmd.earthdata.nasa.gov/kms/capabilities?format=html
The IDN site search interface and the CMR OpenSearch production instances will provide access to all collections which have been registered in the IDN. The KMS production instance will provide access to all approved GCMD keywords registered by IDN providers.
Retrieve Collections via IDN OpenSearch#
CEOS OpenSearch supports searching for collections through the IDN. Searching for granules in a specific collection is supported at the data partners via the Granule Gateways (see chapter “CWIC” and chapter “FedEO”). It executes a collection or inventory search, as appropriate, and returns the matching results. In order to create a valid request, clients have to obtain the IDN OpenSearch OSDD and fill request parameters with proper values.
Step 1
Obtain the IDN OpenSearch OSDD to formulate a valid IDN OpenSearch request.
URL_OSDD = "https://cmr.earthdata.nasa.gov/opensearch/collections/descriptor_document.xml?clientId=ceosOpenSearchDoc"
The template of the OpenSearch request is available under the <Url> element corresponding to the media type (Atom) in the OSDD and is included below.
<?xml version="1.0" ?><os:OpenSearchDescription xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:echo="https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#atom" xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/" xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/" xmlns:params="http://a9.com/-/spec/opensearch/extensions/parameters/1.0/" xmlns:referrer="http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0" xmlns:eo="http://a9.com/-/opensearch/extensions/eo/1.0/" xmlns:atom="http://www.w3.org/2005/Atom">
<os:ShortName>CMR Collections</os:ShortName>
<os:Description>NASA CMR Collection search using geo, time and parameter extensions</os:Description>
<os:Contact>echodev@echo.nasa.gov</os:Contact>
<os:Url type="application/atom+xml" rel="collection" params:method="GET" template="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword={os:searchTerms?}&instrument={echo:instrument?}&satellite={eo:platform?}&boundingBox={geo:box?}&lat={geo:lat?}&lon={geo:lon?}&radius={geo:radius?}&geometry={geo:geometry?}&placeName={geo:name?}&startTime={time:start?}&endTime={time:end?}&cursor={os:startPage?}&numberOfResults={os:count?}&offset={os:startIndex?}&uid={geo:uid?}&hasGranules={echo:hasGranules?}&isCwic={echo:isCwic?}&isGeoss={echo:isGeoss?}&isCeos={echo:isCeos?}&isEosdis={echo:isEosdis?}&isFedeo={echo:isFedeo?}&provider={echo:provider?}&clientId=ceosOpenSearchDoc">
<params:Parameter name="keyword" uiDisplay="Search terms" value="{os:searchTerms}" title="Inventory with terms expressed by these search terms" minimum="0">
<atom:link rel="profile" href="http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html" title="This parameter follows the elastic search free text search implementations"/>
</params:Parameter>
<params:Parameter name="instrument" uiDisplay="Instrument" value="{echo:instrument}" title="Inventory associated with a satellite instrument expressed by this short name" minimum="0"/>
<params:Parameter name="satellite" uiDisplay="Satellite" value="{eo:platform}" title="Inventory associated with a Satellite/platform expressed by this short name" minimum="0"/>
<params:Parameter name="boundingBox" uiDisplay="Bounding box" value="{geo:box}" title="Inventory with a spatial extent overlapping this bounding box" minimum="0"/>
<params:Parameter name="lat" uiDisplay="Latitude" value="{geo:lat}" title="Inventory with latitude in decimal degrees, must be used together with lon and radius" minimum="0" minInclusive="-90.0" maxInclusive="90.0"/>
<params:Parameter name="lon" uiDisplay="Longitude" value="{geo:lon}" title="Inventory with longitude in decimal degrees, must be used together with lat and radius" minimum="0" minInclusive="-180.0" maxInclusive="180.0"/>
<params:Parameter name="radius" uiDisplay="Radius" value="{geo:radius}" title="Inventory with the search radius in meters, must be used together with lat and lon" minimum="0" minInclusive="10" maxInclusive="6000000"/>
<params:Parameter name="geometry" uiDisplay="Geometry" value="{geo:geometry}" title="Inventory with a spatial extent overlapping this geometry" minimum="0">
<atom:link rel="profile" href="http://www.opengis.net/wkt/LINESTRING" title="This service accepts WKT LineStrings"/>
<atom:link rel="profile" href="http://www.opengis.net/wkt/POINT" title="This service accepts WKT Points"/>
<atom:link rel="profile" href="http://www.opengis.net/wkt/POLYGON" title="This service accepts WKT Polygons"/>
</params:Parameter>
<params:Parameter name="placeName" uiDisplay="Place name" value="{geo:name}" title="Inventory with a spatial location described by this name" minimum="0"/>
<params:Parameter name="startTime" uiDisplay="Start time" value="{time:start}" title="Inventory with a temporal extent containing this start time" minimum="0"/>
<params:Parameter name="endTime" uiDisplay="End time" value="{time:end}" title="Inventory with a temporal extent containing this end time" minimum="0"/>
<params:Parameter name="cursor" uiDisplay="Start page" value="{os:startPage}" title="Start page for the search result" minimum="0"/>
<params:Parameter name="numberOfResults" uiDisplay="Number of results" value="{os:count}" title="Maximum number of records in the search result" minimum="0" maxInclusive="2000"/>
<params:Parameter name="offset" uiDisplay="Start index" value="{os:startIndex}" title="0-based offset used to skip the specified number of results in the search result set" minimum="0"/>
<params:Parameter name="uid" uiDisplay="Unique identifier" value="{geo:uid}" title="Inventory associated with this unique ID" minimum="0"/>
<params:Parameter name="hasGranules" uiDisplay="Has granules" value="{echo:hasGranules}" title="Inventory with granules">
<params:Option value="true" label="Yes"/>
<params:Option value="false" label="No"/>
</params:Parameter>
<params:Parameter name="isCwic" uiDisplay="CWIC collection" value="{echo:isCwic}" title="Inventory related to CWIC">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isGeoss" uiDisplay="GEOSS collection" value="{echo:isGeoss}" title="Inventory related to GEOSS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isCeos" uiDisplay="CEOS collection" value="{echo:isCeos}" title="Inventory related to CEOS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isEosdis" uiDisplay="EOSDIS collection" value="{echo:isEosdis}" title="Inventory related to EOSDIS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isFedeo" uiDisplay="FedEO collection" value="{echo:isFedeo}" title="Inventory related to FedEO">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="provider" uiDisplay="Provider" value="{echo:provider}" title="Inventory associated with a provider" minimum="0"/>
<params:Parameter name="clientId" uiDisplay="Client identifier" value="{referrer:source}" title="Client identifier to be used for metrics" minimum="0"/>
</os:Url>
<os:Url type="text/html" rel="collection" params:method="GET" template="https://cmr.earthdata.nasa.gov/opensearch/collections.html?keyword={os:searchTerms?}&instrument={echo:instrument?}&satellite={eo:platform?}&boundingBox={geo:box?}&lat={geo:lat?}&lon={geo:lon?}&radius={geo:radius?}&geometry={geo:geometry?}&placeName={geo:name?}&startTime={time:start?}&endTime={time:end?}&cursor={os:startPage?}&numberOfResults={os:count?}&offset={os:startIndex?}&uid={geo:uid?}&hasGranules={echo:hasGranules?}&isCwic={echo:isCwic?}&isGeoss={echo:isGeoss?}&isCeos={echo:isCeos?}&isEosdis={echo:isEosdis?}&isFedeo={echo:isFedeo?}&provider={echo:provider?}&clientId=ceosOpenSearchDoc">
<params:Parameter name="keyword" uiDisplay="Search terms" value="{os:searchTerms}" title="Inventory with terms expressed by these search terms" minimum="0">
<atom:link rel="profile" href="http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html" title="This parameter follows the elastic search free text search implementations"/>
</params:Parameter>
<params:Parameter name="instrument" uiDisplay="Instrument" value="{echo:instrument}" title="Inventory associated with a satellite instrument expressed by this short name" minimum="0"/>
<params:Parameter name="satellite" uiDisplay="Satellite" value="{eo:platform}" title="Inventory associated with a Satellite/platform expressed by this short name" minimum="0"/>
<params:Parameter name="boundingBox" uiDisplay="Bounding box" value="{geo:box}" title="Inventory with a spatial extent overlapping this bounding box" minimum="0"/>
<params:Parameter name="lat" uiDisplay="Latitude" value="{geo:lat}" title="Inventory with latitude in decimal degrees, must be used together with lon and radius" minimum="0" minInclusive="-90.0" maxInclusive="90.0"/>
<params:Parameter name="lon" uiDisplay="Longitude" value="{geo:lon}" title="Inventory with longitude in decimal degrees, must be used together with lat and radius" minimum="0" minInclusive="-180.0" maxInclusive="180.0"/>
<params:Parameter name="radius" uiDisplay="Radius" value="{geo:radius}" title="Inventory with the search radius in meters, must be used together with lat and lon" minimum="0" minInclusive="10" maxInclusive="6000000"/>
<params:Parameter name="geometry" uiDisplay="Geometry" value="{geo:geometry}" title="Inventory with a spatial extent overlapping this geometry" minimum="0">
<atom:link rel="profile" href="http://www.opengis.net/wkt/LINESTRING" title="This service accepts WKT LineStrings"/>
<atom:link rel="profile" href="http://www.opengis.net/wkt/POINT" title="This service accepts WKT Points"/>
<atom:link rel="profile" href="http://www.opengis.net/wkt/POLYGON" title="This service accepts WKT Polygons"/>
</params:Parameter>
<params:Parameter name="placeName" uiDisplay="Place name" value="{geo:name}" title="Inventory with a spatial location described by this name" minimum="0"/>
<params:Parameter name="startTime" uiDisplay="Start time" value="{time:start}" title="Inventory with a temporal extent containing this start time" minimum="0"/>
<params:Parameter name="endTime" uiDisplay="End time" value="{time:end}" title="Inventory with a temporal extent containing this end time" minimum="0"/>
<params:Parameter name="cursor" uiDisplay="Start page" value="{os:startPage}" title="Start page for the search result" minimum="0"/>
<params:Parameter name="numberOfResults" uiDisplay="Number of results" value="{os:count}" title="Maximum number of records in the search result" minimum="0" maxInclusive="2000"/>
<params:Parameter name="offset" uiDisplay="Start index" value="{os:startIndex}" title="0-based offset used to skip the specified number of results in the search result set" minimum="0"/>
<params:Parameter name="uid" uiDisplay="Unique identifier" value="{geo:uid}" title="Inventory associated with this unique ID" minimum="0"/>
<params:Parameter name="hasGranules" uiDisplay="Has granules" value="{echo:hasGranules}" title="Inventory with granules">
<params:Option value="true" label="Yes"/>
<params:Option value="false" label="No"/>
</params:Parameter>
<params:Parameter name="isCwic" uiDisplay="CWIC collection" value="{echo:isCwic}" title="Inventory related to CWIC">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isGeoss" uiDisplay="GEOSS collection" value="{echo:isGeoss}" title="Inventory related to GEOSS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isCeos" uiDisplay="CEOS collection" value="{echo:isCeos}" title="Inventory related to CEOS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isEosdis" uiDisplay="EOSDIS collection" value="{echo:isEosdis}" title="Inventory related to EOSDIS">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="isFedeo" uiDisplay="FedEO collection" value="{echo:isFedeo}" title="Inventory related to FedEO">
<params:Option value="true" label="Yes"/>
</params:Parameter>
<params:Parameter name="provider" uiDisplay="Provider" value="{echo:provider}" title="Inventory associated with a provider" minimum="0"/>
<params:Parameter name="clientId" uiDisplay="Client identifier" value="{referrer:source}" title="Client identifier to be used for metrics" minimum="0"/>
</os:Url>
<os:Query role="example" searchTerms="Amazon River Basin Precipitation, 1972-1992" title="Sample search"/>
<os:Attribution>NASA CMR</os:Attribution>
<os:SyndicationRight>open</os:SyndicationRight>
<os:Tags>CMR NASA CWIC CEOS-OS-BP-V1.1/L3 ESIP OGC collection pageOffset=1 indexOffset=0</os:Tags>
</os:OpenSearchDescription>
Step 2
Search collections of interest through IDN OpenSearch with proper request parameters.
An example request can be formed as follows.
# find URL template for collection search
root = ElementTree.fromstring(response.text)
ns = {'os': 'http://a9.com/-/spec/opensearch/1.1/'}
collection_url_atom = root.find('os:Url[@rel="collection"][@type="application/atom+xml"]', ns)
collection_template = collection_url_atom.attrib['template']
collection_template
'https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword={os:searchTerms?}&instrument={echo:instrument?}&satellite={eo:platform?}&boundingBox={geo:box?}&lat={geo:lat?}&lon={geo:lon?}&radius={geo:radius?}&geometry={geo:geometry?}&placeName={geo:name?}&startTime={time:start?}&endTime={time:end?}&cursor={os:startPage?}&numberOfResults={os:count?}&offset={os:startIndex?}&uid={geo:uid?}&hasGranules={echo:hasGranules?}&isCwic={echo:isCwic?}&isGeoss={echo:isGeoss?}&isCeos={echo:isCeos?}&isEosdis={echo:isEosdis?}&isFedeo={echo:isFedeo?}&provider={echo:provider?}&clientId=ceosOpenSearchDoc'
request_url = get_api_request(collection_template, {'count': '10', 'searchTerms': 'Landsat_8'})
request_url
'https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword=Landsat_8&numberOfResults=10&clientId=ceosOpenSearchDoc'
response = requests.get( request_url )
xmlstr = minidom.parseString(response.text).toprettyxml(indent=' ', newl='')
md("```xml\n" + xmlstr + "\n```\n")
<?xml version="1.0" ?><feed xmlns:relevance="http://a9.com/-/opensearch/extensions/relevance/1.0/" xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:georss="http://www.georss.org/georss" xmlns="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:echo="https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#atom" xmlns:esipdiscovery="http://commons.esipfed.org/ns/discovery/1.2/" xmlns:gml="http://www.opengis.net/gml" xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/" xmlns:eo="http://a9.com/-/opensearch/extensions/eo/1.0/" esipdiscovery:version="1.2">
<updated>2024-12-06T16:28:24.940Z</updated>
<id>https://cmr.earthdata.nasa.gov/opensearch/collections.atom</id>
<author>
<name>CMR</name>
<email>echodev@echo.nasa.gov</email>
</author>
<title type="text">ECHO dataset metadata</title>
<subtitle type="text">Search parameters: keyword => Landsat_8</subtitle>
<link href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml" hreflang="en-US" type="application/opensearchdescription+xml" rel="search"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword=Landsat_8&numberOfResults=10&clientId=ceosOpenSearchDoc" hreflang="en-US" type="application/atom+xml" rel="self"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword=Landsat_8&numberOfResults=10&clientId=ceosOpenSearchDoc&cursor=1" hreflang="en-US" type="application/atom+xml" rel="last"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?keyword=Landsat_8&numberOfResults=10&clientId=ceosOpenSearchDoc&cursor=1" hreflang="en-US" type="application/atom+xml" rel="first"/>
<link href="https://wiki.earthdata.nasa.gov/display/echo/Open+Search+API+release+information" hreflang="en-US" type="text/html" rel="describedBy" title="Release Notes"/>
<os:Query xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/" role="request" os:searchTerms="Landsat_8"/>
<os:totalResults>1</os:totalResults>
<os:itemsPerPage>10</os:itemsPerPage>
<os:startIndex>1</os:startIndex>
<entry>
<id>https://cmr.earthdata.nasa.gov/opensearch/collections.atom?uid=C1235542031-USGS_LTA</id>
<author>
<name>CMR</name>
<email>echodev@echo.nasa.gov</email>
</author>
<consortium>CEOS</consortium>
<consortium>CWIC</consortium>
<title type="text">Landsat 8</title>
<summary type="text">The Operational Land Imager (OLI) and Thermal Infrared Sensor (TIRS) are onboard the Landsat 8 satellite, have acquired images of the Earth since February 2013. The sensors collect images of the Earth with a 16-day repeat cycle, referenced to the Worldwide Reference System-2. The approximate scene size is 170 km north-south by 183 km east-west (106 mi by 114 mi).
Landsat 8 image data files consist of 11 spectral bands with a spatial resolution of 30 meters for bands 1-7 and bands 9-11; 15-meters for the panchromatic band 8. Delivered Landsat 8 Level-1 data typically include both OLI and TIRS data files; however, there may be OLI-only and/or TIRS-only scenes in the USGS archive. A Quality Assurance (QA.tif) band is also included. This file provides bit information regarding conditions that may affect the accuracy and usability of a given pixel – clouds, water or snow, for example.</summary>
<updated/>
<link rel="enclosure" hreflang="en-US" href="http://glovis.usgs.gov"/>
<link rel="enclosure" hreflang="en-US" href="http://earthexplorer.usgs.gov"/>
<link rel="describedBy" hreflang="en-US" href="http://landsat.usgs.gov/landsat8.php"/>
<link length="0.0KB" rel="http://esipfed.org/ns/fedsearch/1.1/search#" hreflang="en-US" href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA" hreflang="en-US" type="application/opensearchdescription+xml" rel="search" title="Non-CMR OpenSearch Provider Granule Open Search Descriptor Document"/>
<link href="https://cmr.earthdata.nasa.gov/search/concepts/C1235542031-USGS_LTA.xml" hreflang="en-US" type="application/xml" rel="via" title="Product metadata"/>
<dc:identifier>C1235542031-USGS_LTA</dc:identifier>
<dc:date>2013-02-11T00:00:00.000Z/</dc:date>
<echo:datasetId>Landsat 8</echo:datasetId>
<echo:shortName>Landsat_8</echo:shortName>
<echo:versionId>Not provided</echo:versionId>
<echo:entryId>Landsat_8</echo:entryId>
<echo:dataCenter>USGS_LTA</echo:dataCenter>
<echo:archiveCenter>DOI/USGS/EROS</echo:archiveCenter>
<echo:organization>DOI/USGS/EROS</echo:organization>
<echo:processingLevelId>Not Provided</echo:processingLevelId>
<echo:coordinateSystem>CARTESIAN</echo:coordinateSystem>
<echo:orbitParameters/>
<georss:box>-82.71 -180 82.74 180</georss:box>
<echo:hasVariables>false</echo:hasVariables>
<echo:hasFormats>false</echo:hasFormats>
<echo:hasTransforms>false</echo:hasTransforms>
<echo:hasCombine>false</echo:hasCombine>
<echo:hasSpatialSubsetting>false</echo:hasSpatialSubsetting>
<echo:hasTemporalSubsetting>false</echo:hasTemporalSubsetting>
<echo:cloudHosted>false</echo:cloudHosted>
<relevance:score>0.97999995</relevance:score>
<echo:tag>
<echo:tagKey>org.ceos.wgiss.cwic.granules.prod</echo:tagKey>
<echo:data>" "</echo:data>
</echo:tag>
<echo:tag>
<echo:tagKey>org.ceos.wgiss.cwic.granules.provider</echo:tagKey>
<echo:data>"USGSLSI"</echo:data>
</echo:tag>
<echo:tag>
<echo:tagKey>org.geoss.geoss_data-core</echo:tagKey>
</echo:tag>
<echo:tag>
<echo:tagKey>gov.nasa.eosdis</echo:tagKey>
</echo:tag>
<echo:is_geoss>true</echo:is_geoss>
<echo:is_eosdis>true</echo:is_eosdis>
</entry>
</feed>
Step 3
From the IDN OpenSearch response obtain the OSDD endpoint for the collection by parsing the href attribute in the
<link rel="search" type="application/opensearchdescription+xml" />element. Note that the OSDD endpoint may refer to CWIC or FedEO.
request_url = get_api_request(collection_template, {'count': '10', 'geo:uid': 'C1235542031-USGS_LTA'})
request_url
'https://cmr.earthdata.nasa.gov/opensearch/collections.atom?&numberOfResults=10&uid=C1235542031-USGS_LTA&clientId=ceosOpenSearchDoc'
response = requests.get( request_url )
xmlstr = minidom.parseString(response.text).toprettyxml(indent=' ', newl='')
md("```xml\n" + xmlstr + "\n```\n")
<?xml version="1.0" ?><feed xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:georss="http://www.georss.org/georss" xmlns="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:echo="https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#atom" xmlns:esipdiscovery="http://commons.esipfed.org/ns/discovery/1.2/" xmlns:gml="http://www.opengis.net/gml" xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/" xmlns:eo="http://a9.com/-/opensearch/extensions/eo/1.0/" esipdiscovery:version="1.2">
<updated>2024-12-06T16:28:25.281Z</updated>
<id>https://cmr.earthdata.nasa.gov/opensearch/collections.atom</id>
<author>
<name>CMR</name>
<email>echodev@echo.nasa.gov</email>
</author>
<title type="text">ECHO dataset metadata</title>
<subtitle type="text">Search parameters: uid => C1235542031-USGS_LTA</subtitle>
<link href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml" hreflang="en-US" type="application/opensearchdescription+xml" rel="search"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?&numberOfResults=10&uid=C1235542031-USGS_LTA&clientId=ceosOpenSearchDoc" hreflang="en-US" type="application/atom+xml" rel="self"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?&numberOfResults=10&uid=C1235542031-USGS_LTA&clientId=ceosOpenSearchDoc&cursor=1" hreflang="en-US" type="application/atom+xml" rel="last"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/collections.atom?&numberOfResults=10&uid=C1235542031-USGS_LTA&clientId=ceosOpenSearchDoc&cursor=1" hreflang="en-US" type="application/atom+xml" rel="first"/>
<link href="https://wiki.earthdata.nasa.gov/display/echo/Open+Search+API+release+information" hreflang="en-US" type="text/html" rel="describedBy" title="Release Notes"/>
<os:Query xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/" role="request" geo:uid="C1235542031-USGS_LTA"/>
<os:totalResults>1</os:totalResults>
<os:itemsPerPage>10</os:itemsPerPage>
<os:startIndex>1</os:startIndex>
<entry>
<id>https://cmr.earthdata.nasa.gov/opensearch/collections.atom?uid=C1235542031-USGS_LTA</id>
<author>
<name>CMR</name>
<email>echodev@echo.nasa.gov</email>
</author>
<consortium>CEOS</consortium>
<consortium>CWIC</consortium>
<title type="text">Landsat 8</title>
<summary type="text">The Operational Land Imager (OLI) and Thermal Infrared Sensor (TIRS) are onboard the Landsat 8 satellite, have acquired images of the Earth since February 2013. The sensors collect images of the Earth with a 16-day repeat cycle, referenced to the Worldwide Reference System-2. The approximate scene size is 170 km north-south by 183 km east-west (106 mi by 114 mi).
Landsat 8 image data files consist of 11 spectral bands with a spatial resolution of 30 meters for bands 1-7 and bands 9-11; 15-meters for the panchromatic band 8. Delivered Landsat 8 Level-1 data typically include both OLI and TIRS data files; however, there may be OLI-only and/or TIRS-only scenes in the USGS archive. A Quality Assurance (QA.tif) band is also included. This file provides bit information regarding conditions that may affect the accuracy and usability of a given pixel – clouds, water or snow, for example.</summary>
<updated/>
<link rel="enclosure" hreflang="en-US" href="http://glovis.usgs.gov"/>
<link rel="enclosure" hreflang="en-US" href="http://earthexplorer.usgs.gov"/>
<link rel="describedBy" hreflang="en-US" href="http://landsat.usgs.gov/landsat8.php"/>
<link length="0.0KB" rel="http://esipfed.org/ns/fedsearch/1.1/search#" hreflang="en-US" href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA"/>
<link href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA" hreflang="en-US" type="application/opensearchdescription+xml" rel="search" title="Non-CMR OpenSearch Provider Granule Open Search Descriptor Document"/>
<link href="https://cmr.earthdata.nasa.gov/search/concepts/C1235542031-USGS_LTA.xml" hreflang="en-US" type="application/xml" rel="via" title="Product metadata"/>
<dc:identifier>C1235542031-USGS_LTA</dc:identifier>
<dc:date>2013-02-11T00:00:00.000Z/</dc:date>
<echo:datasetId>Landsat 8</echo:datasetId>
<echo:shortName>Landsat_8</echo:shortName>
<echo:versionId>Not provided</echo:versionId>
<echo:entryId>Landsat_8</echo:entryId>
<echo:dataCenter>USGS_LTA</echo:dataCenter>
<echo:archiveCenter>DOI/USGS/EROS</echo:archiveCenter>
<echo:organization>DOI/USGS/EROS</echo:organization>
<echo:processingLevelId>Not Provided</echo:processingLevelId>
<echo:coordinateSystem>CARTESIAN</echo:coordinateSystem>
<echo:orbitParameters/>
<georss:box>-82.71 -180 82.74 180</georss:box>
<echo:hasVariables>false</echo:hasVariables>
<echo:hasFormats>false</echo:hasFormats>
<echo:hasTransforms>false</echo:hasTransforms>
<echo:hasCombine>false</echo:hasCombine>
<echo:hasSpatialSubsetting>false</echo:hasSpatialSubsetting>
<echo:hasTemporalSubsetting>false</echo:hasTemporalSubsetting>
<echo:cloudHosted>false</echo:cloudHosted>
<echo:tag>
<echo:tagKey>org.ceos.wgiss.cwic.granules.prod</echo:tagKey>
<echo:data>" "</echo:data>
</echo:tag>
<echo:tag>
<echo:tagKey>org.ceos.wgiss.cwic.granules.provider</echo:tagKey>
<echo:data>"USGSLSI"</echo:data>
</echo:tag>
<echo:tag>
<echo:tagKey>org.geoss.geoss_data-core</echo:tagKey>
</echo:tag>
<echo:tag>
<echo:tagKey>gov.nasa.eosdis</echo:tagKey>
</echo:tag>
<echo:is_geoss>true</echo:is_geoss>
<echo:is_eosdis>true</echo:is_eosdis>
</entry>
</feed>
Obtain the OSDD endpoint for the granule search for this collection by parsing the href attribute in <link rel="search" type="application/opensearchdescription+xml" >
root = ElementTree.fromstring(response.text)
# Extract <link> element with the OSDD for the granule search with Atom response
el = root.find('{http://www.w3.org/2005/Atom}entry/{http://www.w3.org/2005/Atom}link[@rel="search"][@type="application/opensearchdescription+xml"]')
xmltxt = ElementTree.tostring(el, encoding='unicode', method='xml')
md("```xml\n" + xmltxt + "\n```\n")
<ns0:link xmlns:ns0="http://www.w3.org/2005/Atom" href="https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA" hreflang="en-US" type="application/opensearchdescription+xml" rel="search" title="Non-CMR OpenSearch Provider Granule Open Search Descriptor Document" />
Extract the URL of the OSDD endpoint from the <link>.
url_osdd = el.attrib['href']
el.attrib['href']
'https://cmr.earthdata.nasa.gov/opensearch/granules/descriptor_document.xml?collectionConceptId=C1235542031-USGS_LTA'
Step 4
From the collection OSDD found in the IDN OpenSearch response, formulate a valid granule search request. How to do this is explained in sections (“CWIC”) and “FedEO”.
In principle, CEOS OpenSearch clients compliant with CEOS OpenSearch Best Practices should not care whether the second step (i.e. Granule search) redirects to CWIC or FedEO as both endpoints provide the same interface which clients should discover by obtaining the OSDD. Search parameters in the URL template which are specific to one of both endpoints (i.e. not defined in the CEOS Best Practice for OpenSearch or belonging to a foreign namespace) can be left empty when preparing the granule search request.
Available Collection Search Criteria#
CEOS OpenSearch is used as the IDN’s collections search implementation based on the OpenSearch 1.1 (Draft 5) specification and is compliant with the CEOS OpenSearch Best Practices. The IDN OpenSearch API allows clients to formulate OpenSearch compliant queries against the IDN collections and specify the desired search results format as OpenSearch compliant Atom or HTML. The IDN OpenSearch API implements the following search fields for users’ queries:
Table of collection search criteria
| HTTP Query Parameter | Description | Value &
Cardinality (M) = mandatory (O) = optional | OpenSearch Parameter |
|---|---|---|---|
| boundingBox | Inventory with a spatial extent overlapping this bounding box | (O) | geo:box |
| keyword | Inventory with terms expressed by these search terms | (O) | os:searchTerms |
| instrument | Inventory associated with a satellite instrument expressed by this short name | (O) | echo:instrument |
| satellite | Inventory associated with a Satellite/platform expressed by this short name | (O) | eo:platform |
| geometry | Inventory with a spatial extent overlapping this geometry | (O) | geo:geometry |
| placeName | Inventory with a spatial location described by this name | (O) | geo:name |
| startTime | Inventory with a temporal extent containing this start time | (O) | time:start |
| endTime | Inventory with a temporal extent containing this end time | (O) | time:end |
| cursor | Start page for the search result | (O) | os:startPage |
| numberOfResults | Maximum number of records in the search result | (O) | os:count |
| offset | 0 - based offset used to skip the specified number of results in the search result set | (O) | os:startIndex |
| uid | Inventory associated with this unique ID | (O) | geo:uid |
| hasGranules | Inventory with granules | (O) | echo:hasGranules |
| isCwic | Inventory related to CWIC | (O) | echo:isCwic |
| isGeoss | Inventory related to GEOSS | (O) | echo:isGeoss |
| isCeos | Inventory related to CEOS | (O) | |
| isEosdis | Inventory related to EOSDIS | (O) | echo:isEosdis |
| provider | Inventory associated with a provider | (O) | echo:provider |
| clientId | Client identifier to be used for metrics | (O) | cswOpenSearchDoc |
Also, client developers are able to query with specific tags: isCeos, isCwic, isGeoss, and isFedEO. Tagging allows arbitrary sets of collections to be grouped under a single namespace value. The sets of collections can be recalled later when searching by tag fields.
IDN query examples:
GET the first 10 IDN collections with results in the Atom format: https://cmr.earthdata.nasa.gov/opensearch/collections.atom?numberOfResults=10&clientId=cswOpenSearchDoc
GET the first 10 IDN collections containing the GCMD instrument keyword MODIS with results in the Atom output format: https://cmr.earthdata.nasa.gov/opensearch/collections.atom?instrument=MODIS&numberOfResults=10&clientId=cswOpenSearchDoc
GET the first 10 CWIC IDN collections containing the GCMD instrument keyword MODIS with results in the HTML format: https://cmr.earthdata.nasa.gov/opensearch/collections?instrument=MODIS&isCwic=true&numberOfResults=10&clientId=cswOpenSearchDoc