Home About Holdings Missions Documentation Helpdesk

Galactic Dust Extinction Service: Program Interface

Introduction   Examples   XML Output   Description of XML Tags

The Galactic Dust Reddening and Extinction service can be accessed via an HTTP GET/POST program interface where the request is a set of "parameter=value" pairs and the return is an XML document containing the results of the area statistics, an extinction table , and the URLs of the image cutouts from the following three maps: E(B-V) reddening, 100 micron intensity, and dust temperature. This document describes the input parameters and the structure of the returned XML.

Some of the interactive features found on the HTML form interface (such as clicking on the all-sky map to define coordinates or the clicking of a result image to fine-tune the input coordinate) are not available. Program-mode programmer/users will presumably want to control this sort of functionality themselves. Similarly, the table upload option on the form interface (which loops over a list of coordinates to produce all the results in one submit) is not necessary in program mode since programmers can perform this looping themselves.

The following shows a typical query:

http://irsa.ipac.caltech.edu/cgi-bin/DUST/nph-dust?locstr=m51

where the

  
Input Parameters   Introduction   Examples   XML Output   Description of XML Tags

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 equal 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 cause ambiguities they have to be encoded as shown in any HTTP or URL reference. As shown above, these pairs are separated from each other by ampersand (&) characters.

  
Input Parameters

Parameter Values Default Description
locstr (locstr examples) NA This is the only required parameter; if the input is an object name, it is resolved into coordinates using NED and, if that fails, SIMBAD.
regSize a decimal number 5.0 The regSize is the size of image cutout in decimal degrees which defaults to 5.0 degrees.
  
Examples       Introduction   Input Parameters   XML Output   Description of XML Tags

Note: The following examples can be run by clicking their links; examples 1 through 3 produce valid results while 4 through 6 are examples of the error conditions.

  1. nph-dust?locstr=m51
    Generates area statistics for the area centered on object "m51" and produces image cutouts with default image size of 5.0 degrees (see the output from Example 1 in the XML Output session below).

  2. nph-dust?locstr=m101®Size=2.0
    Generates area statistics for the area centered on object "m101" and produces image cutout sizes of 2.0 degrees.

  3. nph-dust?locstr=266.0+-60.+equ+j2000
    Generates area statistics for the area centered on coordinate "266.0 -60. equ j2000" and produces image cutout sizes of default 5.0 degrees.

  4. nph-dust?locstr=xxx
    The input location of this query is unresolvable, it produces the error condition: "Failed to resolve object [xxx] using both NED and SIMBAD." (see the output from Example 4 in the XML Output section below).

  5. nph-dust?locstr=m51®Size=1.0
    The input search radius of this query is smaller than 2.0 degrees, it produces the error condition: "ERROR: Invalid image size[1.0]: must be between 2.0 and 37.5 degrees."

  6. nph-dust?locstr=m51®Size=40.0
    The input search radius of this query is larger than 37.5 degrees, it produces the error condition: "ERROR: Invalid image size[40.0]: must be between 2.0 and 37.5 degrees."

  
XML Output     Introduction   Input Parameters   Examples   Description of XML Tags

Normally, when you run a web application the return is HTML text which is rendered in a browser and contains links to download additional data files. However, HTML is notoriously difficult to parse, so in program mode we instead return a simple XML document. This document can be rendered in a browser but the normal use pattern is as follows: have your program make an HTTP request using the above parameters; retrieving the XML result into a file (or memory); parse it; extract links to the desired final data files; and use these links (again from your program) to retrieve the data.

The interaction above can be done in a variety of ways, ranging from simple scripting (using programs like 'wget') to integrated URL-access and XML-parsing in JAVA, PERL, Python, etc. Our XML is simple enough that if you do not have XML-parsing tools simple pattern checking (manually built code or tools like PERL) should suffice.

The returned XML "inventory" contains the area statistics and URLs to the extinction table and image cutouts. Below we give example XML output for two of the use cases above. The first block is from Example 1 above (a normal return) and the second is an example error return (from Example 4). After these examples, we will enumerate all the tags that might be returned by a successful query. These examples vary only in the input constraints; their XML outputs are identical in layout.

Note: In the real XML files, all this is just text. Here we have turned some of this text into links so you can see examples of the result files. This is just for illustration.

