IRSA Image Server API

Overview

The IRSA Image Server API is similar to the IRSA's Simple Image Access v1 API, but expands upon it by including column selection and relational queries. Like IRSA's SIA v1 API, the IRSA Image Server API is limited to WISE/NEOWISE, 2MASS, and PTF. All of the features in this service are available through our VO-compliant TAP server, and we encourage users creating new queries to use our TAP service.

The URL for IRSA Image Server API queries takes the form of:

https://irsa.ipac.caltech.edu/ibe/search/{mission}/{data-set}/{table-name}?{query-constraints}

The possible values for {mission}, {data-set}, and {table-name} are shown in the table below.

Available data-sets

The table below lists all of the data sets that can be used with this service. The link in the "Description" column goes to detailed information regarding the use of the table with the IRSA Image Service API. The link in the "table-name" column displays all of the columns available for the table.

Description mission data-set table-name
2MASS All-Sky Image Metadata Table 2mass allsky allsky
2MASS Full Survey Atlas Image Metadata Table 2mass full full
2MASS Long Exposure (6X) Full Survey Atlas Image Metadata Table 2mass sixxfull sixxfull
2MASS Long Exposure (6X) Atlas Image Metadata Table 2mass sixxcat sixxcat
2MASS Calibration Scan Atlas Image Metadata Table 2mass calibration calibration
2MASS 6-Degree Mosaic Image Metadata Table 2mass mosaic sixdeg
AllWISE Atlas Image Inventory Table wise allwise p3am_cdd
NEOWISE-R Single Exposure (L1b) Image Inventory Table wise neowiser p1bm_frm
WISE 2-Band Post-Cryo Single Exposure (L1b) Image Inventory Table wise postcryo 2band_p1bm_frm
WISE 3-Band Cryo Atlas Image Inventory Table wise cryo_3band 3band_p3am_cdd
WISE 3-Band Cryo Single Exposure (L1b) Image Inventory Table wise cryo_3band 3band_p1bm_frm
WISE All-Sky Atlas Image Inventory Table wise allsky 4band_p3am_cdd
WISE All-Sky Single Exposure (L1b) Image Inventory Table wise allsky 4band_p1bm_frm
WISE Preliminary Release Single Exposure (L1b) Image Inventory Table (Superseded) wise prelim p1bm_frm
WISE Preliminary Release Atlas Image Inventory Table (Superseded) wise prelim p3am_cdd
WISE Preliminary 2-Band Post-Cryo Single Exposure (L1b) Image Inventory Table (Superseded) wise prelim_postcryo p1bm_frm
PTF Level 1 Images ptf images level1
PTF Level 2 Images ptf images level2

Query Constraints

An SIA v1 query returns a table of files satisfying the constraints of the query. SIA v1 constraints are entirely limited to spatial queries using the POS, SIZE, and INTERSECT parameters. The results from SIA v1 queries are VO Tables.

SIA v1 Query Parameters:

columns

The columns parameter identifies the columns of the queried table to be returned in the results file. The column names must match the names given in the various tables and must be separated by commas (',') in the query string. If this parameter is not included, then a select set of useful columns in the queried table will be returned.

Examples:

  • columns=coadd_id,band,ra,dec
  • columns=ut_date,filter,telname
where

The where parameter allows users to submit SQL-like constraints on the columns. In order to ensure that the where clause is properly interpreted, a plus sign ('+') should be used in place of a space. Also, be sure to encode '<' as '%3C' and '>' as '%3E'.

Examples:

  • where=band+in+(1,2)
  • where=coaddno%3C100
POS

The POS parameter defines the central position of the search region of interest. The position is given by two values separated by a comma (',') with no whitespace. Values are right ascension and declination in decimal degrees using the ICRS coordinate system.

Examples:

  1. A postion centered on (164.7, -5.8):

    POS=164.7,-5.8

  2. A postion centered on (12.34, 5.09):

    POS=12.34,5.09

The POS parameter implementation in the IRSA Image Server API permits uploading a table of coordinates stored in a file. The file should be a simple file with only 'ra' and 'dec' columns formatted like an IPAC table (see example.tbl). See the example below for using a table of positions in a query.

SIZE

The SIZE parameter defines the angular region of interest centered about POS. The region can be provided using one or two values, which have units of decimal degrees. If only one value is given, it applies to both axes. For two values, the numbers must be separated by a comma (',') with no whitespace; the first number is the angular width along the right ascension axis and the second number is the width along the declination axis. The region defined by this parameter assumes no rotation.

Examples:

  1. A region of interest with lengths 0.2 degrees along the right ascension and declination axes:

    SIZE=0.2

  2. A region of interest with a size of 0.1 degrees in the right ascension axis and 0.5 degrees in the declination axis:

    SIZE=0.1,0.5

  3. Find data that contains the search position:

    SIZE=0

INTERSECT

The INTERSECT parameter defines how the matched images should intersect the search region. The allowed values are:

  • COVERS: The image covers the entire search region.
  • ENCLOSED: The image is entirely enclosed by the search region.
  • CENTER: The image overlaps the center of the search region.
  • OVERLAPS: The image overlaps with some part of the search region.

Examples:

  • INTERSECT=COVERS
  • INTERSECT=ENCLOSED
  • INTERSECT=CENTER
  • INTERSECT=OVERLAPS

INTERSECT=OVERLAPS is assumed if this parameter is not included in the query.

FORMAT

The FORMAT parameter defines what data should be returned by the query. The allowed values are:

  • ALL: Return all images matching the query contraints.
  • METADATA: Ignore the query contraints and return the metadata for the requested dataset.

Examples:

  • FORMAT=ALL
  • FORMAT=METADATA

FORMAT=ALL is assumed if this parameter is not included in the query.

ct

The ct parameter specifies what type of output the service will return. The default is an IPAC Table, but many options are available:

Examples:

  • ct=FITS
  • ct=JSON
  • ct=HTML

Examples

  1. Find all WISE All-Sky Release Level 1b Frames overlapping with (ra, dec) = (20, 40) and write the results to a VOTABLE.

          wget "https://irsa.ipac.caltech.edu/ibe/search/wise/allsky/4band_p1bm_frm?POS=20,40&ct=VOTABLE" -O wise_allsky_level1b_ra20dec40.vot

  2. Find all 2MASS Allsky images overlapping a search rectangle centered on (ra, dec) = (20, 40) with width and height of 1.5 degrees. Limit results to images with coaddno<100. Results are output to a file with IPAC Table formatting.

          wget "https://irsa.ipac.caltech.edu/ibe/search/twomass/allsky/allsky?POS=20,40&SIZE=1.5&where=coaddno%3C100" -O twomass_allsky_ra20dec40_size1p5.tbl

  3. Find all NEOWISE-R Level 1b Frames containing (ra, dec) = (20, 40) in the W2 filter and with a frame quality score of 10. Return only scan_id, frame_num, date_obs, mjd_obs, and qual_frame columns and save the results to a CSV file.

          wget "https://irsa.ipac.caltech.edu/ibe/search/wise/neowiser/p1bm_frm?POS=20,40&where=band=2+and+qual_frame=10&columns=scan_id,frame_num,date_obs,mjd_obs,qual_frame&ct=CSV" -O wise_neowiser_ra20dec40_band2qs10.csv

  4. Find all AllWISE images corresponding to a list of positions in example.tbl

          curl -o allwise_table_upload.tbl -F INTERSECT=CENTER -F "POS=@example.tbl" "https://irsa.ipac.caltech.edu/ibe/search/wise/allwise/p3am_cdd"

Getting Help

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