Contents:
+Overall Introduction
+API Introduction
+SHA VO Support: SIAP
+SHA-specific API: Introduction
+SHA-specific API Examples
+SHA-specific API Input Parameters
+SHA-specific API Output Columns
+SHA-specific API Response on error

 

Overall Introduction

There are fundamentally two ways to interact with FinderChart in an automatic or semi-automatic fashion.

The semi-automatic way is to pass a list of sources to the SHA web interface. You can pass a list of up to 1000 sources to the SHA from the search screen. More information on that is in the Searching section. For this, you still need to examine the output of this by hand, but at least you do not have to send targets individually to the server.

The more fully automatic way requires you to write some code that conducts a search query and then parses the results to obtain URLs, from which you can download the data. The rest of this section talks about this API, or application programming interface. There are two different ways to query the database.

API Introduction

An API, or application programming interface, enables programs to interact with the SHA, search for data, and download it. You can write a program that will construct a series of URLs and query our server, resulting in XML files. Then you will need to write code to parse those XML files to obtain the links that you need to download the the data files meeting your search criteria. Please note that it is really easy to inadvertently launch a 'denial-of-service' attack on IRSA's servers if you are not careful. Use this option with caution.

Because the API queries result in XML tables, if you click on any of the links below (in this section), your browser may have trouble rendering it, or will render only bits and pieces of the embedded text. You may need to save the contents of the link to a file in order to read what is returned. You may be able to use "View Source" to see the result in more legible format.

Note that when you parse the XML file, you will be looking for URLs. To retrieve a URL using wget or curl, you should enclose the URL in quotes. Here are some examples using the FinderChart API service.

wget --output-document=file.pdf "http://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997"

curl --output file.pdf "http://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997"

There are two different APIs for the SHA. One is complex and powerful, the other is simple, follows a protocol, and is limited. The Virtual Observatory (VO) is a set of data services that all follow a set of standard API rules agreed upon by the International Virtual Observatory Alliance (IVOA). The simpler API follows these rules.

IRSA also has a page about all the program interfaces at IRSA.

SHA VO Support: SIAP

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.

The base URL for these queries is http://sha.ipac.caltech.edu/applications/Spitzer/VO/VOServices. Here are 2 example URLs. These URLs return XML tables that are lists of the metadata that are a part of the VO search. From the descriptions in the XML metadata table, you can figure out what values you need to change in order to do the search you want to do.

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.

SHA-specific API: Introduction

The SHA data can be accessed via an HTTP GET program interface (basically a really long URL) 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.

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.

SHA-specific API 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

SHA-specific API 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

SHA-specific API 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

Note that to retrieve a URL using wget or curl, you should enclose the URL in quotes. Here are some examples using the FinderChart API service.
wget --output-document=file.pdf "http://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997"

curl --output file.pdf "http://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997"

SHA-specific API 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.