Atlas Search Service: Program Interface

Introduction   Input Parameters   Examples   XML Output   Description of XML Tags

Atlas is a search service for contributed datasets at IRSA. A dataset can be searched interactively via a web page, or with a program line call, where the return is an XML file containing links to the results. This document describes the input parameters and the structure of the returned XML for the program interface. The call can also be turned into an input line to a browser to give the same web page result as interactive mode ("HTML mode").

The program interface is for one object at a time. Table upload is not necessary since users can perform the looping themselves.

Atlas serves a large number of datasets. A basic call for a Spitzer GLIMPSE field giving XML output might be (if curl is not available on your system, use "wget -O out.xml ..." ):

curl -o out.xml "http://irsa.ipac.caltech.edu/cgi-bin/Atlas/nph-atlas?mission=GLIMPSE&locstr=m17&regSize=0.1&mode=PI"

where the


  
Input Parameters   Introduction   Examples   XML Output   Description of XML Tags

The input parameters are entered as standard "parameter=value" pairs in HTTP syntax. No extra spaces are allowed (a space can be encoded as a "+" sign) and special characters need to be encoded as shown in any HTTP reference (e.g. here).

Search Parameters

Parameter Values Default Description
mission (see examples below) NA The mission parameter is required. It is an acronym or short name for the dataset. Here is a complete list of the datasets.
locstr (see examples below) NA This is the search location which is required. The input can be coordinates or an astronomical object name. If it is an object name, it is resolved into coordinates using NED and, if that fails, SIMBAD.
regSize (number) NA The box search size, in degrees, for the image spatial search. This parameter is required for image data. In most cases, the maximum allowed regSize value is 12.5 degrees, but it can be smaller. Maximum values for each dataset are given on the Instructions page.
covers
on
none
none The parameter corresponding to the "Images must cover coordinate" box on the web page. It determines whether returned images must cover the position ("on"), or not.
radius (number) NA The adjustable search radius for catalogs or spectra. The default is regSize/2 and the maximum typically 6.25 degrees, but it can be smaller. The regSize and radius parameters can be set independently, allowing for flexibility in images vs catalog/spectra searching.
radunits deg
arcmin
arcsec
deg The units of the radius spatial search; the default is "deg".
searchregion
on
none
none The parameter corresponding to the "Search whole region" box for catalog sources and/or spectra on the web page. When turned "on", the search for catalog sources and spectra is done using regSize/2 (and any search radius is ignored). Otherwise it will use radius if present.
mode PI NA The mode must be set to "PI" (for Program Interface) to return results in XML. If the mode is not set, the result will be in HTML, not XML.
  

  
Examples       Introduction   Input Parameters   XML Output   Description of XML Tags

