IRSA VO Table Access Protocol (TAP) Instructions

IRSA offers program-friendly interfaces to all of its catalogs. An Application Program Interface (API), allows access to IRSA catalogs (within a script or on the command line) without the need to go through a browser. IRSA accepts three kinds of APIs for catalogs (more on IRSA's Catalog Search APIs).

This page describes IRSA's implementation of the VO Table Access Protocol, or TAP ( TAP protocol document ). TAP allows a rich variety of searches, including cone, box, polygon, or all-sky. You can upload a table with multiple positions. The output can be a VO Table, an IPAC table, a FITS table, or several other formats. It also provides the option of selecting output columns, and performing functions on the results.

Here is an example of how to do a command-line cone search of the 2MASS Point Source Catalog ("fp_psc") with the commonly available curl and wget commands. The units of RA, Dec, and search radius are decimal degrees. The result in "out.xml" is a VOTable, the default format.

curl -o out.xml "https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',66.76957,26.10453,0.01))=1"

wget -O out.xml "https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',66.76957,26.10453,0.01))=1"

Curl is preferred as it handles table upload easier. Note the "+" signs which indicate spaces within a URL. These will be omitted in the descriptions below for clarity. They are not needed with the "-F" option shown below.

How do I get IRSA's Catalog Names and Column Names?

Ready to go and just need the IRSA catalog and/or column names? See the sections labled "table" and "columns" in blue, below.

Constructing a TAP Query

The format for the TAP query depends upon whether you make a synchronous or asynchronous query. A synchronous query runs until it completes and streams the results back -- use this for small-area searches. An asynchronous query will run in the background and give you a place to check whether your job is done, rather than streaming results back directly. For both cases, the main query parameters are QUERY, FORMAT (optional), and UPLOAD (for table upload), described below.

For synchronous calls (small-area searches):

For asynchronous calls (large searches):

In IRSA's implementation of the asynchronous query, PHASE=RUN is required. You will be given a web address that you can use to check on your job. For example, if the address is:

Then you can check the progress of your job by checking the "phase" associated with this job:

This will return either QUEUED, EXECUTING, COMPLETED, ERROR, or ABORT. When the job is completed, you get your results like this:


QUERY:

QUERY=SELECT {columns} FROM {table} WHERE {geometric constraint} AND ({sql constraint}) {order by}{group by} {having}

keyword description
columns

Comma-separated list of column names, or functions of columns to be returned.

Supported functions are those that are both defined in ADQL 2.0 and implemented by database software providers Oracle (most IRSA tables) or Informix (some WISE tables).

Examples (just for illustration -- don't run without constraints):

1. Output all columns.

  • SELECT *

2. Output selected columns.

  • SELECT ra,dec,j_m

3. Output the date of observation from the main 2MASS catalog, but round to the nearest day.

  • SELECT round(jdate, 0) FROM fp_psc

4. Rename the output column returned by "round(jdate,0)" to rounded_jdate.

  • SELECT round(jdate, 0) as rounded_jdate FROM fp_psc

5. Prefix the ra with the table name. This is useful when performing operations on multiple tables.

  • SELECT fp_psc.ra FROM fp_psc

Note on Column Names: To get the available column names, say for the catalog "fp_psc" (retrieving the catalog table name is described in the following section):

curl -o out.xml "https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+TAP_SCHEMA.columns+WHERE+table_name='fp_psc'"

table

Specifies the catalog table to search.

Example (just for illustration):

Select all columns from the COSMOS Photometry catalog.

  • SELECT * FROM cosmos_phot

Note on Catalog Table Names: To obtain the string needed for the "table" parameter, you can download a VOTable of IRSA's available catalogs. The string needed is in the column labeled "table_name". There is also a useful column called "description".

curl -o out.xml "https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+TAP_SCHEMA.tables"

Some Popular Catalogs

table_name Description
allwise_p3as_psd AllWISE Source Catalog
fp_psc 2MASS Point Source Catalog
glimpse_s07 GLIMPSE I Spring 07 Catalog (Spitzer)
cosmos_phot COSMOS Photometry Catalog
iraspsc IRAS Point Source Catalog

geometric contraint

Geometric constraints are typically a CONTAINS function (= 1 for true) operating on a POINT and a shape. There are three supported shape functions. For the shape functions, the first argument, the coordinate system, can be one of 'J2000', 'ICRS', and 'GALACTIC'. Coordinates will be interpreted in terms of that coordinate system. All coordinates and angular sizes are in decimal degrees.

Circle

This requires the coordinate system, coordinates of the center, and radius. A 1 degree cone search around M101 would be:

  • SELECT * FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',210.80225,54.34894,1.0))=1

Box

This requires the coordinate system, coordinates of the center of the box, the width, and the height. The box will be aligned with the coordinate system. A 1 degree by 1 degree box around M101 would be:

  • SELECT * FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec),BOX('J2000',210.80225,54.34894,1.0,1.0))=1

Polygon

This requires the coordinate system, and then a series of coordinates of the vertices. A triangle search around M101 would be:

  • SELECT * FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec),POLYGON('J2000',209.80225,53.34894,209.80225,55.34894,211.80225,54.34894))=1

The region searched is the convex hull of the supplied coordinates, so the order of coordinates does not matter. This is different from the ADQL specification, which allows arbitrary polygons.

Note: Some functions (e.g. count()) do not work when there is a {geometric constraint}.

sql constraint

SQL constraints can be any constraint expressible in ADQL 2.0, with the restriction that functions must be supported by the Oracle (most tables) or Informix (some WISE tables) backend.

Example (just for illustration):

