TAP DEtails

The entry point is a TAP (Table Access Protocol) server.

You may use HTTP protocol to execute TAP requests at http://soar.esac.esa.int/soar-sl-tap/tap.

TAP may be used to access Metadata or Data

• Metadata is information about the data files
• Data is the products themselves

TAP provides two operation modes: Synchronous and Asynchronous

• Synchronous: the response to the request will be generated as soon as the request is received by the server.
• Asynchronous: the server will start a job that will execute the request. The first response to the request is the required information (a link) to obtain the job status. Once the job is finished, the results can be retrieved. Recommended for slower network connections where the request may time out.

Our TAP server provides two access mode: public and authenticated

• Public: this is the standard TAP access to publicly available data. A user can perform synchronous data requests or both synchronous or asynchronous metadata queries without logging in.
• Authenticated: allows access to restricted data, and enables asynchronous data requests to send an email notification when the products are ready for download.

TYPES OF REQUESTS

Our TAP server can be used either for metadata requests as well as for data requests:

INTERFACE SPECIFICATION

See the following specifications:

• TAP (Table Access Protocol)
• UWS (Universal Worker Service)
• ADQL (Astronomical Data Query Language)

TAP RESOURCES

http://soar.esac.esa.int/soar-sl-tap/tap/

Authentication

Logging in (register here for a userid) allows access to restricted data (contact us) but also enables asynchronous requests to send an email when the request has been completed and is ready for download, since an email address is required by the registration process.

TAP+ LOGIN

To access the login page:

http://soar.esac.esa.int/soar-sl-tap/login

The response header will contain the session identifier.

Example of login with curl:

curl -k -c cookies.txt -X POST -d username=USERNAME -d password=PASSWORD -L http://soar.esac.esa.int/soar-sl-tap/login

NOTE: curl allows to store a cookies file (cookies.txt above) to be used for the subsequent asynchronous requests

TAP+ LOGOUT

To log out:

http://soar.esac.esa.int/soar-sl-tap/logout

Logout using curl and a cookie file:

curl -k -b cookies.txt -X POST -d -L http://soar.esac.esa.int/soar-sl-tap/logout

SYNCHRONOUS/ASYNCHRONOUS QUERIES

SYNCHRONOUS QUERIES

Example of direct request:

http://soar.esac.esa.int/soar-sl-tap/tap/sync?REQUEST=doQuery&LANG=ADQL&FORMAT=votable_plain&QUERY=SELECT+*+FROM+v_ll_data_item+WHERE+((instrument='MAG')+OR+(instrument='EPD'))+AND+begin_time>'2020-08-29+00:00:28'

ASYNCHRONOUS QUERIES

In all asynchronous requests the response header will contain the location of the job, which can be used to check its status and finally to get the URL for retrieving the data.
It is possible to launch asynchronous queries with or without being authenticated. If the user is authenticated, an email will be sent to the LDAP user email address with the information to retrieve the data. In order to know how to login, please review the previous section in this page ('Introduction -> TAP+ Login').
These are the steps to follow to launch an asynchronous query and retrieve the results:

Step 1: Launch asynchronous request.

Example of direct request.

NOTE: It will redirect to the URL of the status of the job running at the server side.

http://soar.esac.esa.int/soar-sl-tap/tap/async?PHASE=run&REQUEST=doQuery&LANG=ADQL&FORMAT=votable_plain&QUERY=SELECT+*+FROM+v_ll_data_item+WHERE+((instrument='MAG')+OR+(instrument='EPD'))+AND+begin_time>'2020-08-29+00:00:28'

Example of Curl request without authentication:

NOTE: The response will contain the URL of the job running at the server side (see Location header).

curl -i -X POST --data "PHASE=run&REQUEST=doQuery&LANG=ADQL&FORMAT=votable_plain&QUERY=SELECT+*+FROM+v_ll_data_item+WHERE+((instrument='MAG')+OR+(instrument='EPD'))+AND+begin_time>'2020-08-29+00:00:28'" "http://soar.esac.esa.int/soar-sl-tap/tap/async?"

Example of Curl request with authentication:

NOTE: The cookies.txt file must have been generated through the login request (see Login section above).

curl -k -b cookies.txt -i -X POST --data "PHASE=run&REQUEST=doQuery&LANG=ADQL&FORMAT=votable_plain&QUERY=SELECT+*+FROM+v_ll_data_item+WHERE+((instrument='MAG')+OR+(instrument='EPD'))+AND+begin_time>'2020-08-29+00:00:28'" "http://soar.esac.esa.int/soar-sl-tap/tap/async?"