Note: The following examples can be run by clicking their links. Both HTML and XML versions will return via the browser -- for XML output in a file, see the example call at the top. The examples do not cover all of the datasets available.

  1. C2D (HTML results)
    nph-atlas?mission=C2D&locstr=RU+Lup&regSize=0.1&searchregion=on
    C2D [mission] data are searched at location of source name "RU Lup" [locstr]; size of image search is 0.1 [regSize] degree; with searchregion turned on, so regSize/2 is used for the spectrum search radius; mode is not set (HTML output).

    C2D (XML results)
    nph-atlas?mission=C2D&locstr=RU+Lup&regSize=0.1&searchregion=on&mode=PI

  2. COSMOS (HTML results)
    nph-atlas?mission=COSMOS&locstr=150.425933+2.430235+eq&regSize=0.1&searchregion=on&covers=on COSMOS [mission] data are searched at location "150.425933 2.430235 eq" [locstr]; size of search is 0.1 [regSize] degrees and images must cover position; with searchregion turned on, regSize/2.0 is used for the source search region; mode is not set (HTML output).

    COSMOS (XML results)
    nph-atlas?mission=COSMOS&locstr=150.425933+2.430235+eq&regSize=0.1&searchregion=on&covers=on&mode=PI

  3. EIGA (HTML results)
    nph-atlas?mission=EIGA&locstr=NGC+7822&regSize=12.5&covers=on

    EIGA (XML results)
    nph-atlas?mission=EIGA&locstr=NGC+7822&regSize=12.5&covers=on&mode=PI

  4. FEPS (HTML results)
    nph-atlas?mission=FEPS&locstr=285.85705+30.87640+ga&regSize=2.0&searchregion=on

    FEPS (XML results)
    nph-atlas?mission=FEPS&locstr=285.85705+30.87640+ga&regSize=2.0&searchregion=on&mode=PI

  5. FIDEL (HTML results)
    nph-atlas?mission=FIDEL&locstr=53.158591+-27.891113+eq&regSize=0.1&covers=on

    FIDEL (XML results)
    nph-atlas?mission=FIDEL&locstr=53.158591+-27.891113+eq&regSize=0.1&covers=on&mode=PI

  6. FLS_ELAISN1_R (HTML results)
    nph-atlas?mission=FLS_ELAISN1_R&locstr=ELAISR20+J161104%2B542834&regSize=0.5

    FLS_ELAISN1_R (XML results)
    nph-atlas?mission=FLS_ELAISN1_R&locstr=ELAISR20+J161104%2B542834&regSize=0.5&mode=PI

  7. FLS_HECTOSPEC (HTML results)
    nph-atlas?mission=FLS_HECTOSPEC&locstr=17h18m57s+60d21m12s+Equ+J2000&radius=0.1&searchregion=none&radunits=deg

    FLS_HECTOSPEC (XML results)
    nph-atlas?mission=FLS_HECTOSPEC&locstr=17h18m57s+60d21m12s+Equ+J2000&radius=0.1&searchregion=none&radunits=deg&mode=PI

  8. FLS_MAIN_R (HTML results)
    nph-atlas?mission=FLS_MAIN_R&locstr=FLSVLA+J171940.2%2B592449&regSize=0.5

    FLS_MAIN_R (XML results)
    nph-atlas?mission=FLS_MAIN_R&locstr=FLSVLA+J171940.2%2B592449&regSize=0.5&mode=PI

  9. FLS_VLA (HTML results)
    nph-atlas?mission=FLS_VLA&locstr=259.7373+60.3533+eq&regSize=0.25&covers=on&searchregion=on

    FLS_VLA (XML results)
    nph-atlas?mission=FLS_VLA&locstr=259.7373+60.3533+eq&regSize=0.25&covers=on&searchregion=on&mode=PI

  10. GLIMPSE (HTML results)
    nph-atlas?mission=GLIMPSE&locstr=m17&regSize=0.4&covers=on

    GLIMPSE (XML results)
    nph-atlas?mission=GLIMPSE&locstr=m17&regSize=0.4&covers=on&mode=PI

  11. GOALS (HTML results)
    nph-atlas?mission=GOALS&locstr=IC+4734&regSize=2.0

    GOALS (XML results)
    nph-atlas?mission=GOALS&locstr=IC+4734&regSize=2.0&mode=PI

  12. GOODS (HTML results)
    nph-atlas?mission=SGOODS&locstr=03h32m38.06s+-27d53m28.0s+Equ+J2000&regSize=0.1&covers=on&searchregion=on

    GOODS (XML results)
    nph-atlas?mission=SGOODS&locstr=03h32m38.06s+-27d53m28.0s+Equ+J2000&regSize=0.1&covers=on&searchregion=on&mode=PI

  13. IGA (HTML results)
    nph-atlas?mission=IGA&locstr=M16&regSize=12.5&covers=on&searchregion=on

    IGA (XML results)
    nph-atlas?mission=IGA&locstr=M16&regSize=12.5&covers=on&searchregion=on&mode=PI
    Note: the XML output results of this example are discussed in the XML Output section below.

  14. IRIS (HTML results)
    nph-atlas?mission=IRIS&locstr=M+31&regSize=12.5&covers=on

    IRIS (XML results)
    nph-atlas?mission=IRIS&locstr=M+31&regSize=12.5&covers=on&mode=PI

  15. IRTS (HTML results)
    nph-atlas?mission=IRTS&locstr=47.09669+-1.71325+ga&regSize=12.5&covers=on&searchregion=none&radius=2.0&radunits=deg

    IRTS (XML results)
    nph-atlas?mission=IRTS&locstr=47.09669+-1.71325+ga&regSize=12.5&covers=on&searchregion=none&radius=2.0&radunits=deg&mode=PI

  16. ISSA (HTML results)
    nph-atlas?mission=ISSA&locstr=NGC+4800&regSize=12.5

    ISSA (XML results)
    nph-atlas?mission=ISSA&locstr=NGC+4800&regSize=12.5&mode=PI

  17. LGA (HTML results)
    nph-atlas?mission=LGA&locstr=M81&regSize=6.0

    LGA (XML results)
    nph-atlas?mission=LGA&locstr=M81&regSize=6.0&mode=PI

  18. LH (HTML results)
    nph-atlas?mission=LH&locstr=159.738690+54.932062+eq+B1950&regSize=159.738690+54.932062+eq+B1950&covers=on&radius=0.1&radunits=deg

    LH (XML results)
    nph-atlas?mission=LH&locstr=159.738690+54.932062+eq+B1950&regSize=0.5&covers=on&radius=0.1&radunits=deg&mode=PI

  19. MIGA (HTML results)
    nph-atlas?mission=MIGA&locstr=335.762875+59.146226&regSize=12.5&covers=on

    MIGA (XML results)
    nph-atlas?mission=MIGA&locstr=335.762875+59.146226&regSize=12.5&covers=on&mode=PI

  20. MIPSGAL (HTML results)
    nph-atlas?mission=MIPSGAL&locstr=NGC+6631&regSize=12.5&covers=on

    MIPSGAL (XML results)
    nph-atlas?mission=MIPSGAL&locstr=NGC+6631&regSize=12.5&covers=on&mode=PI

  21. NExScI_PTI_KI (HTML results)
    nph-atlas?mission=NExScI_PTI_KI&locstr=GLC388&radius=6.25&searchregion=none&radunits=deg

    NExScI_PTI_KI (XML results)
    nph-atlas?mission=NExScI_PTI_KI&locstr=GLC388&radius=6.25&searchregion=none&radunits=deg&mode=PI

  22. MSX (HTML results)
    nph-atlas?mission=MSX&locstr=46.5377+-0.2518+ga&regSize=12.5&covers=on

    MSX (XML results)
    nph-atlas?mission=MSX&locstr=46.5377+-0.2518+ga&regSize=12.5&covers=on&mode=PI

  23. NED (HTML results)
    nph-atlas?mission=NED&locstr=M52&regSize=2.0&covers=none

    NED (XML results)
    nph-atlas?mission=NED&locstr=M52&regSize=2.0&covers=none&mode=PI

  24. SAGE (HTML results)
    nph-atlas?mission=SAGE&locstr=NGC+2070&regSize=2.0&covers=on

    SAGE (XML results)
    nph-atlas?mission=SAGE&locstr=NGC+2070&regSize=2.0&covers=on&mode=PI

  25. Scrapbook (HTML results)
    nph-atlas?mission=Scrapbook&locstr=M18&regSize=5.0&covers=on&searchregion=on

    Scrapbook (XML results)
    nph-atlas?mission=Scrapbook&locstr=M18&regSize=5.0&covers=on&searchregion=on&mode=PI

  26. SINGS (HTML results)
    nph-atlas?mission=SINGS&locstr=hoii&regSize=3.0&covers=on&searchregion=on

    SINGS (XML results)
    nph-atlas?mission=SINGS&locstr=hoii&regSize=3.0&covers=on&searchregion=on&mode=PI

  27. SWIRE (HTML results)
    nph-atlas?mission=SWIRE&locstr=ELAISR20+J163640%2B413132&regSize=1.0&covers=on&searchregion=on

    SWIRE (XML results)
    nph-atlas?mission=SWIRE&locstr=ELAISR20+J163640%2B413132&regSize=1.0&covers=on&searchregion=on&mode=PI

  28. SWS (HTML results)
    nph-atlas?mission=SWS&locstr=290.971773+11.774474+EQ&radius=5.0&searchregion=none&radunits=deg

    SWS (XML results)
    nph-atlas?mission=SWS&locstr=290.971773+11.774474+EQ&radius=5.0&searchregion=none&radunits=deg&mode=PI

  29. Taurus (HTML results)
    nph-atlas?mission=Taurus&locstr=68.74+26.205+eq&regSize=2.0&covers=on

    Taurus (XML results)
    nph-atlas?mission=Taurus&locstr=68.74+26.205+eq&regSize=2.0&covers=on&mode=PI


  
