Galactic Dust Reddening and Extinction: Program Interface

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

Table upload is not an option in the program interface since one can simply program single-position requests in a loop.

The following shows a typical query,

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

where:

• Base URL for the service is

    https://irsa.ipac.caltech.edu/cgi-bin/DUST/nph-dust

• Input parameters are specified by standard parameter/value pairs. "locstr=m51" specifies the position. Statistics are computed on an area (with fixed 5 arcmin radius) covering location "m51". This query does not specify the size of the image cutouts, so the default size, 5 deg x 5 deg, will be used.
• Output is an XML document containing the area statistics of the three maps, the URLs of the image cutouts, and an extinction table.

Input Parameters  

The input parameters are entered as standard HTTP "parameter=value" pairs in HTTP/GET syntax: the parameter name is followed by an equals sign followed by the value. No extra spaces are allowed and if the value contains spaces or special characters that might cause ambiguities they have to be encoded as shown in any HTTP or URL reference. The pairs are separated from each other by ampersands (&).

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      

Note: The following examples can be run by clicking their links; examples 1-3 produce valid results while 4-6 are errors.

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 XML Output below).
2. nph-dust?locstr=m101&regSize=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 in XML Output below).
5. nph-dust?locstr=m51&regSize=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&regSize=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    

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 the results are returned in simple XML. The XML can be rendered in a browser but the normal usage is as follows: have your program make an HTTP request using the above parameters; retrieve 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 shell 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.

Below we give the XML output for two of the examples above. The first block is from Example 1 above (a normal return) and the second is an example error return (from Example 4). The XML tags for the data values are given below.

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. The servers the links point to are just for illustration.

Output from Example 1:

 
    <?xml version="1.0"?>
    <results status="ok">
      <input>
        <objname>202.484170 47.230560 equ J2000</objname>
        <regSize>5.0 deg</regSize>
      </input>
      <result">
        <desc>E(B-V) Reddening</desc>
        <data>
          <image>
	    https://irsa.ipac.caltech.edu/workspace/TMP_AAAiday1A/DUST/m51.v0009/p378Dust.fits
          </image>
          <table>
	    https://irsa.ipac.caltech.edu/workspace/TMP_AAAiday1A/DUST/m51.v0009/extinction.tbl
	  </table>
        </data>
        <statistics>
          <refPixelValueSandF> 0.0298 (mag) </refPixelValueSandF>
          <refPixelValueSFD> 0.0347 (mag) </refPixelValueSFD>
          <refCoordinate>202.484170 47.230560 equ J2000</refCoordinate>
          <meanValueSandF> 0.0301 (mag) </meanValueSandF>
          <meanValueSFD> 0.0351 (mag) </meanValueSFD>
          <stdSandF> 0.0006 (mag) </stdSandF>
          <stdSFD> 0.0007 (mag) </stdSFD>
          <maxValueSandF> 0.0314 (msg) </maxValueSandF>
          <maxValueSFD> 0.0365 (msg) </maxValueSFD>
          <minValueSandF> 0.0287 (msg) </minValueSandF>
          <minValueSFD> 0.0334 (msg) </minValueSFD>
        </statistics>
      </result>
      <result>
        <desc>100 Micron Emission</desc>
        <data>
          <image>
	    https://irsa.ipac.caltech.edu/workspace/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>
	    https://irsa.ipac.caltech.edu/workspace/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>