Simple Image Access v2 Queries

Overview

The IRSA implementation of the IVOA SIA v2 specification allows users to query the majority of the IRSA holdings through a single, standardized interface. All data set collections available through our SIA v2 service conform to a unified set of metadata, removing the need to know column names in the individual data sets. An overview of how to perform SIA v2 queries in IRSA is provided below - for full details, please see the IVOA SIA v2 specification.

All new programmatic queries of IRSA imaging data sets should use this service over our older APIs.

Available data-sets

The link below provides a list of all the COLLECTIONs available through IRSA's SIA v2 API.

IRSA's SIAv2 COLLECTION names

Query Constraints

An SIA v2 query returns a table of files satisfying any number of constraints. By default, queries return results from all datasets. IRSA's SIA v2 holdings contain almost a billion records, so searches without constraints will time out. Common constraints are spatial (using the POS keyword), dataset (using the COLLECTION keyword), and/or calibration level (using the CALIB keyword) which we describe below. In addition, the type of output can be specified with the RESPONSEFORMAT keyword, and the number of rows can be limited with the MAXREC keyword. The complete list of parameters supported by IRSA's SIA v2 implementation is

BAND

The BAND parameter defines the wavelength interval(s) in meters to be searched for data. The interval can be open or closed, and is inclusive of the bounding values. A BAND constraint is satisfied if the interval intersects the wavelength coverage of the observation as returned in the em_min, em_max columns.

Examples:

  1. Find data that intersects a J-band filter covering 1.154--1.316 micron:

    BAND=1.154e-6 1.316e-6

  2. Find data with wavelength longer than 1.4 micron:

    BAND=1.4e-6 Inf

  3. Find data with wavelength shorter than 1.4 micron:

    BAND=-Inf 1.4e-6

  4. Find data that includes 2.2 micron:

    BAND=2.2e-6

CALIB

The CALIB parameter identifies the calibration level of an observation. This is useful for distinguishing between raw, processed, and highly processed data that are all part of the same collection. The specific meaning for the different levels are specified in the IVOA ObsCore standard:

  • Level 0: Raw instrumental data, in a proprietary or internal data-provider defined format, that needs instrument specific tools to be handled.
  • Level 1: Instrumental data in a standard format (FITS, VOTable, SDFITS, ASDM, etc.) which could be manipulated with standard astronomical packages.
  • Level 2: Calibrated, science ready data with the instrument signature removed.
  • Level 3: Enhanced data products like mosaics, resampled or drizzled images, or heavily processed survey fields. Level 3 data products may represent the combination of data from multiple primary observations.

Examples:

  • CALIB=1
  • CALIB=2
  • CALIB=3
COLLECTION

The COLLECTION parameter identifies the group of data to which an observation belongs. Multiple collections can be queried in the same call by including more than one COLLECTION= clauses. For a complete set of valid options, see IRSA's SIAv2 COLLECTION names.

Examples:

  • COLLECTION=spitzer_sha
  • COLLECTION=wise_allwise
  • COLLECTION=twomass_allsky
  • COLLECTION=twomass_allsky&COLLECTION=wise_allwise
DPTYPE

The DPTYPE parameter specifies the type of data to be searched. The only values allowed here for SIA queries is "image" or "cube."

Examples:

  • DPTYPE=image
  • DPTYPE=cube
EXPTIME

The EXPTIME parameter identifies the range of exposure times to be searched. Values are assumed to be in units of seconds.

Examples:

  1. Find data with exposure times between 60 and 180 seconds:

    EXPTIME=60 180

  2. Find data with exposure times longer than 30 seconds:

    EXPTIME=30 +Inf

  3. Find data with exposure times shorter than 5 minutes:

    EXPTIME=-Inf 300

FACLITY

The FACILITY parameter defines the name of the facility where the data were acquired.

Examples:

  • FACILITY=Wide-field Infrared Survey Explorer
  • FACILITY=Spitzer Space Telescope
  • FACILITY=The 2 Micron All Sky Survey 1.3m Telescope at Cerro Tololo Inter-American Observatory