XML Output     Introduction   Input Parameters   Examples   Description of XML Tags

XML output is used in program mode as it is easier to parse than HTML. However the user must parse the XML file to extract the links to retrieve data files (using curl or wget).

Below is example XML output for three of the use cases above. The first is from Example 13, a normal return. The second is an example error using an invalid coordinate locstr. The third is an example of a notification that no sources were found for a valid position.

At the bottom are descriptions of the XML data.

Note: In the real XML files, all this is just text. Here we have turned some of this text into example links to show what to retrieve.

Output from Example 13:

 
    <?xml version="1.0"?>
    <result status="ok">
      <description> 
        <collection> IGA  </collection> 
        <ra> 274.700730  </ra> 
        <dec> -13.807230  </dec> 
        <regSize> 12.500000  </regSize>  
        <radius> 6.250000  </radius> 
        <radunits> degrees  </radunits> 
      </description>
      <coverageMap>
        <resultHtml>
	  http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/index.html 
        </resultHtml>
        <resultMap>
          http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/region.gif 
        </resultMap>
        <resultFits>
          http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/region.fits 
        </resultFits>
      </coverageMap>
      <summary>
        <counts>
          <imagesN> 4  </imagesN> 
          <sourcesN>  7342  </sourcesN>
          <spectraN>  0  </spectraN>
        </counts>
        <downloadScript>
            http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/wget_data.bat 
        </downloadScript>
        <dataTag>
             ADS/IRSA.Atlas#2008/0423/144647_1313 
        </dataTag>
      </summary>
      <images>
        <counts> 4  <counts> 
        <metadata>
            http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/images.tbl 
        </metadata>
        <metadataVOtable>
            http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/images.xml 
        </metadataVOtable>
      </images>
      <sources>
        <counts>  7342  </counts>
        <metadata>
            http://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/IRAS_point_sources.tbl 
        </metadata>
      </sources>
    </result> 
  

