TAP Details - Solar Orbiter Archive
TAP DEtails
The entry point is a TAP (Table Access Protocol) server.
You may use HTTP protocol to execute TAP requests at https://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:
Request Type | Description | Syntax |
---|---|---|
METADATA REQUEST | To be used when we want to retrieve the metadata details of product file(s) | https://soar.esac.esa.int/soar-sl-tap/tap/sync?REQUEST=doQuery(...) |
DATA REQUEST | To be used when we want to retrieve a product file or all of them in a single tar file | https://soar.esac.esa.int/soar-sl-tap/data?(...) |
INTERFACE SPECIFICATION
See the following specifications:
TAP RESOURCES
https://soar.esac.esa.int/soar-sl-tap/tap/
Tables | https://soar.esac.esa.int/soar-sl-tap/tap/tables |
||
Synchronous access | https://soar.esac.esa.int/soar-sl-tap/tap/sync |
||
Asynchronous access | https://soar.esac.esa.int/soar-sl-tap/tap/async |
||
Service availability | https://soar.esac.esa.int/soar-sl-tap/tap/availability |
||
Sharing capability (not available yet) |
|
TAP+ | |
Events capability | https://soar.esac.esa.int/soar-sl-tap/tap/event |
TAP+ | |
Notifications capability (not available yet) |
|
TAP+ | |
Jobs listing capability (not available yet) | https://soar.esac.esa.int/soar-sl-tap/tap/jobs |
TAP+ | |
Jobs removal capability (not available yet) | https://soar.esac.esa.int/soar-sl-tap/tap/deletejobs |
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:
https://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 https://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:
https://soar.esac.esa.int/soar-sl-tap/logout
Logout using curl and a cookie file:
curl -k -b cookies.txt -X POST -d -L https://soar.esac.esa.int/soar-sl-tap/logout
SYNCHRONOUS/ASYNCHRONOUS QUERIES
Parameter | Value | Comments |
---|---|---|
REQUEST | doQuery | Requests to execute the provided query |
LANG | ADQL | Query language |
FORMAT | - votable_plain - votable - csv - json |
Results output format (note that 'votable' returns a binary compressed votable) |
QUERY | ADQL query | query |
PHASE | run | Mandatory for "Asynchronous". Query job initial phase |
SYNCHRONOUS QUERIES
Example of direct request:
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.
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'" "https://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'" "https://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: nosniffLocation: https://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 (https://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="https://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.
https://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:
TAP+ TABLES CAPABILITIES
In addition to the standard 'tables' TAP capability, the following parameters can be used too:
Parameter | Value | Comments |
---|---|---|
tables | comma separated full qualified table names | A list of the specified tables will be returned |
schemas | comma separated schema names | A list of the specified schemas will be returned |
only_tables | TRUE / FALSE (default: FALSE) | TRUE: no columns information will be returned |
only_schemas | TRUE / FALSE (default: FALSE) | TRUE: no tables nor columns information will be returned |
These parameters are handled based on the following priorities:
Priority | Parameter | Comments |
---|---|---|
1 | tables != null | No more checks are performed (share_info and share_accessible are handled if present) |
2 | tables == null (default) | More checks are performed |
2.1 | only_schemas = TRUE | No more checks are performed |
2.2 | only_schemas = FALSE (default) | The following checks are performed |
2.2.1 | schema_names != null | The following parameters are applied to the specified schemas only |
2.2.2 | only_tables = TRUE | No columns data are generated |
2.2.3 | only_tables = FALSE (default) | Columns data are generated |
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:
Parameter | Value | Comments |
---|---|---|
id | event type identifier | Optional parameter. If not provided, all events are returned. If provided, only the requested type is returned. |
The current event types are:
Value | Comments |
---|---|
100 | Job created |
101 | Job updated |
102 | Job removed |
210 | Shared item created |
211 | Shared item updated |
212 | Shared item removed |
220 | Shared group created |
221 | Shared group updated |
222 | Shared group removed |
230 | Shared user created |
231 | Shared user updated |
232 | Shared user removed |
300 | Log in |
301 | Log out |
401 | Database quota updated |
402 | File quota updated |
500 | Notification created |
501 | Notification removed |
4000 | Table created |
4001 | Table updated |
4002 | Table removed |
TAP+ NOTIFICATIONS
Notifications are kept for one month. Each notification provides a message that explains the notification. Notifications are available for authenticated users only.
Parameter | Value | Comments |
---|---|---|
session identifier | session identifier | Session identifier provided by a login request Must be added to the HTTP header |
action | GetNotifications |
Notifications associated to the user |
TAP+ JOBS CAPABILTIES
Parameter | Value | Comments |
---|---|---|
session identifier | session identifier | Session identifier provided by a login request Must be added to the HTTP header |
list | job list identifier (e.g. 'sync'/'async') |
Mandatory |
offset | Number of jobs to skip | Optional. '0' by default. |
limit | Number of jobs to return | Optinal. No limit by default. |
order | List of column order records. | Optiona. Each record is composed of: column_name:ASC|DESC |
TAP+ DELETEJOBS CAPABILITIES
Parameter | Value | Comments |
---|---|---|
session identifier | session identifier | Session identifier provided by a login request Must be added to the HTTP header |
JOB_IDS | comma separated job identifiers | Mandatory |
- Removed a total of (10) border attribute.
- Removed a total of (10) cellpadding attribute.
- Removed a total of (10) cellspacing attribute.