Atlas Search Service Program Interface

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 "https://irsa.ipac.caltech.edu/cgi-bin/Atlas/nph-atlas?mission=GLIMPSE&locstr=m17&regSize=0.1&mode=PI"

where the

Base URL for the service is: https://irsa.ipac.caltech.edu/cgi-bin/Atlas/nph-atlas
Input parameters are specified by parameter/value pairs, e.g. "locstr=m17" searches for data covering M17.
Output is an XML file containing URL links to metadata tables, download scripts to retrieve data, and the same HTML result page that is generated in interactive mode.

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.

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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.

Dummy 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>
	  https://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/index.html 
        </resultHtml>
        <resultMap>
          https://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/region.gif 
        </resultMap>
        <resultFits>
          https://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>
            https://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/wget_data.bat 
        </downloadScript>
      </summary>
      <images>
        <counts> 4  <counts> 
        <metadata>
            https://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/images.tbl 
        </metadata>
        <metadataVOtable>
            https://irsa.ipac.caltech.edu/workspace/TMP_AAAylaqUG/Atlas/MESSIER_016.v0001/images.xml 
        </metadataVOtable>
      </images>
      <sources>
        <counts>  7342  </counts>
        <metadata>
            https://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.
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.