Tim Kimball $Id: DSS_ICD,v 1.6 1997/07/31 18:54:35 kimball Exp $
This document shows you how to use the DSS CGI scripts at ST ScI. You can use this information to create tools that access the DSS remotely. IMPORTANT: The DSS is a limited resource! We cannot continue to support automated requests for large numbers of large files. Please do not write tools that automatically submit multiple simultaneous requests, and please retrieve large files sparingly.
In the URL, "archive" is preferred over "stdatu", though the latter is more widely published and bookmarked.
You can use the interface described below to either draw the DSS standard
form with the given values set as the defaults, or to fetch an image from
the jukebox. To draw the form, use the URL
http://archive.stsci.edu/cgi-bin/dss_form
and to fetch an image, use
http://archive.stsci.edu/cgi-bin/dss_search
All of the parameters described below will be used in the scripts. (The
form script, however, will not validate the values.)
Method can be either GET or POST.
Here are the CGI parameters currently recognized:
r - right ascension
d - declination
e - equinox (B1950 or J2000; default: J2000)
h - height of image (arcminutes; default: 15.0)
w - width of image (arcminutes; default: 15.0)
f - image format (FITS or GIF; default: FITS)
c - compression (UNIX, GZIP, or NONE; default: NONE; compression
applies to FITS only)
v - Which version of the survey to use:
1 - First Generation survey (garden variety)
2 - Second generation survey (incomplete)
3 - Check the 2nd generation; if no image is available,
then go to the 1st generation.
4 - The Quick V survey (whence came the Guide Stars Catalog;
used mostly for Phase II proposal submission)
s - Save the file to disk instead of trying to display.
(ON (or anything) or not defined; default: not defined.)
Case is not significant in the values, but it is in the parameter names (e.g., use r=, not R=).
If these are too cryptic, there are synonyms:
r -> ra d -> dec e -> equinox h -> height w -> width f -> format c -> compression v -> version s -> saveAgain, case counts in the parameter names, but not in the values.
If for some reason you want to overlay an HST field of view on a GIF image (won't work with FITS), use the following additional CGI parameters:
fov - which FOV to overlay (NONE, LAUNCH, SM93, SM97; default: NONE) v3 - V3 roll angle (default: 0.0)
RA and DEC can be a single decimal number (interpreted as degrees) or in HMS/DMS, separated by anything but 0-9, +, -, or . (dot). So the following are valid values of RA/Dec:
RA DEC
------------ -------------
187.277915 2.052389
12 22 31.98 29 53 45.55
12:22:31.98 +29:53:45.55
12h 22' 31.98" 29d 53' 45.55"
12h 22m 29d 53m
Note that seconds are optional, as is the plus sign on a positive dec.
One caveat: There's a bug I've been meaning to fix, where if you give
RA in HMS format but give it in degrees instead, it will not recognize
it as such; i.e., an RA of 65 40 50.9 will be accepted by the CGI
script, but will cause an error when the field is extracted. In that
case, you get back text/html.
The height and width are limited to 60 arcminutes or less. The compression parameter "c" will be ignored if the format "f" is GIF. The field of view parameters ("fov" and "v3") will be ignored unless the format "f" is GIF. (FOVs can only be overlaid on GIF images.) The save parameter "s" can be set to anything. An HTML checkbox will set it to "on", but the script will test for any value.
The MIME type will be either image/x-fits or image/gif unless you set the save-to-disk parameter "s" to anything, in which case it will be application/octet-stream. Setting "s" to nothing does not define it.
If compression was used, then there will be a Content-encoding of either "x-compress" or "x-gzip".
The following conditions will return an HTML error message (Content-type: text/html):