FORMAT

The FORMAT parameter constrains which data products are returned based on their data format, as listed in the access_format column

Examples:

  • FORMAT=application/x-gzip
  • FORMAT=image/fits
  • FORMAT=text/plain
FOV

The FOV parameter identifies the range of the field of view to be searched. Values are assumed to be in units of decimal degrees.

Examples:

  1. Find data with a field of view between 0.5 and 1 degrees:

    FOV=0.5 1.0

  2. Find data with a field of view larger than 0.1 degrees:

    FOV=0.1 +Inf

  3. Find data with a field of view smaller than 0.1 degrees:

    FOV=-Inf 0.1

ID

The ID parameter defines the identifier of the dataset. The values are strings and searches are case-insensitive.

Examples:

  • ID=ivo://irsa.ipac/wise_allwise/1640m061_ac51
  • ID=ivo://irsa.ipac/twomass_allsky/allsky/990114s/s082
INSTRUMENT

The INSTRUMENT parameter defines the name of the instrument on which the data were acquired.

Examples:

  • INSTRUMENT=GALEX
  • INSTRUMENT=IRAC
  • INSTRUMENT=2MASS Survey Camera
MAXREC

The MAXREC parameter specifies the maximum number of records to retrieve. The default is unlimited. However, any jobs taking longer than 5 minutes will be canceled. For larger jobs, please use TAP

Examples:

  • MAXREC=0
  • MAXREC=100
  • MAXREC=1000000
POL

The POL parameter identifies polarization state to be matched in the data query.

Examples:

  • POL=I
  • POL=LL
  • POL=V

IRSA does not currently contain any data in which the polarization state has been populated.

POS

The POS parameter value must consist of a shape described by ICRS coordinates in decimal degrees. It identifies the shape which returned images must intersect with.

Examples:

  1. A circle with radius=1 degree centered on (164.7, -5.8):

    POS=circle 164.7 -5.8 1

  2. A polygon shape with corners at (164, -5), (165, -5), (164, -6):

    POS=polygon 164 -5 165 -5 165 -6 164 -6

  3. A region spanning RA=104 to 105 deg and Dec=-22 to -12 deg:

    POS=range 104 105 -22 -12

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.

RESPONSEFORMAT

The RESPONSEFORMAT parameter specifies what type of output the service will return. The default is VOTable, but many options are available:

Examples:

  • RESPONSEFORMAT=FITS
  • RESPONSEFORMAT=JSON
  • RESPONSEFORMAT=TEXT
SPATRES

The SPATRES parameter identifies range of spatial resolution to be searched. Values are assumed to be in units of arcsec.

Examples:

  1. Find data with a spatial resolution between 0.1 and 1.0 arcsec:

    SPATRES=0.1 1.0

  2. Find data with a spatial resolution larger than 0.5 arcsec:

    SPATRES=0.5 +Inf

  3. Find data with a spatial resolution smaller than 1.0 arcsec:

    SPATRES=-Inf 1.0

SPECRP

The SPECRP parameter identifies the spectral resolving power to be used in the search. Values are unitless and the resolving power is assumed to be expressed as λ/Δλ.

Examples:

  1. Find data with spectral resolving power between 500 and 5000:

    SPECRP=500 5000

  2. Find data with spectral resolving power higher than 10000:

    SPECRP=10000 +Inf

  3. Find data with spectral resolving power lower than 5000:

    SPECRP=-Inf 5000

TARGET

The TARGET parameter identifies the name of the target of the intended observation. Many datasets (eg, all-sky surveys) may not have target names associated with their observations.

TIME

The TIME parameter identifies the time boundaries in which an observation occurs. The TIME parameters should be entered as numeric values in Modified Julian Date (MJD) and can include an open or closed interval.

Examples:

  1. Find data obtained between MJD=55123.456 and MJD=55123.789:

    TIME=55123.456 55123.789

  2. Find data obtained at MJD=55123.456:

    TIME=55123.456