Step 2: Check the status of the job.

Example of the response of the curl request where the Location can be found:

HTTP/1.1 303 See Other
Date: Mon, 10 Sep 2018 09:38:13 GMT
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Location: http://soar.esac.esa.int/soar-sl-tap/tap/async/1536572293438OPE
Content-Type: text/plain;charset=ISO-8859-1
Connection: close
Transfer-Encoding: chunked

Accessing the location URL (http://soar.esac.esa.int/soar-sl-tap/tap/async/1536572293438OPE in this example) results in the Job response displayed below where:

• the phase indicates the job status (EXECUTING, COMPLETED...):
• the result provides the URL where the data can be retrieved

<?xml version="1.0" encoding="UTF-8"?>
<uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 http://www.ivoa.net/xml/UWS/v1.0" >
<uws:jobId><![CDATA[1536572293438DEV]]></uws:jobId>
<uws:runId xsi:nil="true"/>
<uws:ownerId><![CDATA[anonymous]]></uws:ownerId>
<uws:phase>COMPLETED</uws:phase>
<uws:quote>-1</uws:quote>
<uws:startTime>2018-08-01T10:38:57.097+0200</uws:startTime>
<uws:endTime>2018-08-01T10:38:57.161+0200</uws:endTime>
<uws:executionDuration>1800</uws:executionDuration>
<uws:destruction>2018-08-04T10:38:57.081+0200</uws:destruction>
<uws:creationTime>2018-08-01T10:38:57.081+0200</uws:creationTime>
<uws:locationId>anonymous/2018/08/01/1533112737081DEV</uws:locationId>
<uws:name xsi:nil="true"/>
<uws:parameters>
<uws:parameter id="format" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[json]]></uws:parameter>
<uws:parameter id="lang" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[ADQL]]></uws:parameter>
<uws:parameter id="lib_sl_version" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[2.2.1]]></uws:parameter>
<uws:parameter id="lib_tap_version" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[2.2.1]]></uws:parameter>
<uws:parameter id="lib_uws_version" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[2.2.1]]></uws:parameter>
<uws:parameter id="page" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[1]]></uws:parameter>
<uws:parameter id="page_size" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[1000]]></uws:parameter>
<uws:parameter id="phase" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[run]]></uws:parameter>
<uws:parameter id="query" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[SELECT * FROM v_ll_data_item WHERE ((instrument='RPW') OR (instrument='SWA')) AND begin_time>'2020-08-29 00:00:28']]></uws:parameter>
<uws:parameter id="request" parameter_type="COMMON" parameter_data_type="String" ><![CDATA[doQuery]]></uws:parameter>
</uws:parameters>
<uws:results>
<uws:result id="result" xlink:type="simple" xlink:href="http://soar.esac.esa.int/soar-sl-tap/tap/async/1536572293438OPE/results/result" mime="application/json" size="37488" rows="1000" />
</uws:results>
<uws:errorSummary xsi:nil="true"/>
</uws:job>

Step 3: Obtain the results of the job.

To obtain the results of the job (once the job is finished), access the result URL.

http://soar.esac.esa.int/soar-sl-tap/tap/async/1536572293438OPE/results/result

Note that there is the possibility to use the optional parameters "JOBNAME" to assign a name to the job and "JOBDESCRIPTION" to add a description:

http://soar.esac.esa.int/soar-sl-tap/tap/async?PHASE=run&JOBNAME=optionalJobName&JOBDESCRIPTION=optionalDescription&REQUEST=doQuery&LANG=ADQL&FORMAT=votable_plain&QUERY=SELECT+TOP+5+*+FROM+v_auxiliary_file

TAP+ TABLES CAPABILITIES

In addition to the standard 'tables' TAP capability, the following parameters can be used too:

These parameters are handled based on the following priorities:

TAP+ EVENTS CAPABILITIES

Tables creation/removal/sharing actions generate events. Events are grouped by types and each type has a 'last modification time' associated. Those events and times can be retrieved using:

The current event types are:

TAP+ NOTIFICATIONS

Notifications are kept for one month. Each notification provides a message that explains the notification. Notifications are available for authenticated users only.

TAP+ JOBS CAPABILTIES

TAP+ DELETEJOBS CAPABILITIES