Query the 2MASS Point Source Catalog, and return all columns for records that fall within a certain time range.

  • SELECT * FROM fp_psc WHERE (jdate>=2451500 and jdate<=2451700)
order by

A comma-separated list of column names specifying which to use for sorting the output table rows, in order of priority.

Example:

Query the 2MASS Point Source Catalog. Return all columns for records within a specified time range, and order the results by the observation date. If multiple records have identical observation dates, then order by right ascension.

  • SELECT * FROM fp_psc WHERE (jdate>=2451500 and jdate<=2451700) order by jdate, ra
group by Groups the returned records by the specified columns, which allows you to perform functions on that group.

Example:

Query the 2mass Point Source Catalog. Return all columns for records within a specified time range, and group the records by date.

  • SELECT * FROM fp_psc WHERE (jdate>=2451500 and jdate<=2451700) group by jdate
having Constrains selections after an aggregate function such as "group by". Quicker than a WHERE since it acts on the smaller group.

Example:

Query the 2mass Point Source Catalog. Return all columns for records within a specified time range, group the records by date, then select those in the group with a certain brightness.

  • SELECT * FROM fp_psc WHERE (jdate>=2451500 and jdate<=2451700) group by jdate having j_m < 8

Note: Other ADQL 2.0 functions may also be implemented, but this page is not meant to be a complete description of SQL functions.


FORMAT:

The TAP service will by default return a VOTable. Other formats are also possible by setting the FORMAT keyword. The supported output formats are:

keyword description
VOTABLE VO Table - a type of XML
CSV Comma Separated Value table
TSV Tab Separated Value table
IPAC_TABLE IPAC Table Format
HTML HyperText Markup Language
FITS Flexible Image Transport System Binary Table

UPLOAD:

UPLOAD={name},{URI}

keyword description
name

The name of the table within TAP (e.g. my_favorite_quasars). Prefix this name with TAP_UPLOAD to refer to columns in the query (e.g. TAP_UPLOAD.my_favorite_quasars.ra).

Currently the uploaded table needs to be a VOTable, though a special syntax allows an IPAC table on the local machine. See Example 7 below.

URI Location of table to upload. If it is an http or https URL, then the TAP service will attempt to fetch it over the network. To upload a file along with the query, use the special URL scheme "param". This indicates that the value after the colon will be the name of the inline content. The content type used is multipart/form-data, using a "file" type input element, e.g. the -F option of curl. The "name" attribute in the file input must match that used in the UPLOAD parameter. See Example 7 below.

Examples

  1. Cone Search

    • https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',210.80225,54.34894,1.0))=1
  2. Cone Search returning a FITS table file

    • https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',210.80225,54.34894,1.0))=1&format=fits

  3. Cone Search with only ra, dec, and date rounded to the nearest day
  4. Cone Search with a date filter, ordered by date

    • https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',210.80225,54.34894,1.0))=1+and+(jdate>=2451500+and+jdate<=2451700)+order+by+jdate
  5. Box Search

    • https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),BOX('J2000',210.80225,54.34894,1.0,1.0))=1
  6. Polygon Search

    • https://irsa.ipac.caltech.edu/TAP/sync?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),POLYGON('J2000',209.80225,53.34894,209.80225,55.34894,211.80225,54.34894))=1
  7. Upload local file

    If you have a file "upload.vo", then this command will run a match against objects in the 2MASS catalog.

    • curl -o fp_psc.xml -F "UPLOAD=my_table,param:table" -F "table=@upload.vo" -F "QUERY=SELECT fp_psc.ra, fp_psc.dec FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec), CIRCLE('J2000',TAP_UPLOAD.my_table.ra, TAP_UPLOAD.my_table.dec, 0.01)) =1" https://irsa.ipac.caltech.edu/TAP/sync

    NOTE: If you have an IPAC table "upload.tbl", then this command will run a match against objects in the 2MASS catalog, returning an IPAC table.

    • curl -o fp_psc.tbl -F "UPLOAD=my_table,param:table.tbl" -F "table.tbl=@upload.tbl" -F "FORMAT=IPAC_TABLE" -F "QUERY=SELECT fp_psc.ra, fp_psc.dec FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec), CIRCLE('J2000',TAP_UPLOAD.my_table.ra, TAP_UPLOAD.my_table.dec, 0.01)) =1" https://irsa.ipac.caltech.edu/TAP/sync

  8. Upload remote file

    This will run a simple cone search on WISE and pipe it directly into a cross match with 2MASS.

    • curl -o fp_psc.xml -F "UPLOAD=wise,https://irsa.ipac.caltech.edu/SCS?table=allwise_p3as_psd&RA=210.80225&DEC=54.34894&SR=0.01" -F "QUERY=SELECT fp_psc.ra, fp_psc.dec FROM fp_psc WHERE CONTAINS(POINT('J2000',ra,dec), CIRCLE('J2000',TAP_UPLOAD.wise.ra, TAP_UPLOAD.wise.dec, 0.01)) =1" https://irsa.ipac.caltech.edu/TAP/sync

  9. Asynchronous Cone Search

    Submit the query.

    • curl -v "https://irsa.ipac.caltech.edu/TAP/async?QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',210.80225,54.34894,1.0))=1&PHASE=RUN"

    The output should include a line like:

    • > Location: https://irsa.ipac.caltech.edu/TAP/async/10

    Check the progress of the job.

    • curl "https://irsa.ipac.caltech.edu/TAP/async/10/phase"

    This query completes fairly quickly, so you should see "COMPLETED". To get the results:

    • curl -o fp_psc.xml "https://irsa.ipac.caltech.edu/TAP/async/10/results/result"