Project

General

Profile

Actions
History

OpenSearch in Virtual Archive 4

This is a more detailed explaining the OpenSearch interface provided by the Virtual Archive 4 Catalogue Access Service.

Note that the procedure described here does not need to be followed entirely. In many scenarios the series to be queried is already known and therefore it is often possible to skip the first two steps. The series description URL for step 3 can be easily guessed as it follows always the schema: http://eo-virtual-archive4.esa.int/search/<series-name>/description

Following the steps described in the previous section, with curl you have to do the following:

Step 1: Get URL Template for Series Query

Request (using curl): curl "http://eo-virtual-archive4.esa.int/search/description"

Response (formatted and shortened):

<OpenSearchDescription ...>
  <ShortName>Supersite</ShortName>
  <LongName>Discover the different search feeds available at this Supersite</LongName>
  <Description>The Supersites have data for the study of natural hazards in geologically active regions, ...</Description>
  <Tags> Supersite, ESA, NASA, GEO, NSF, JAXA, UNAVCO, SAR, GPS, Digital Earth Communities, Catalogue</Tags>
  <Contact>info@terradue.com</Contact>
  <Image height="38" width="120" type="image/png">http://www.terradue.com/images/terradue.png</Image>
  <Image height="16" width="16" type="image/vnd.microsoft.icon">http://www.terradue.com/images/terradue.ico</Image>
  <Query role="example" geo:box="-25,30,45,70"/>
  <Developer>Terradue GeoSpatial Development Team</Developer>
  <Attribution>Terradue Srl. Copyright 2008-11, All Rights Reserved</Attribution>
  <SyndicationRight>open</SyndicationRight>
  <AdultContent>false</AdultContent>
  <Language>en-us</Language>
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
  <Url type="application/rdf+xml" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/rdf/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
  <Url type="text/plain" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/wkt/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
  <Url type="text/plain" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/txt/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
  <Url type="text/tab-separated-values" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/eoli/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
  <Url type="text/html" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/html/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
  <Url type="application/atom+xml" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/atom/?count={count?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;q={searchTerms?}&amp;uid={geo:uid?}&amp;bbox={geo:box?}&amp;start={time:start?}&amp;stop={time:end?}"/>
</OpenSearchDescription>

The <Url> elements contain the information necessary for the querying step 2, one for each supported output format.

The terms between curly brackets in the template URLs represent the information that can be provided by the client for refining the query:

Search parameter Required? Description Default value
{count?} no Number of records to be returned 20
{startPage?} no Number of result page to be returned (starting with 0, each page contains count records; applies only if there are more than count results) 0
{startIndex?} no Index of first result record to be returned (starting with 0) 0
{searchTerms?} no Textual search string containing key words empty
{geo:uid?} no Identifier of record to be returned empty
{geo:box?} no Spatial coverage: rectangular area to be covered in the format minlon,minlat,maxlon,maxlat. -180,-90,180,90
{time:start?} no Temporal coverage: Start date of the period to be covered in the format YYYY-MM-DD or @YYYY-MM-DDThh:mm:ssZ minimum possible date value
{time:end?} no Temporal coverage: End date of the period to be covered in the format YYYY-MM-DD or @YYYY-MM-DDThh:mm:ssZ maximum possible date value

Note that the curly brackets with the contained terms must be removed when performing a query. The connected URL query string parameter must not be removed if the parameter is not used. For example if the uid={geo:uid?} is not used, the query URL must still contain uid= (at the end of the URL or followed by an &).

Step 2: Query the Series

Example request (using curl, in the following ATOM output is used): curl "http://eo-virtual-archive4.esa.int/search/atom/?count=&startPage=&startIndex=&q=ENVISAT&uid=&bbox=&start=2004-10-01&stop=2004-12-31"

This request queries series related to ENVISAT and containing data sets within that period for which there is data of the last quarter of 2004.

Response (shortened and formatted):

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/" xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/" xml:lang="en">
  <title>Discovery feed for Search Services</title>
  <subtitle type="html">
               Found 3 results.

    &lt;br/&gt;
    </subtitle>
  <generator uri="http://www.terradue.com" version="1.4.0">Terradue CAS</generator>
  <updated>2013-05-07T16:42:35ZZ</updated>
  <id>http://eo-virtual-archive4.esa.int/search/atom/</id>
  <link rel="self" type="application/atom+xml" href="http://eo-virtual-archive4.esa.int/search/atom//?startIndex=0&amp;q=ENVISAT&amp;start=2004-12-09&amp;stop=2004-12-31">
  </link>
  <link rel="first" type="application/atom+xml" href="http://eo-virtual-archive4.esa.int/search/atom//?startIndex=0&amp;q=ENVISAT&amp;start=2004-12-09&amp;stop=2004-12-31">
  </link>
  <link rel="last" type="application/atom+xml" href="http://eo-virtual-archive4.esa.int/search/atom//?startIndex=0&amp;q=ENVISAT&amp;start=2004-12-09&amp;stop=2004-12-31">
  </link>
  <link rel="search" type="application/opensearchdescription+xml" href="http://eo-virtual-archive4.esa.int/search/description">
  </link>
  <os:totalResults>3</os:totalResults>
  <os:startIndex>0</os:startIndex>
  <os:itemsPerPage>20</os:itemsPerPage>
  <os:Query role="request" searchTerms="ENVISAT" time:start="2004-12-09" time:end="2004-12-31">
  </os:Query>
  <entry>
    <id>http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/atom</id>
    <title>ASAR Image Mode source packets Level 0 (ASA_IM__0P)</title>
    <published>2011-01-21T11:05:29.511Z</published>
    <updated>2013-04-18T13:44:56.872Z</updated>
    <rights>
    </rights>
    <dc:date>2002-10-18T08:07:37.387Z/2012-04-06T08:24:56.723Z</dc:date>
    <georss:where>
      <gml:Polygon>
        <gml:exterior>
          <gml:LinearRing>
            <gml:posList srsDimension="2">...</gml:posList>
          </gml:LinearRing>
        </gml:exterior>
      </gml:Polygon>
    </georss:where>
    <link rel="alternate" type="application/atom+xml" title="ATOM feed" href="http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/atom">
    </link>
    <link rel="search" type="application/opensearchdescription+xml" href="http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/description/" title="Search the ASA_IM__0P">
    </link>
    <link rel="via" type="application/rdf+xml" title="RDF metadata entry" href="http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/rdf?count=0">
    </link>
    <content type="html">
            &lt;b&gt; Search Feed  &lt;/b&gt;
            &lt;ul&gt;
            &lt;li&gt; Title: ASAR Image Mode source packets Level 0 (ASA_IM__0P) &lt;/li&gt;
            The ASAR Image Mode source packets Level 0 data product offers Level 0 data for possible images processing on an other processing site. It includes some mandatory information for SAR processing ...
    </content>
  </entry>
  <entry>
    <id>http://eo-virtual-archive4.esa.int/search/ASA_IMS_1P/atom</id>
    <title>ENVISAT ASAR Image Mode Single Look Complex Image (ASA_IMS_1P)</title>
    <published>2011-01-21T11:05:29.511Z</published>
    <updated>2013-04-18T13:44:56.872Z</updated>
    <rights>
    </rights>
    <dc:date>2002-10-21T08:13:28.350Z/2022-02-26T08:26:09.501Z</dc:date>
    <georss:where>
      <gml:Polygon>
        <gml:exterior>
          <gml:LinearRing>
            <gml:posList srsDimension="2">...</gml:posList>
          </gml:LinearRing>
        </gml:exterior>
      </gml:Polygon>
    </georss:where>
    <link rel="alternate" type="application/atom+xml" title="ATOM feed" href="http://eo-virtual-archive4.esa.int/search/ASA_IMS_1P/atom">
    </link>
    <link rel="search" type="application/opensearchdescription+xml" href="http://eo-virtual-archive4.esa.int/search/ASA_IMS_1P/description/" title="Search the ASA_IMS_1P">
    </link>
    <link rel="via" type="application/rdf+xml" title="RDF metadata entry" href="http://eo-virtual-archive4.esa.int/search/ASA_IMS_1P/rdf?count=0">
    </link>
    <content type="html">
            &lt;b&gt; Search Feed  &lt;/b&gt;
            &lt;ul&gt;
            &lt;li&gt; Title: ENVISAT ASAR Image Mode Single Look Complex Image (ASA_IMS_1P) &lt;/li&gt;
            The ASAR Image Mode Single Look Complex Image represents a single-look, complex, slant-range, digital image generated from Level 0 ASAR data collected when the instrument is in image mode ...
    </content>
  </entry>
  <entry>
    <id>http://eo-virtual-archive4.esa.int/search/ASA_WS__0P/atom</id>
    <title>ASAR Wide Swath Level 0 product (ASA_WS__0P)</title>
    <published>2011-06-10T11:05:29.511Z</published>
    <updated>2013-04-18T08:25:35.099Z</updated>
    <dc:date>2004-02-19T03:03:23.736Z/2010-09-12T15:57:36.072Z</dc:date>
    <georss:where>
      <gml:Polygon>
        <gml:exterior>
          <gml:LinearRing>
            <gml:posList srsDimension="2">...</gml:posList>
          </gml:LinearRing>
        </gml:exterior>
      </gml:Polygon>
    </georss:where>
    <link rel="alternate" type="application/atom+xml" title="ATOM feed" href="http://eo-virtual-archive4.esa.int/search/ASA_WS__0P/atom">
    </link>
    <link rel="search" type="application/opensearchdescription+xml" href="http://eo-virtual-archive4.esa.int/search/ASA_WS__0P/description/" title="Search the ASA_WS__0P">
    </link>
    <link rel="via" type="application/rdf+xml" title="RDF metadata entry" href="http://eo-virtual-archive4.esa.int/search/ASA_WS__0P/rdf?count=0">
    </link>
    <content type="html">
            &lt;b&gt; Search Feed  &lt;/b&gt;
            &lt;ul&gt;
            &lt;li&gt; Title: ASAR Wide Swath Level 0 product (ASA_WS__0P) &lt;/li&gt;
            The WS Mode Level 0 product consists of time-ordered AISPs collected while the instrument is in WS Mode. The echo samples in the AISPs have been compressed to 4 bits/sample using FBAQ ...
    </content>
  </entry>
</feed>

When writing this document, there were 3 matching series out of 15.

In order to proceed with step 3, a series must be chosen the OpenSearch description URL for finding data sets must be used. This URL is taken from the <link rel="search"> element of the corresponding <entry> (this applies to ATOM; in other output formats the description URL is found in different elements).

Step 3: Get URL Template for Data Set Query

Example request (using curl and the series description URL): curl "http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/description/"

Response (shortened and formatted): 

<OpenSearchDescription>
  ...
  <Url type="application/atom+xml" indexOffset="0" pageOffset="0" template="http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/atom/?count={count?}&amp;name={geo:name?}&amp;startPage={startPage?}&amp;startIndex={startIndex?}&amp;sort={sru:sortKeys?}&amp;q={searchTerms?}&amp;start={time:start?}&amp;stop={time:end?}&amp;bbox={geo:box?}&amp;geometry={geo:geometry?}&amp;uid={geo:uid?}&amp;processingCenter={eop:processingCenter?}&amp;acquisitionStation={eop:acquisitionStation?}&amp;orbitDirection={eop:orbitDirection?}&amp;orbitNumber={eop:orbitNumber?}&amp;frame={eop:wrsLatitudeGrid?}&amp;track={eop:wrsLongitudeGrid?}&amp;submitted={dct:dateSubmitted?}" />
</OpenSearchDescription>

The result is similar to the one of step one, but applies to data sets of one series and shows additional search parameters (e.g. for the orbit direction), some of which specific to just that series.

Search parameter Required? Description Possible values Default value
{count?} no see above
{startPage?} no
{startIndex?} no
{searchTerms?} no
{geo:uid?} no
{geo:box?} no
{time:start?} no
{time:end?} no
{geo:name?} no ???
{sru:sortKeys?} no Result sorting Sorting expression, empty
{geo:geometry?} no Spatial coverage a WKT string (e.g. a POLYGON((...)) empty
{eop:processingCenter?} no Processing centre I-PAC empty
PDAS-F
PDAS-M
PDHS-E
PDHS-K
{eop:acquisitionStation?} no Acquisition station empty
{eop:orbitDirection?} no Orbit direction ASCENDING empty
DESCENDING
{eop:orbitNumber?} no Orbit number empty
{eop:wrsLatitudeGrid?} no Frame??? empty
{eop:wrsLongitudeGrid?} no Track??? empty
{dct:dateSubmitted?} no Date of insertion of record into the catalogue Date in interval format [YYYY-MM-DD,YYYY-MM-DD] empty
Date/time in interval format [YYYY-MM-DDThh:mm:ssZ,YYYY-MM-DD:hh:mm:ssZ]

Step 4: Query the Data Sets

Example request (using curl, in the following ATOM output is used): curl "http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/atom/?count=50&name=&startPage=&startIndex=&sort=&q=&start=2004-01-01&stop=2004-12-31&bbox=5,35,15,45&geometry=&uid=&processingCenter=&acquisitionStation=&orbitDirection=ASCENDING&orbitNumber=&frame=&track=&submitted="

The request queries for ASA_IM__0P data sets over Italy in the year 2004. It results in 75 matching records, of which 50 are shown (as specified in the query string parameter count=50).

In order to have an XML document that is parsable more easily, it is recommendable to use the RDF output format. For the example above, the curl command would be:
curl "http://eo-virtual-archive4.esa.int/search/ASA_IM__0P/rdf/?count=50&name=&startPage=&startIndex=&sort=&q=&start=2004-01-01&stop=2004-12-31&bbox=5,35,15,45&geometry=&uid=&processingCenter=&acquisitionStation=&orbitDirection=ASCENDING&orbitNumber=&frame=&track=&submitted="

Updated by Herve Caumont over 11 years ago ยท 1 revisions