TIMERES

The TIMERES parameter defines the temporal resolution to be searched. Values are assumed to be in units of seconds.

Examples:

  1. Find data with a temporal resolution between 1.0 and 2.0 seconds:

    TIMERES=1.0 2.0

  2. Find data with a temporal resolution larger than 0.5 seconds:

    TIMERES=0.5 +Inf

  3. Find data with a temporal resolution smaller than 1.0 second:

    TIMERES=-Inf 1.0

Examples

  1. Search for ALLWISE images within 0.01 degrees of ra,dec = (164.7, -5.8). Return the result as in comma-separated value format. 

                wget -O example1.csv "https://irsa.ipac.caltech.edu/SIA?COLLECTION=wise_allwise&POS=circle+164.7+-5.8+0.01&RESPONSEFORMAT=CSV"

  2. Include 2MASS Allsky images in the query and write the results to an IPAC table. 

                wget -O example2.tbl "https://irsa.ipac.caltech.edu/SIA?COLLECTION=wise_allwise&COLLECTION=twomass_allsky&POS=circle+164.7+-5.8+0.01&RESPONSEFORMAT=IPAC_TABLE"

  3. Restrict the data to have wavelengths between 2 and 5 microns, and write the results to a VO Table. 

                wget -O example3.vot "https://irsa.ipac.caltech.edu/SIA?COLLECTION=wise_allwise&COLLECTION=twomass_allsky&POS=circle+164.7+-5.8+0.01&BAND=2.0e-6+5.0e-6"

Understanding the Results

The results table identifies all files matching the search parameters of the query. The exact set of files returned depends on the collection(s) queried but can include items such as calibrated science images, uncertainty maps, image masks, coverage maps, calibration files, and artifact tables. For some collections (eg. twomass_allsky), multiple rows of a single artifact may be returned if that artifact applies to different images.

As mentioned above, the columns in the results tables will be the same regardless of the collection that is queried. To see detailed information about the columns that are returned, visit https://irsa.ipac.caltech.edu/SIA?MAXREC=0 and examine the contents of the <RESOURCE type="results"> section of the VO Table output. It is also instructive to examine the results files from the example queries above as they demonstrate how certain image metadata translates to the unified columns here. For example, image metadata describing the name of the filter used in the observation can be found in the column named energy_bandpassname.

Downloading Data

The location for each file is provided in the access_url column. When downloading files via most browsers, you will be prompted with a "Save As" dialog box including a suggested file name. This behavior is achieved by sending an HTTP Content-Disposition header containing the file name suggestion.

However, command-line clients for web access typically ignore this header by default. Unless instructed otherwise, wget will derive a local file name from the URL (including the query string), and curl will write to standard out. To obtain shorter file names, one can explicitly specify a local file name:

wget
wget -O file <access_url>
wget --output-document=file <access_url>

For example:

wget --output-document=myimage.fits "serverroot/data/wise/allwise/p3am_cdd/16/1640/1640m061_ac51/1640m061_ac51-w1-int-3.fits"
curl
curl -o file <access_url>
curl --output file <access_url>
curl <access_url> > file # uses the shell to redirect standard out to a file

One can also force both wget and curl to honor the file name suggestion in the Content-Disposition header:

wget
wget --content-disposition <access_url>

For example:

wget --content-disposition "serverroot/data/wise/allwise/p3am_cdd/16/1640/1640m061_ac51/1640m061_ac51-w1-int-3.fits"

will download the remote file to a local file named 1640m061_ac51-w1-int-3.fits. Note that the --content-disposition option is only available in wget versions 1.11.x or later.

curl

Using the -J/--remote-header-name option in conjunction with -O/--remote-name does the trick: 

curl -O -J "serverroot/data/wise/allwise/p3am_cdd/16/1640/1640m061_ac51/1640m061_ac51-w1-int-3.fits"

Getting Help

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