Developer Cloud Sandboxes solution

h1. 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:

h3. Step 1: Get URL Template for Series Query 

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

Response (formatted and shortened):

<pre><code class="xml">

<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>

</code></pre>

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 @&@).

h3. 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):

<pre><code class="xml">

<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.

	<br/>

	</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">

			<b> Search Feed  </b>

			<ul>

			<li> Title: ASAR Image Mode source packets Level 0 (ASA_IM__0P) </li>

			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">

			<b> Search Feed  </b>

			<ul>

			<li> Title: ENVISAT ASAR Image Mode Single Look Complex Image (ASA_IMS_1P) </li>

			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">

			<b> Search Feed  </b>

			<ul>

			<li> Title: ASAR Wide Swath Level 0 product (ASA_WS__0P) </li>

			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>

</code></pre>

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).

h3. 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): 

<pre><code class="xml">

<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>

</code></pre>

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 |/8\3. 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":http://en.wikipedia.org/wiki/Well-known_text string (e.g. a @POLYGON((...))@ | _empty_ |

|/5. @{eop:processingCenter?}@ |/5=. no |/5. Processing centre | @I-PAC@ |/5. _empty_ |

| @PDAS-F@ |

| @PDAS-M@ |

| @PDHS-E@ |

| @PDHS-K@ |

| @{eop:acquisitionStation?}@ |=. no | Acquisition station | | _empty_ |

|/2. @{eop:orbitDirection?}@ |/2=. no |/2. Orbit direction | @ASCENDING@ |/2. _empty_ |

| @DESCENDING@ |

| @{eop:orbitNumber?}@ |=. no | Orbit number | | _empty_ |

| @{eop:wrsLatitudeGrid?}@ |=. no | Frame??? | | _empty_ |

| @{eop:wrsLongitudeGrid?}@ |=. no | Track??? | | _empty_ |

|/2. @{dct:dateSubmitted?}@ |/2=. no |/2. Date of insertion of record into the catalogue | Date in interval format @[YYYY-MM-DD,YYYY-MM-DD]@ |/2. _empty_ |

| Date/time in interval format @[YYYY-MM-DDThh:mm:ssZ,YYYY-MM-DD:hh:mm:ssZ]@ |

h3. 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="@