Metadata Request

A metadata request consists of a HTTP request that the user will have to build using several parameters. Once this query is sent, the HSA backend will return the metadata that matches the given criteria in the requested format.

The default return type for all metadata requests is the VOTable format (What is a VOTable?)

All metadata requests have the following HTTP prefix:

http://archives.esac.esa.int/hsa/aio/jsp/metadata.jsp?

After the HTTP prefix, the following parameters are used to build the request:

Table 2: Metadata request parameters
Parameter name(s) Description Mandatory? Possible values
SELECTED_FIELDS Single Entity ("Entity") or list of Attributes requested ("Entity"."Attribute" list separated by commas). NOT Any HSA Entity or any combination of HSA attributes. (See List of HSA entities and attributes)
RETURN_TYPE Output format of the response. The default response formal is VOTable. Other formats are JSON or CSV ( in next releases ) NOT VOTABLE (default), CSV,JSON
RESOURCE_CLASS Single Entity which defines the granularity level of the metadata query response. YES Any HSA Entity. (See List of HSA entities and attributes)
PAGE_SIZE & PAGE Number of records per page & page number NOT, but highly recommended Any integer value
QUERY Complex restrictions of the request NOT Any Jython valid query expression (see below)
ORDER_BY Criteria to sort metadata results NOT Any HSA attribute. (See List of HSA entities and attributes)
LAST_TRAC_VERSION 'TRUE' means that the results must contain only latest versions ( grouped by HCSS_TRACK_ID and HCSS_TRACK_VERSION ) NOT TRUE
LIMIT If it is specified and the number of results are greater that the specified value, a VOTable containing an error is returned. NOT Integer value less than 25000 (HSA Hard Limit).
SHOW_PROPRIETARY 'TRUE' means that each VOTable record will contain a field that specifies proprietary rights access. NOT TRUE
EXPIRED 'TRUE' means that the results must contain only public observations whereas 'FALSE' means that results must contain only proprietary observations. NOT [ TRUE | FALSE ]

In addition to these parameter names, simple attribute restrictions can be added as "Entity"."Attribute"="value" or "Alias"="value" to the metadata request (for example product.hcss_urn= or urn=urn:hsa:herschel.ia.obs.auxiliary.horizons.HorizonsProduct:2364 urn=urn:hsa:herschel.ia.obs.auxiliary.horizons.HorizonsProduct:2364). Click here in order to get the complete list of alias available.

Baby stars in Orion Nebula
(ESA/PACS/NASA/JPL-Caltech/IRAM )




Please note that:

Let's see the use of all the above through some examples:

When requesting in VOTABLE format, e.g: (SELECTED_FIELDS=OBSERVATION), additional information will be provided for each result:

Herschel’s image of Fomalhaut
(ESA/Herschel/PACS/
Bram Acke, KU Leuven, Belgium)

Use of QUERY parameter


Keyword=value paradigm creates simple queries using the AND argument as logical operator. If a user wants to create a complex query, by using >,<,>=,<=,like (including SQL wildcards), and, or... operators he/she will have to use the QUERY parameter. The rest of the keyword parameters will be seen as other AND conditions.



The value of this query field should be URL encoded (See URL Encoding Reference)

Inside the value of the QUERY parameter, we allow any Jython valid query expression using SSA attributes.

Jython query operations are slightly different to the SQL ones, as stated in this table:

Table 3: QUERY parameter operators
QUERY operators Type Precedence Symbol
Parenthesis Grouping 1 ()
Equals Relational 2 ==
Not equals Relational 2 !=
Greater than Relational 2 >
Lower than Relational 2 <
Greater or equals than Relational 2 >=
Lower or equals than Relational 2 <=
Like:'%' => multiple characters '_' => one character Relational 2 LIKE
And Logical 3 AND
Or Logical 4 OR

Let's see the use of all the above through some examples: