Simple Image Access v2 Queries
- Overview
- Available datasets
- Metadata queries
- Query Constraints
- Examples
- Understanding the Results
- Downloading Data
- Getting Help
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 datasets
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
- CALIB
- COLLECTION
- DPTYPE
- EXPTIME
- FACILITY
- FORMAT
- FOV
- ID
- INSTRUMENT
- MAXREC
- POL
- POS
- RESPONSEFORMAT
- SPATRES
- SPECRP
- TARGET
- TIME
- TIMERES
- 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:
- Find data that intersects a J-band filter covering 1.154--1.316 micron:
BAND=1.154e-6 1.316e-6
- Find data with wavelength longer than 1.4 micron:
BAND=1.4e-6 Inf
- Find data with wavelength shorter than 1.4 micron:
BAND=-Inf 1.4e-6
- Find data that includes 2.2 micron:
BAND=2.2e-6
- Find data that intersects a J-band filter covering 1.154--1.316 micron:
- 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.
- Level 4: Analysis data products generated after some scientific data manipulation or interpretation.
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 the table of SIAv2 COLLECTION names above.
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 v2 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:
- Find data with exposure times between 60 and 180 seconds:
EXPTIME=60 180
- Find data with exposure times longer than 30 seconds:
EXPTIME=30 +Inf
- Find data with exposure times shorter than 5 minutes:
EXPTIME=-Inf 300
- Find data with exposure times between 60 and 180 seconds:
- 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:
- Find data with a field of view between 0.5 and 1 degrees:
FOV=0.5 1.0
- Find data with a field of view larger than 0.1 degrees:
FOV=0.1 +Inf
- Find data with a field of view smaller than 0.1 degrees:
FOV=-Inf 0.1
- Find data with a field of view between 0.5 and 1 degrees:
- 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:
- A circle with radius=1 degree centered on (164.7, -5.8):
POS=circle 164.7 -5.8 1
- A polygon shape with corners at (164, -5), (165, -5), (164, -6):
POS=polygon 164 -5 165 -5 165 -6 164 -6
- 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.
- A circle with radius=1 degree centered on (164.7, -5.8):
- RESPONSEFORMAT
-
The RESPONSEFORMAT parameter specifies what type of output the service will return. The default is VOTable, but many options are available:
- FITS: Flexible Image Transport System (FITS binary table)
- IPAC_TABLE: IPAC's Table Format
- HDF5: Hierarchical Data Format v5
- VOTABLE: IVOA VOTable
- JSON: JavaScript Object Notation
- CSV: Comma Separated Values (suitable for loading into spreadsheets)
- TSV: Tab Separated Values (suitable for loading into spreadsheets)
- TEXT: Plain text
- HTML: HTML table suitable for embedding within another page
- POSTGRES: SQL for loading the result into Postgres
- SQLITE: SQL for loading the result into SQLite
- ORACLE: SQL for loading the result into Oracle
- DB: Raw SQLite database
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:
- Find data with a spatial resolution between 0.1 and 1.0 arcsec:
SPATRES=0.1 1.0
- Find data with a spatial resolution larger than 0.5 arcsec:
SPATRES=0.5 +Inf
- Find data with a spatial resolution smaller than 1.0 arcsec:
SPATRES=-Inf 1.0
- Find data with a spatial resolution between 0.1 and 1.0 arcsec:
- 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:
- Find data with spectral resolving power between 500 and 5000:
SPECRP=500 5000
- Find data with spectral resolving power higher than 10000:
SPECRP=10000 +Inf
- Find data with spectral resolving power lower than 5000:
SPECRP=-Inf 5000
- Find data with spectral resolving power between 500 and 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:
- Find data obtained between MJD=55123.456 and MJD=55123.789:
TIME=55123.456 55123.789
- Find data obtained at MJD=55123.456:
TIME=55123.456
- Find data obtained between MJD=55123.456 and MJD=55123.789:
- TIMERES
-
The TIMERES parameter defines the temporal resolution to be searched. Values are assumed to be in units of seconds.
Examples:
- Find data with a temporal resolution between 1.0 and 2.0 seconds:
TIMERES=1.0 2.0
- Find data with a temporal resolution larger than 0.5 seconds:
TIMERES=0.5 +Inf
- Find data with a temporal resolution smaller than 1.0 second:
TIMERES=-Inf 1.0
- Find data with a temporal resolution between 1.0 and 2.0 seconds:
Examples
-
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"
-
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"
-
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.