Output with an error condition:

 
    <?xml version="1.0"?>
    <result status="error">
      <message>
         Object lookup failed for source.
      </message>
    </result>
  

Output with a warning that no sources were found for requested position:

 
    <?xml version="1.0"?>
    <result status="warning">
      <message>
          No images or sources were found for location: 17h 45m 37.22s -28d 56m 10.2s Eq J2000.
      </message>
    </result>
  


Description of XML Tags     Introduction   Input Parameters   Examples   XML Output

Tag name description
result 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" indicating that something went wrong during the query, or "warning" if the requested position had no results.
message This tag contains the error message when the query status = "error" or "warning".
description This series of tags contain input parameter information regarding the data collection, location of search and size of search.
collection This tag contains the name of the dataset.
ra The Right Ascension of the requested search, in decimal degrees [J2000]
dec The Declination of the requested search, in decimal degrees [J2000]
regSize For images, the search box size (in degrees)
radius For catalog & spectra, the search radius size
radunits For catalog & spectra, the search radius units
coverageMap This section contains files that shows the overall search results and graphical coverage map of the retrieved data: resultHtml, resultMap and resultFits.
resultHtml An HTML page that contains the entire set of search results, along with the resultMap and resultFits image plus the captions which includes the search location, range, and the details descriptions of the graphical representations on the JPEG (or GIF) image.
resultMap A JPEG (or GIF) image showing the footprints of the retrieved data.
resultFits A FITS image without the footprints, which is used to make the sky resultsMap image.
summary Overall summary of all available data.
counts The numbers of results found, for images, catalog sources and spectra.
imagesN Numbers of retrieved image (FITS) data files.
sourcesN Numbers of catalog sources found.
spectraN Numbers of spectra found.
downloadScript A link to a script (file) which contains bulk download instructions using the unix tool "wget" to download all the search results: image FITS, source catalog(s) and spectra metadata.
dataTag A string which contains the Data Tag for the query made. This tag can be used in journal publications to indicate IRSA data usage.
images This section contains the information regarding the image results; metadata is provided in ASCII IPAC table format (metadata tag name), as well as in VO Table format (metadataVOtable tag name). Note, these tags do not exist if no images were found.
metadata An IPAC formatted ASCII table containing the parameters of the FITS image results set.
metadataVOtable The VO Table version of the image metadata FITS image results set.
sources This section contains the information regarding the catalog source results; each catalog is provided in ASCII IPAC table format (metadata tag name); the number of sources in that catalog is indicated by the counts tag. Note, these tags do not exist if no sources were found.
counts The number of sources matching the search criteria for one source list; the source list results are in the next metadata tag.
metadata An IPAC formatted ASCII table containing the catalog sources matching the search criteria.
spectra This section contains the information regarding the spectra source results; each spectra metadata table is provided in ASCII IPAC table format (metadata tag name); the number of spectra in that catalog is indicated by the counts tag. Note, these tags do not exist if no spectra were found.
counts The number of spectra matching the search criteria for one list of spectra; the spectra metadata results are in the next metadata tag.
metadata An IPAC formatted ASCII table containing the spectra source metadata matching the search criteria. This file can be used to get the spectra files themselves (one in each row of the metadata table). The user must decide which file(s) to download, as spectra generally come in many different formats, which are indicated by different columns in the metadata.