Output from Example 1: 

 
    <?xml version="1.0"?>
    <results status="ok">
      <input>
        <objname>202.482194 47.231509 equ J2000</objname>
        <regSize>5.0 deg</regSize>
      </input>
      <result">
        <desc>E(B-V) Reddening</desc>
        <data>
          <image>
	    http://dodo.ipac.caltech.edu:9010//workspace/mihseh_9010/TMP_AAAiday1A/DUST/m51.v0009/p378Dust.fits
          </image>
          <table>
	    http://dodo.ipac.caltech.edu:9010//workspace/mihseh_9010/TMP_AAAiday1A/DUST/m51.v0009/extinction.tbl
	  </table>
        </data>
        <statistics>
          <refPixelValue> 0.0347 (mag) </refPixelValue>
          <refCoordinate>202.482194 47.231509 equ J2000</refCoordinate>
          <meanValue> 0.0351 (mag) </meanValue>
          <std> 0.0007 (mag) </std>
          <maxValue> 0.0365 (msg) </maxValue>
          <minValue> 0.0334 (msg) </minValue>
        </statistics>
      </result>
      <result>
        <desc>100 Micron Emission</desc>
        <data>
          <image>
	    http://dodo.ipac.caltech.edu:9010//workspace/mihseh_9010/TMP_AAAiday1A/DUST/m51.v0009/p378i100.fits
          </image>
        </data>
        <statistics>
          <refPixelValue> 1.8071 (MJy/sr) </refPixelValue>
          <refCoordinate> 202.482194 47.231509 equ J2000 </refCoordinate>
          <meanValue> 1.8257 (MJy/sr) </meanValue>
          <std> 0.0354 (MJy/sr) </std>
          <maxValue> 1.9127 (MJy/sr) </maxValue>
          <minValue> 1.7415 (MJy/sr) </minValue>
        </statistics>
      </result>
      <result>
        <desc> Dust Temperature </desc>
        <data>
          <image>
	    http://dodo.ipac.caltech.edu:9010//workspace/mihseh_9010/TMP_AAAiday1A/DUST/m51.v0009/p378temp.fits
          </image>
        </data>
        <statistics>
          <refPixelValue> 18.0824 (K) </refPixelValue>
          <refCoordinate> 202.482194 47.231509 equ J2000 </refCoordinate>
          <meanValue> 18.0795 (K) </meanValue>
          <std> 0.0081 (K) </std>
          <maxValue> 18.0872 (K) </maxValue>
          <minValue> 18.0532 (K) </minValue>
        </statistics>
      <result">
    </results>

Output from Example 4: 

 
    <?xml version="1.0"?>
    <results status="error">
      <message>
        Failed to resolve object [xxx] using both NED and SIMBAD.
      </message>
    </results>

Description of XML Tags     Introduction   Input Parameters   Examples   XML Output

The structure of the XML file is straightforward and is fully illustrated by the above examples; we do not provide formal BNF (Backus-Naur form) or schema information. We may add information to the XML as needed, though we will make every effort not to change the existing tag structure in the process.

Tag name description
results This is the top tag of the XML file, it contains a variable "status" indicating whether the query is successful: "ok" for successul query, "error" otherwise.
message This tag contains the error message when the query status = "error".
input This section contains the input parameters.
objname Input parameter objname or coordinate ( see examples).
regSize This is the image cutout size in degrees, it should be between 2.0 and 37.5 degrees. If not specified, it defaults to 5.0 degrees.
result DUST service produces image cutouts and area statistics for E(B-V) reddening, 100 micron intensity, and dust temperature maps. Each "result" tag contains one of the three result sets.
desc The description of the result sets: E(B-V)Reddening, 100 Micron Emission, or Dust Temperature.
data This session contsins the URLs of the result data.
image The URL of an image cutout.
table The URL of an extinction table.
statistics This session contains the area statistics of a 5.0 arcmin area around the input coordinate.
refPixelValue The E(B-V) reddening, 100 micron emission, or dust temperature values of the input coordinate.
refCoordinate The input coordinate.
meanValue The average E(B-V) reddening, 100 micron emission, or dust temperature values.
std The standard deviation of E(B-V) reddening, 100 micron emission, or dust temperature values.
maxValue The maximum E(B-V) reddening, 100 micron emission, or dust temperature values.
minValue The minimum E(B-V) reddening, 100 micron emission, or dust temperature values.