Spitzer Heritage Archive API and VAO Support

Some users may want to interact with the SHA via a program interface; Virtual Astronomy Observatory (VAO) applications are among these users.

Currently, the SHA supports Simple Image Access Protocol (SIAP) for Level 1 (BCD) and Level 2 (PBCD) data access. The services support all required parameters listed in the SIAP specification (POS, SIZE, FORMAT) and VERB parameter with two verbosity levels: 1 and 3. With verbosity level 1, only the required and recommended fields are added to the output table. With verbosity level 3, extra fields might be present. They output all the required and some recommended fields.

Here are the URLs to do metadata queries:
Simple Image Access for level 1 (BCD) images (DATASET=ivo://irsa.ipac/spitzer.level1)

Simple Image Access for level 2 (PBCD) images (DATASET=ivo://irsa.ipac/spitzer.level2)

Spitzer Heritage Archive Application Program Interface (API)

The SHA data can be accessed via an HTTP GET program interface where the request is a set of parameter=value pairs, and what is returned is an IPAC Table containing metadata and URL links to download products with the related ancillary files. This section describes these input parameters and the columns returned.

NOTE THAT spectral data are available via this Simple Image Access Protocol rather than the Simple Spectrum Access Protocol. This API will return all the BCD or PBCD data that the Spitzer Science Center produced. They may be images or spectral data.

Note #2: When you try the URL in the browser, use "View Source" to see the result in proper table format.

Note #3: Please note that it is really easy to inadvertently launch something that is functionally equivalent to a 'denial-of-service' attack on IRSA's servers if you are not careful. Please be sure to test your code using only a subset of your desired requests, and add throttle control to your code, e.g., add some 'wait' steps between successive requests. If we notice an undue load on our servers (a real life example is more than 70,000 requests in less than 10 hours), we will block your IP address, so if your requests suddenly stop working, this may be why. Please contact the IRSA Help Desk if this happens.

Examples

Search by fixed position
applications/Spitzer/SHA/servlet/DataService?RA=163.6136&DEC=-11.784&SIZE=0.5&VERB=3&DATASET=ivo%3A%2F%2Firsa.ipac%2Fspitzer.level2

Search by moving target NAIF ID
applications/Spitzer/SHA/servlet/DataService?NAIFID=2003226&VERB=3&DATASET=ivo%3A%2F%2Firsa.ipac%2Fspitzer.level2

Search by program ID
applications/Spitzer/SHA/servlet/DataService?PID=30080&VERB=3&DATASET=ivo%3A%2F%2Firsa.ipac%2Fspitzer.level2

Search by Astronomical Observation Request ID
applications/Spitzer/SHA/servlet/DataService?REQKEY=21641216&VERB=3&DATASET=ivo%3A%2F%2Firsa.ipac%2Fspitzer.level2

Input parameters

The input parameters are entered as standard HTTP parameter=value pairs in HTTP/GET syntax. In this syntax, the parameter name is followed by an equals sign (=) which is then followed by a value. No extra spaces are allowed, and if the value contains any spaces or special characters that might be ambiguous, they have to be encoded formally as in any HTTP or URL reference (more discussion here: http://www.w3schools.com/tags/ref_entities.asp). As shown above, these pairs are separated from each other by ampersand (&) characters.

DATASETData set. Two sets are supported:
ivo://irsa.ipac.spitzer.level1 (BCD data)
ivo://irsa.ipac.spitzer.level2 (PBCD data)
VERBVerbosity level, controls the number of columns in the output.
1 - selected columns, 3 - all available
RASearch by position: right ascension in degrees
DECSearch by position: declination in degrees
SIZESearch by position: region size in degrees
NAIFIDSearch by moving target: NAIF ID, which is a unique number allocated to solar system objects (e.g. planets, asteroids, comets, spacecraft) by the NAIF at JPL.
PIDSearch by program: program ID
REQKEYSearch by AOR ID: Astronomical Observation Request ID

Output columns

The output columns in the resultant table describe metadata and include a link to download the requested data product and the important ancillary products related to it. Please note that all output columns are available only when verbosity level is set to 3. Fields returned for verbosity is set to 1 are indicated below.

fieldshort descriptionlong descriptionreturned for VERB=1
reqkeyAORKEYSpitzer Astronomical Observation Request Number (key)no
pbcdidPBCD IDPost Basic Calibrated Data ID (Level 2 product search)no
bcdidBCD IDBasic Calibrated Data ID (Level 1 product search)no
hasAccessPublic access "true" if the data is public accessible, "false" if it is proprietary data. no
accessUrlProduct access reference URLThe URL to be used to retrieve image or table, "NONE" if product does not have public accessyes
accessWithAnc1UrlZip access reference URLThe URL to be used to retrieve the image or spectra with important ancillary products (mask, uncertainty, etc.) as a zip archive, "NONE" if product does not have public accessno
modedisplaynameInstrument/ModeInstrument/Modeno
wavelengthBandpassBandpass IDyes
craRA (J2000)Right Ascension in sexigesimal format HHMMSS J2000, of the FITS image. Example: "2h23m14.3s"no
cdecDec (J2000)Declination in sexagesimal format DDMMSS J2000, of the FITS image. Example: "-12d43m11s"no
exposuretimeExposure time in secondsExposure time (Level 1 products only)no
primaryPrimary fieldIf this value is equal to 1, the observation was designed to include the originally specified target. If it is set to 0, the observation was obtained serendipitously of an offset field, and may or may not contain the originally specified target (most often, it does not)no
filetypeTable or ImageTable or Imageno
externalnameFile nameFile nameyes
ptcommentProduct descriptionProduct descriptionno
racrval1 in FITS fileRight Ascension in Equatorial J2000 for the center of the FITS imageyes
deccrval2 in FITS fileDeclination in Equatorial J2000 for the center of the FITS imageyes
epochEpochEpoch yearno
equinoxEquinoxPrecessional year associated with the coordinate systemno
begintimeObservation startObservation start (Level 2 products only)no
endtimeObservation endObservation end (Level 2 products only)no
scetSpacecraft event time: the coordinated universal time on board the spacecraftDate and time of data collection event (Level 1 products only)no
minwavelengthMin wavelength (microns)Min wavelength (microns)no
maxwavelengthMax wavelength (microns)Max wavelength (microns)no
filesizeFile size in bytesFile size in bytesyes
campidCampaign IDInstrument campaign IDno
ra1RA of corner 1RA position of the lower left image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra1, dec1) = (0.5, 0.5)]no
dec1Dec of corner 1DEC position of the lower left image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra1, dec1) = (0.5, 0.5)]no
ra2RA of corner 2RA position of the lower right image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra2, dec2) = (NAXIS1 + 0.5, 0.5)]no
dec2Dec of corner 2Dec position of the lower right image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra2, dec2) = (NAXIS1 + 0.5, 0.5)]no
ra3RA of corner 3RA position of the upper right image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra3, dec3) = (NAXIS1 + 0.5, NAXIS2 + 0.5)]no
dec3Dec of corner 3Dec position of the upper right image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra3, dec3) = (NAXIS1 + 0.5, NAXIS2 + 0.5)]no
ra4RA of corner 4RA position of the upper left image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra4, dec4) = (0.5, NAXIS2 + 0.5)]no
dec4Dec of corner 4Dec position of the upper left image corner [pixel space, where first pixel is located at (0.5, 0.5), position (ra4, dec4) = (0.5, NAXIS2 + 0.5)]no
naxis1naxis1The size of the image in pixels for dimension 1yes
naxis2naxis2The size of the image in pixels for dimension 2yes
cdelt1cdelt1The pixel scale (in degrees on the sky per pixel) at the reference location for dimension 1yes
cdelt2cdelt2The pixel scale (in degrees on the sky per pixel) at the reference location for dimension 2yes
crota2crota2The rotation angle from the "up" direction to the celestial poleyes
crpix1crpix1The pixel coordinate of the reference location (can be fractional, in the image center or off the image) for dimension 1yes
crpix2crpix2The pixel coordinate of the reference location (can be fractional, in the image center or off the image) for dimension 2yes
crval1crval1[deg] RA at CRPIX1, CRPIX2yes
crval2crval2[deg] DEC at CRPIX1, CRPIX2yes
ctype1ctype1The coordinate system (first four characters) and WCS map projection (last three characters) for dimension 1no
ctype2ctype2The coordinate system (first four characters) and WCS map projection (last three characters) for dimension 2no

Response on error

If an error occurs when an HTTP request is being processed, an empty IPAC table with a single attribute, named ERROR, will be returned. The error message is a value of this attribute.