$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.
Calling the script
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
and to fetch an image, use
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 -> save
Again, 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:
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.
What you get back:
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
The jukebox is busy (i.e., 4 or more getimage processes are
An invalid RA/Dec was passed
The height or width exceed the maximum allowed values
A 2nd-generation scan is not available (and you didn't ask for a
1st if 2nd not available)
The DSS file was not created for some reason (e.g., the server was
out of memory or disk space)
We need to take the jukebox down for any reason (maintenance,
repairs, etc); in that case, the script will return a text/html
message indicating the problem.