The 2MASS Image Inventory Program Interface allows program friendly access to lists of 2MASS Image sets covering a specific region, position, or target object via the VO SIA protocol. It consists of a single CGI program conforming to the VO SIA specification; accordingly, it returns lists of image sets in VOTable form.

Essentially, SIA defines a set of query parameters (and in some cases allowable values) that can be passed to a service via HTTP GET or POST. The service — in this case https://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia — returns an XML table (in VOTable format) of metadata and links for the images satisfying the query parameters.

These images (and their associated artifact locations) can be downloaded programmatically by parsing the output VOTable and issuing HTTP GET requests for the embedded URLs using one of many freely available libraries (for example, C code to do this could use libxml2 and libcurl).

A full description of the SIA and VOTable standards is beyond the scope of this document. Interested readers are encouraged to refer to the official SIA and VOTable specifications. However, a minimal query will typically involve a position or search region (specified using the POS and SIZE parameters) and a 2MASS data set (via the ds parameter). The full set of recognized parameters is listed below, allowing for constraints on date, hemisphere, scan number and image band, as well as other criteria.

Examples

nph-im_sia?FORMAT=METADATA

Returns a VOTable describing service parameters and returned columns

nph-im_sia?POS=-245.0,33.5&SIZE=0.1

Searches for 2MASS All Sky Survey images overlapping a circular region of interest with radius 0.1 deg centered on -245.0 33.5 (J2000). Links to both FITS images and preview pages will be returned.

nph-im_sia?ds=sx&POS=m31&SIZE=0.1&FORMAT=image/fits

Searches for 2MASS 6X Catalog images overlapping a circular region of interest with radius 0.1 deg centered on m31 (short for MESSIER 31), and returning only FITS image links.

Parameters

POS

The position of the region of interest, expressed as the right-ascension and declination of the region center, in decimal degrees using the ICRS coordinate system. A comma should delimit the two values; embedded whitespace is not permitted. As an extension of the standard, object names are also accepted. Names are mapped to search positions via the NED and SIMBAD name resolvers.

SIZE

The angular size of the region given in decimal degrees. Only one value is allowed. A special case is SIZE=0, which is equivalent to searching for all images which cover the given search position. This parameter can be omitted if the INTERSECT parameter is equal to CENTER.

INTERSECT

A parameter that indicates how matched images should intersect the region of interest (ROI). Allowed values are:

COVERS

The candidate image covers or includes the entire ROI.

ENCLOSED

The candidate image is entirely enclosed by the ROI.

CENTER

The candidate image overlaps the center of the ROI.

OVERLAPS (default)

The candidate image overlaps some part of the ROI.

If this parameter is omitted, INTERSECT=OVERLAPS is assumed. Note that the ROI edges (as well as the image boundaries) are approximated using great circles. Coverage computations of the resulting sky-polygons are exact.

FORMAT

Requested format of images. Allowed values are:

ALL (default)

Return URIs for image FITS files and image preview web pages

image/fits

Return URIs for image FITS files

text/html

Return URIs for image preview web pages

METADATA

Return a description of service parameters and returned columns

type

Sets the type of 2MASS image (Atlas or Quicklook) to search for. Atlas Images contain photometric zero point information in their headers and are suitable for quantitative photometric measurements. Quicklook Images are restored from lossy-compressed versions of the Atlas Images and may be used for position measurements, finding charts and visual inspection of the near-infrared sky. Only Atlas Images should be used for quantitative photometric measurements because of the information lost during the Quicklook compression process.

at (default)

Search for Atlas Images

ql

Search for Quicklook Images

ds

The 2MASS data set to search for images in.

asky (default)

2MASS All Sky Release Survey Images

askyw

2MASS Full Survey Images

sx

2MASS 6X Catalog Images

sxw

2MASS Full 6X Images

cal

2MASS Calibration Images

band

Limits 2MASS images returned to those with the given 2MASS Band. If omitted, no restrictions are placed on the 2MASS band of the images returned. Allowed values are:

A (default)

All 2MASS Bands

J

2MASS J-Band

H

2MASS H-Band

K

2MASS K_s-Band

xdate

Limits 2MASS images to those with the given reference date, specified in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date. If omitted, no restrictions are placed on the reference date of the images returned.

Note: date is frequently a database manager reserved word, so the column name xdate is used instead.

hem

The hemisphere of the 2MASS observatory where the FITS images to return were taken. There are only two possible values:

n

north (Mt. Hopkins)

s

south (Cerro Tololo)

If omitted, no restrictions are placed on the observatory hemisphere of the images returned.

scan

The nightly scan number (a positive integer) of the FITS images to return. If omitted, no restrictions are placed on the nightly scan number of the images returned.

Output table columns

Column name	UCD	Column description
name	VOX:Image_Title	Concise description of the image returned.
download	VOX:Image_AccessReference	Image access reference URL.
center_ra	POS_EQ_RA_MAIN	ICRS right-ascension of the image center.
center_dec	POS_EQ_DEC_MAIN	ICRS declination of the image center.
naxes	VOX:Image_Naxes	Number of Image Axes.
naxis	VOX:Image_Naxis	An array giving the length in pixels of each image axis.
scale	VOX:Image_Scale	An array giving the scale in degrees per pixel of each image axis.
format	VOX:Image_Format	MIME-type of the object pointed to by the image access reference URL.
crpix	VOX:WCS_CoordRefPixel	An array specifying the image pixel coordinates of the WCS reference pixel.
crval	VOX:WCS_CoordRefValue	An array specifying the world coordinates of the WCS reference pixel.
crota2	VOX:BandPass_ID	Twist in degrees about Image Center, +AXIS2 West of North (J2000)
band		2MASS Image Band
bref	VOX:BandPass_RefValue	The reference wavelength of the 2MASS Image Filter (meters).
bhi	VOX:BandPass_HiLimit	Upper wavelength limit of the 2MASS Image Filter (meters).
blo	VOX:BandPass_LoLimit	Lower wavelength limit of the 2MASS Image Filter (meters).
pers_art		URL for a VOTable of persistence artifacts potentially affecting the image
glint_art		URL for a VOTable of filter glint artifacts potentially affecting the image
type		Type of Image (Q=Quicklook; A=Atlas)
dataset		The 2MASS dataset the image belongs to, one of: 'asky' (All-Sky Release Survey), 'askyw' (Full Survey), 'sx' (6X Catalog), 'sxw' (Full 6X), 'cal' (Calibration)
pixflags	VOX:Image_PixFlags	Pixel flags of source image
id		Reserved
scntr		Reserved
xdate		The reference date of the FITS image, in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date.
hem		The hemisphere of the 2MASS observatory where the FITS image was taken. There are only two possible values: 'n' = north (Mt. Hopkins), and 's' = south (Cerro Tololo).
scan		The nightly scan number of the FITS image.
image		The image number of the FITS image.
ut_date		UT when the FITS image was taken, in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date.
coadd_key		The coadd_key value of the FITS image. This is a unique identifier for the observation date, observatory hemisphere, nightly scan number, and image number of the FITS image. Each source in the 2MASS All-Sky Point and Extended Source Catalogs is tagged with a coadd_key value identifying the 2MASS Image Set it was extracted from.
seesh		Seeing Full Width Half Maximum (in arcseconds)
magzp		Photometric zero-point magnitude of the FITS image.
msnr10		Approximate SNR=10 magnitude of the FITS image.
bin		The ID of the HTM triangle (subdivision level 7) containing the FITS image reference location.

References

• SIA specification
• VOTable specifications