DSS Web Access Script
Interface Control Document

Tim Kimball $Id: DSS_ICD,v 1.6 1997/07/31 18:54:35 kimball Exp $

Introduction

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

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.

CGI parameters

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)

Valid values

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.

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 (Content-type: text/html):