IRSA Image Server - Queries

Overview

The query layer of the IRSA Image Server provides the ability to perform spatial and/or relational queries on image metadata tables, with output in IPAC ASCII table, comma-separated-value (CSV), or tab-separated-value (TSV) format. Queries are performed by appending a query string to a base URL identifying the table to query. The available tables are browsable here. The query output format is controlled by the ct parameter, which may always be specified, regardless of the query type. The following values are recognized:

ct=htmlPretty-printed HTML
ct=ipacIPAC ASCII table format
ct=csvComma-separated-value format
ct=tsvTab-separated-value format

Column listings

To see the columns of a particular image metadata table, append the FORMAT parameter with a value equal to METADATA to the base URL. For example, <root>/search/wise/allsky/4band_p1bm_frm?FORMAT=METADATA&ct=html will return a listing of the WISE All-Sky Release Level 1B Frame metadata table columns in HTML format.

Relational queries

The following parameters can be used to specify relational (SQL) queries. Note that they can be combined with a spatial constraint (documented below).

columns=name1,name2,....

The columns parameter value must be set to a comma separated list of the column names that should be output. If this argument is omitted, a table specific default column-set is used.

Examples:

  • columns=scan_id,frame_num,band
  • columns=coadd_id,magzp
where=SQL

The where parameter can be set to a SQL WHERE clause, with some restrictions. Notably, function calls and sub-queries are not supported. You can use AND, OR, NOT, IN, BETWEEN, LIKE, IS, the usual arithmetic and comparison operators, and literal values.

Note that the where parameter is required in the absence of POS (a spatial constraint).

WHERE clauses should be URL encoded. Examples:

band IN (1,2,3) → band%20IN%20(1,2,3)
crval1 between 19 and 21 and (crval2>39 and crval2<41) → crval1%20between%2019%20and%2021%20and%20(crval2%3E39%20and%20crval2%3C41)

Spatial queries

Spatial queries return images that are related to a search region (specified via the POS and SIZE parameters) according to a spatial predicate (specified via the INTERSECT parameter).

POS=ra,dec

The POS parameter value must consist of an ICRS right ascension and declination in decimal degrees. It identifies the point which returned images must contain, or the center of the search region. The coordinate values must be separated by a comma; no embedded whitespace is allowed.

POS is required in the absence of where.

Examples:

  • POS=359,10
  • POS=10,-89.5
SIZE=width[,height]

The SIZE parameter consists of one or two (comma separated) values in decimal degrees. The first SIZE value is taken to be the full-width of the search region along the east axis at POS, and the second is taken to be the full-height along the north axis. Taken together, POS and SIZE define a convex spherical polygon on the sky with great circle edges - the search region. During a query, this region is compared against the convex spherical polygons formed by connecting the 4 corners of each image in a data-set to determine which images should be returned.

If only one size value is specified, it is used as both the full-width and full-height. Negative sizes are illegal, and a width and height of zero indicate that the search region is a point.

SIZE is an optional parameter. If unspecified, the default search region width and height is 0 (i.e. the search region is just the point POS). Note also that if INTERSECT=CENTER (see below), SIZE is ignored.

Examples:

  • SIZE=0.1
  • SIZE=1,2
INTERSECT=value

The INTERSECT parameter specifies a spatial predicate that specifies how the search region S and the spatial extents of a candidate image X must be related. Four values are allowed:

  • COVERS: X must completely contain S. Equivalent to CENTER and OVERLAPS if S is a point.
  • ENCLOSED: S must completely contain X. If S is a point, the query will always return an empty image table.
  • CENTER: X must contain the center of S. If S is a point, this is equivalent to COVERS and OVERLAPS.
  • OVERLAPS: The intersection of S and X is non-empty. If S is a point, this is equivalent to CENTER and COVERS.

The INTERSECT parameter is optional; if unspecified, it defaults to OVERLAPS.

The spatial extent of an image is approximated by connecting its corners with great circles to form a spherical convex polygon. The search region as defined by this service is also a spherical convex polygon (or a point). Spatial predicate evaluation is performed on pairs of spherical convex polygons without recourse to any performance motivated short-cuts. Nevertheless, the implementation uses floating point arithmetic and results are therefore not guaranteed to be mathematically exact. Note also that the spatial extent of an image with a non-gnomonic projection (or large distortion terms) may not be well approximated by the technique employed. However, the images currently being served have gnomonic or orthographic projections, are of small area and have small distortion terms - hence, we believe our approximations are accurate enough to be useful.

mcen

The mcen parameter indicates that only the most centered image/image set (with respect to POS) should be returned, rather than all images/image sets containing POS. If the SIZE parameter is specified and non-zero, the mcen parameter is ignored (except when INTERSECT=CENTER).

Note that mcen is not required to have a value. If one is nevertheless specified, it is ignored.

Examples

Here is a query returning all WISE All-Sky Release Level 1b Frames containing (ra,dec) = (20,40) in bands W1 and W2:

And here is a query returning the most centered WISE All-Sky Atlas W1 coadd with respect to (ra,dec) = (20,40):

Table uploads

It is also possible to search for multiple positions in one query (rather than issuing a series of spatial queries). This can be accomplished by setting the value of the POS parameter to the contents of an IPAC ASCII table file containing search positions. The query must be submitted via an HTTP POST rather than a GET, and the table file must contain two columns named ra and dec such that each row corresponds to a single POS value. Any other columns in the table are ignored. Here's an example IPAC ASCII table (download it here): 

|ra     |dec    |
|double |double |
    70.5    20.1 
    19.5    39.5 
   270.0   -30.3

And here are UNIX shell commands that demonstrate how to query for images overlapping these positions using curl: 

# Download the example table
curl "<server><root>/example.tbl" > example.tbl
# ... and upload it to perform a query
curl -F INTERSECT=CENTER -F "POS=@example.tbl" "<server><root>/search/wise/allsky/4band_p1bm_frm"

Getting Help

If you've run into a problem, think you've found a bug, or simply have questions, please contact IRSA User Support.