TAP interface

The Table Access Protocol (TAP) was developed by IVOA is a second generation DAL interface being developed to provide a general access mechanism for tabular data, including but not limited to astronomical catalogs.

The URL for Gaia@AIP’s TAP service is:
https://gaia.aip.de/tap/

There are numerous ways to use TAP that are explained below.

You can find the full TAP documentation on the IVOA documentation website.

How to use TAP in Python

To set it up, you’ll need to pip install pyvo:

pip install pyvo

To use the TAP interface with your account and to have the results stored in your private database, you can provide pyvo with your API token. The token can be accessed under the url /accounts/token/ of the particular Gaia@AIP site. You’ll need to replace the example token with the token from gaia.aip.de/accounts/token/.

This is how your code will look in Python:

import numpy as np
import matplotlib.pyplot as plt
import pyvo as vo

# init tap service
tap_service = vo.dal.TAPService('https://gaia.aip.de/tap')

# optional: use your API token to use your account
vo.utils.http.session.headers['Authorization'] = 'Token c1a67d3db8b1c93e55573aa1a8a2133a5e65c301'

# run a syncronous query
tap_result = tap_service.run_sync('SELECT TOP 5 source_id, ra, dec FROM gdr2.gaia_source order by random_index')
print(tap_result.to_table())

# run an asyncronous query
tap_result = tap_service.run_async('SELECT TOP 5 source_id, ra, dec FROM gdr2.gaia_source order by random_index')
print(tap_result.to_table())

# manage the jobs yourself
jobs = []

limit = 1000
total = 10000

for offset in range(0, total, limit):
    # sql = 'SELECT * FROM gdr2.gaia_source LIMIT %s OFFSET %s' % (limit, offset)
    sql = 'SELECT * FROM gdr2.gaia_source LIMIT %s' % (limit, )
    print(sql)
    
    job =     tap_service.submit_job(sql, language='postgresql', runid='batch')
    job.run()
    
    jobs.append(job)

# if the job is not finished and an error occurs use
# job.run().wait()
# results = job.fetch_result()
# then collect the results

# collect the results
for job in jobs:
    job.raise_if_error()

    results = job.fetch_result()
    print(presults.to_table().to_pandas())

# clean up
for job in jobs:
    job.delete()

How to use TAP with TOPCAT

Topcat is a Tool for OPerations on Catalogues And Tables.

To use TAP in Gaia@AIP in Topcat, you’ll need to select Gaia@AIP as the service provider in Topcat:
https://gaia.aip.de/tap/

TAP service in Topcat


TAP service in Topcat

Now you can select the table:

TAP interface with Topcat


TAP interface in Topcat

Here you'll find a documentation how to use TAP in Topcat:

How to use TAP on the command line

TAP can also be used with a HTTP command line client. Here we use HTTPie, but there are a lot of other similar clients (e.g. curl).

# retrieve the job list
http https://gaia.aip.de/tap/async

# submit an asyncronous job (using PostgreSQL and the 5 minutes queue)
http -f --follow POST https://gaia.aip.de/tap/async \
    QUERY="SELECT ra, dec FROM gdr2.gaia_source WHERE random_index < 100" \
    LANG="postgresql-9.6" QUEUE="5m" PHASE="RUN"

# get all the information about a job
http https://gaia.aip.de/tap/async/78d9c528-8cf0-46e3-8a5b-ec151229a30b

# check the status of a job
http https://gaia.aip.de/tap/async/78d9c528-8cf0-46e3-8a5b-ec151229a30b/phase

# get the results of a job as csv or votable
http https://gaia.aip.de/tap/async/78d9c528-8cf0-46e3-8a5b-ec151229a30b/results/csv
http https://gaia.aip.de/tap/async/78d9c528-8cf0-46e3-8a5b-ec151229a30b/results/votable

# archive the job (this deletes the database table and frees up space)
http --follow DELETE https://gaia.aip.de/tap/async/78d9c528-8cf0-46e3-8a5b-ec151229a30b

As with the Python interface, you can also use your personal token to authenticate with the system to use your personal account (and your personal joblist, quota etc.). To do so, you need to send the token as part of the Authorization header with every HTTP request.

http https://gaia.aip.de/tap/async Authorization:"Token c1a67d3db8b1c93e55573aa1a8a2133a5e65c301"