Atlas General Search Service: Program Interface

Introduction   Examples   XML Output   Description of XML Tags

Altas is a general search service used to serve many data collections at IRSA. These data can be accessed via an interactive front end (filling in a web form for searching data), as well as 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 URL links to the resulting data and metadata.

This document describes these input parameters and the structure of the returned XML.

Note: Some of the more interactive features found on the HTML form interface (such as clicking on the all-sky map to define coordinates or the interface to preview summaries) 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.

Since Atlas serves data for a large number of different datasets from different missions/collections, there are no default parameters for this service. The programmer must specify all required parameters.

where the

  • Base URL for the service is

    http://irsa.ipac.caltech.edu/cgi-bin/Atlas/nph-atlas

  • Input parameters are specified by standard parameter/value pairs. For instance, "locstr=m51" searches for data covering location "m51" (Messier object 51). Note additional parameters are needed to specify the data collection from which to search for data. These additional parameters are explained in detail below.

  • Output is an XML document containing a set of URL links to: the summaries of retrieved counts; the metadata tables; the download scripts for the retrieved data; and, for completeness, the HTML result page generated for the default interactive (non-program) mode. See the output from Example2 in the XML Output section below for details.

  
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 (e.g. here). As shown above, these pairs are separated from each other by ampersand (&) characters.

The parameters are grouped here for presentation clarity into two subsets: manadatory search parameters for all data collections and manadatory search parameters for for specific data collections.

  
Manadatory Search Parameters for All Data Collections

Parameter Values Default Description
locstr (locstr examples) NA This is the search location parameter; is required for all searches. The input can be a coordinate or astronomical object name; if it is an object name, it is resolved into coordinates using NED and, if that fails, SIMBAD is used for name resolution.
regSize (number) NA The box search size, in degrees, for the image spatial search. This parameters is needed for data collections which contain image data. The size can be any number (interpreted as a double). Note, in most cases, the maximum allowed regSize value is 12.5 degrees, but it varies for the different data collections.
covers
on
none
none The setting for "Images must cover coordinate" allows the user to choose to search for only those images whose footprint on the sky covers the exact input coordinate. If set to "none", all images which overlap the given search area, as determined by location and box size (locstr), will be returned. When turned to on with value "on", the results will show only those data whose footprints overlap the specified input search coordinate.
radius (number) NA The radius search size, for the catalog & spectra spatial search. This parameters is needed for data collections which contain catalogs and/or spectra. The size can be any number (interpreted as a double); generally radius is set to 1/2 the value of regSize, if the user wants to search for catalog & spectra for the same region as the image search size. Note, in most cases, the maximum allowed regSize value is 6.25 degrees, but it varies for the different data collections. The radius search size is specified by two fields: radius and radunits. If radunits are not specified, the default is set to degrees.

Note, unlike the regSize parameter, the radius parameter is matched with units, and therefore can be set with a variety of size & units combinations.

The regSize and radius parameters can be set to completely different size values, allowing for flexibility for imaging vs source/spectra searching around a region of interest.
radunits deg
arcmin
arcsec
deg The units of the radius spatial search, the default is "deg".
searchregion
on
none
none The setting for "Search whole region" for catalog sources and/or spectra. When turned on with setting "on", the search for catalog sources and spectral information is done using the regSize box search, the same search size as for images. Note, when this setting is ("on"), the search radius setting is ignored in this case. When the searchregion is turned off with value "none", then the "radius" value is used for the radius of the cone searchfor catalogs and spectra.

Note, the the radius and searchregion parameters need to be set only for data collections which contain catalogs and/or spectra, where the user would like to use a different search size than for image data. Otherwise, regSize/2.0 is used as the default search size for catalog sources and/or spectra.
mode PI NA Atlas can be run in several different modes; this document is specific to Program Interface (PI) mode only. The mode must be set to "PI" to return results in XML. If the mode is not set, the program's default results set is in HTML, not XML.
  
Manadatory Search Parameters for Specific Data Collections

The mission parameter is madatory for all Atlas searches; this parameters is the acronym or short name for an astronomical mission, data collection or archive, at IRSA. Atlas is a general search service; it serves many different data collections. Therefore, the name of the data collection for searching must be specified, as there is no default dataset that the service searches. The table below gives all the current values for the mission parameter, a full name of the collection is also provided for reference, as well as a link to each data collection. The values for the mission parameter are listed in alphabetical order.

Note: Some data collections are "private" for team access only and require a password to access the data. If you have access privilages, you must send the loggin name and password with your query for data.

Parameter Value Full Name of Mission Example Number
mission C2D Spitzer Space Telescope "From Molecular Cores to Planet-Forming Disks" (C2D) 1
mission COSMOS Cosmic Evolution Survey; and Spitzer-COSMOS (S-COSMOS) data (COSMOS) 2
mission EIGA The Extended IRAS Galaxy Atlas (EIGA) 3
mission FEPS Spitzer Space Telescope "The Formation and Evolution of Planetary Systems: Placing Our Solar System in Context" (FEPS) 4
mission FIDEL Spitzer Space Telescope "Far-Infrared Deep Extragalactic Legacy Survey" (FIDEL) 5
mission FLS_ELAISN1_R The Spitzer First Look Survey (FLS) -- NOAO ELAIS N1 -- R (FLS_ELAISN1_R) 6
mission FLS_HECTOSPEC The Spitzer First Look Survey (FLS) -- Ancillary MMT/Hectospec Spectral Data (FLS_HECTOSPEC) 7
mission FLS_MAIN_R The Spitzer First Look Survey (FLS) -- NOAO Extragalactic -- R (FLS_MAIN_R) 8
mission FLS_VLA The Spitzer First Look Survey (FLS) -- Ancillary VLA Data (FLS_VLA) 9
mission GLIMPSE Spitzer Space Telescope "Galactic Legacy Infrared Midplane Survey Extraordinaire" (GLIMPSE). This includes GLIMPSE I, II and 3D projects. 10
mission GOALS Spitzer Space Telescope "Great Observatory All-sky LIRG Survey" (GOALS) 11
mission GOODS Spitzer Space Telescope "The Great Observatories Origins Deep Survey" (GOODS) 12
mission IGA The IRAS Galaxy Atlas (IGA) 13
mission IRIS The Improved Reprocessing of the IRAS Survey (IRIS) 14
mission IRTS The Infrared Telescope in Space (IRTS) 15
mission ISSA The IRAS Sky Survey Atlas (ISSA) 16
mission LGA The 2MASS Large Galaxy Atlas (LGA) 17
mission LH The 2MASS 6X Lockman Hole Ancillary Data Atlas (LH) 18
mission MIGA The Mid-Infrared IRAS Galaxy Atlas (MIGA) 19
mission MIPSGAL Spitzer Space Telescope "A 24 and 70 Micron Survey of the Inner Galactic Disk with MIPS" (MIPSGAL) 20
mission NExScI_PTI_KI NASA Exoplanet Science Institute (NExScI) Palomar Testbed Interferometer (PTI) & Keck Interferometer (KI) Public Data (NExScI_PTI_KI). Access to metadata is available without username and password, but to download the actual data, you must log into the NExScI archive or register with them if you do not have a username and password. 21
mission MSX The Midcourse Space Experiment (MSX) 22
mission NED The NASA/IPAC Extragalactic Database - Image Data (NED) 23
mission SAGE Spitzer Space Telescope "Surveying the Agents of a Galaxy's Evolution" (SAGE) 24
mission Scrapbook 2MASS Mosaics of MAST Scrapbook Sources (Scrapbook) 25
mission SINGS Spitzer Space Telescope "The Spitzer Infrared Nearby Galaxies Survey - Physics of the Star-Forming ISM and Galaxy Evolution" (SINGS) 26
mission SWIRE Spitzer Space Telescope "The Spitzer Wide-area InfraRed Extragalactic Survey" (SWIRE) 27
mission SWS Infrared Space Observatory (ISO) Spectra from the Short Wavelength Spectrometer (SWS) 28
mission Taurus Taurus 2: Finishing the Spitzer Map of the Taurus Molecular Clouds (Taurus) 29
mission SASS Spitzer Atlas of Stellar Spectra (SASS) 30
mission SDWFS Spitzer Deep Wide Field Survey (SDWFS) 31
mission BLAST Balloon-borne Large Aperture Submillimeter Telescope (BLAST) 32
mission 5MUSES 5 mJy Unbiased Spitzer Extragalactic Survey (5MUSES) 33
mission SSGSS Spitzer SDSS Galaxy Spectroscopic Survey (SSGSS) 34
mission SpUDS Spitzer Public Legacy Survey of the UKIDSS Ultra Deep Survey (SpUDS) 35
mission SIMPLE Spitzer IRAC/MUSYC Public Legacy Survey in the Extended Chandra Deep Field South (SIMPLE) 36

  
Examples       Introduction   Input Parameters   XML Output   Description of XML Tags

Examples are given below using every mission parameter (dataset) listed above. The rest of the parameters are varied to show as examples. The same example is given twice, once for HTTP results and once for XML results(mode=PI). Valid input locations are used for each dataset. Listed at the very bottom of the examples are a few which show error conditions (bad input) and warnings of no data found at a specified location.

Note: The following examples can be run by clicking their links.
  1. C2D (HTTP results)
    nph-atlas?mission=C2D&locstr=L1228®Size=1.0&searchregion=on
    C2D [mission] data are searched at location of source name "L1228" [locstr]; size of search is 1.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; mode is not set (HTTP output).

    C2D (XML results)
    nph-atlas?mission=C2D&locstr=L1228®Size=1.0&searchregion=on&mode=PI
    C2D [mission] data are searched at location of source name "L1228" [locstr]; size of search is 1.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; mode is set to Program Interfer (PI).

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

    COSMOS (XML results)
    nph-atlas?mission=COSMOS&locstr=150.425933+2.430235+eq®Size=0.1&searchregion=on&mode=PI
    COSMOS [mission] data are searched at location "150.425933 2.430235 eq" [locstr]; size of search is 0.1 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; mode is set to Program Interfer (PI).

  3. EIGA (HTTP results)
    nph-atlas?mission=EIGA&locstr=NGC+7822®Size=12.5&covers=on
    EIGA [mission] data are searched at location of source "NGC 7822" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    EIGA (XML results)
    nph-atlas?mission=EIGA&locstr=NGC+7822®Size=12.5&covers=on&mode=PI
    EIGA [mission] data are searched at location of source "NGC 7822" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  4. FEPS (HTTP results)
    nph-atlas?mission=FEPS&locstr=285.85705+%2B30.87640+ga®Size=2.0&searchregion=on FEPS [mission] data are searched at location "285.85705 +30.87640 ga" [locstr]; size of search is 2.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; mode is not set (HTTP output).

    FEPS (XML results)
    nph-atlas?mission=FEPS&locstr=285.85705+%2B30.87640+ga®Size=2.0&searchregion=on&mode=PI
    FEPS [mission] data are searched at location "285.85705 +30.87640 ga" [locstr]; size of search is 2.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; mode is set to Program Interfer (PI).

  5. FIDEL (HTTP results)
    nph-atlas?mission=FIDEL&locstr=53.158591+-27.891113+eq®Size=0.1&covers=on
    FIDEL [mission] data are searched at location "53.158591 -27.891113 eq" [locstr]; size of search is 0.1 [regSize] degrees; with covers turned on; mode is not set (HTTP output).

    FIDEL (XML results)
    nph-atlas?mission=FIDEL&locstr=53.158591+-27.891113+eq®Size=0.1&covers=on&mode=PI FIDEL [mission] data are searched at location "53.158591 -27.891113 eq" [locstr]; size of search is 0.1 [regSize] degrees; with covers turned on; mode is set to Program Interfer (PI).

  6. FLS_ELAISN1_R (HTTP results)
    nph-atlas?mission=FLS_ELAISN1_R&locstr=ELAISR20+J161104%2B542834®Size=0.5 FLS_ELAISN1_R [mission] data are searched at source location "ELAISR20 J161104+542834" [locstr]; size of search is 0.5 [regSize] degrees; mode is not set (HTTP output).

    FLS_ELAISN1_R (XML results)
    nph-atlas?mission=FLS_ELAISN1_R&locstr=ELAISR20+J161104%2B542834®Size=0.5&mode=PI FLS_ELAISN1_R [mission] data are searched at source location "ELAISR20 J161104+542834" [locstr]; size of search is 0.5 [regSize] degrees; mode is set to Program Interfer (PI).

  7. FLS_HECTOSPEC (HTTP results)
    nph-atlas?mission=FLS_HECTOSPEC&locstr=17h18m57s+60d21m12s+Equ+J2000&radius=0.1&searchregion=none&radunits=deg
    FLS_HECTOSPEC [mission] data are searched at location "17h18m57s 60d21m12s Equ J2000" [locstr]; radius size of search is 0.1 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is not set (HTTP output).

    FLS_HECTOSPEC (XML results)
    nph-atlas?mission=FLS_HECTOSPEC&locstr=17h18m57s+60d21m12s+Equ+J2000&radius=0.1&searchregion=none&radunits=deg&mode=PI
    FLS_HECTOSPEC [mission] data are searched at location "17h18m57s 60d21m12s Equ J2000" [locstr]; radius size of search is 0.1 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is set to Program Interfer (PI).

  8. FLS_MAIN_R (HTTP results)
    nph-atlas?mission=FLS_MAIN_R&locstr=FLSVLA+J171940.2%2B592449®Size=0.5
    FLS_MAIN_R [mission] data are searched at location of object "FLSVLA J171940.2+592449" [locstr]; size of search is 0.5 [regSize] degrees; mode is not set (HTTP output).

    FLS_MAIN_R (XML results)
    nph-atlas?mission=FLS_MAIN_R&locstr=FLSVLA+J171940.2%2B592449®Size=0.5&mode=PI FLS_MAIN_R [mission] data are searched at location of object "FLSVLA J171940.2+592449" [locstr]; size of search is 0.5 [regSize] degrees; mode is set to Program Interfer (PI).

  9. FLS_VLA (HTTP results)
    nph-atlas?mission=FLS_VLA&locstr=259.7373+60.3533+eq®Size=0.25&covers=on&searchregion=on
    FLS_VLA [mission] data are searched at location "259.7373 60.3533 eq" [locstr]; size of search is 0.25 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; with searchregion turned on, regSize/2.0 is used for the source search region; mode is not set (HTTP output).

    FLS_VLA (XML results)
    nph-atlas?mission=FLS_VLA&locstr=259.7373+60.3533+eq®Size=0.25&covers=on&searchregion=on&mode=PI
    FLS_VLA [mission] data are searched at location "259.7373 60.3533 eq" [locstr]; size of search is 0.25 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; with searchregion turned on, regSize/2.0 is used for the source search region; mode is set to Program Interfer (PI).

  10. GLIMPSE (HTTP results)
    nph-atlas?mission=GLIMPSE&locstr=m17®Size=0.4&covers=on
    GLIMPSE [mission] (includes GLIMPSE I, II and 3D) data are searched at location of source "m17" [locstr]; size of search is 0.4 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    GLIMPSE (XML results)
    nph-atlas?mission=GLIMPSE&locstr=m17®Size=0.4&covers=on&mode=PI
    GLIMPSE [mission] (includes GLIMPSE I, II and 3D) data are searched at location of source "m17" [locstr]; size of search is 0.4 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  11. GOALS (HTTP results)
    nph-atlas?mission=GOALS&locstr=IC+4734®Size=2.0
    GOALS [mission] data are searched at location of source "IC 4734" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is not set (HTTP output).

    GOALS (XML results)
    nph-atlas?mission=GOALS&locstr=IC+4734®Size=2.0&mode=PI GOALS [mission] data are searched at location of source "IC 4734" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is set to Program Interfer (PI). Note, the XML output results of this example are discussed in the XML Output section below.

  12. GOODS (HTTP results)
    nph-atlas?mission=GOODS&locstr=03h32m38.06s+-27d53m28.0s+Equ+J2000®Size=0.1&covers=on&searchregion=on
    GOODS [mission] data are searched at location "03h32m38.06s -27d53m28.0s Equ J2000" [locstr]; size of search is 0.1 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    GOODS (XML results)
    nph-atlas?mission=GOODS&locstr=03h32m38.06s+-27d53m28.0s+Equ+J2000®Size=0.1&covers=on&searchregion=on&mode=PI
    GOODS [mission] data are searched at location "03h32m38.06s -27d53m28.0s Equ J2000" [locstr]; size of search is 0.1 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  13. IGA (HTTP results)
    nph-atlas?mission=IGA&locstr=M16®Size=12.5&covers=on&searchregion=on
    IGA [mission] data are searched at location of source "M16" [locstr]; size of search is 12.5 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    IGA (XML results)
    nph-atlas?mission=IGA&locstr=M16®Size=12.5&covers=on&searchregion=on&mode=PI IGA [mission] data are searched at location of source "M16" [locstr]; size of search is 12.5 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI). Note, the XML output results of this example are discussed in the XML Output section below.

  14. IRIS (HTTP results)
    nph-atlas?mission=IRIS&locstr=M+31®Size=12.5&covers=on
    IRIS [mission] data are searched at location of source "M 31" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    IRIS (XML results)
    nph-atlas?mission=IRIS&locstr=M+31®Size=12.5&covers=on&mode=PI
    IRIS [mission] data are searched at location of source "M 31" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  15. IRTS (HTTP results)
    nph-atlas?mission=IRTS&locstr=47.09669+-1.71325+ga®Size=12.5&covers=on&searchregion=none&radius=2.0&radunits=deg
    IRTS [mission] data are searched at location "47.09669 -1.71325 ga" [locstr]; size of search is 12.5 [regSize] degrees; with searchregion turned off, radius of 2.0 degrees radunits is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    IRTS (XML results)
    nph-atlas?mission=IRTS&locstr=47.09669+-1.71325+ga®Size=12.5&covers=on&searchregion=none&radius=2.0&radunits=deg&mode=PI
    IRTS [mission] data are searched at location "47.09669 -1.71325 ga" [locstr]; size of search is 12.5 [regSize] degrees; with searchregion turned off, radius of 2.0 degrees radunits is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  16. ISSA (HTTP results)
    nph-atlas?mission=ISSA&locstr=NGC+4800®Size=12.5
    ISSA [mission] data are searched at location of source "NGC 4800" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is not set (HTTP output).

    ISSA (XML results)
    nph-atlas?mission=ISSA&locstr=NGC+4800®Size=12.5&mode=PI
    ISSA [mission] data are searched at location of source "NGC 4800" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is set to Program Interfer (PI).

  17. LGA (HTTP results)
    nph-atlas?mission=LGA&locstr=M81®Size=6.0
    LGA [mission] data are searched at location of source "M81" [locstr]; size of search is 6.0 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is not set (HTTP output).

    LGA (XML results)
    nph-atlas?mission=LGA&locstr=M81®Size=6.0&mode=PI
    LGA [mission] data are searched at location of source "M81" [locstr]; size of search is 6.0 [regSize] degrees; with covers turned off (not set), all images which fall anywhere within the regSize are returned; mode is set to Program Interfer (PI).

  18. LH (HTTP results)
    nph-atlas?mission=LH&locstr=159.738690+54.932062+eq+B1950®Size=159.738690+54.932062+eq+B1950&covers=on&radius=0.1&radunits=deg
    LH [mission] data are searched at location "159.738690 54.932062 eq B1950" [locstr]; size of search is 0.5 [regSize] degrees; with searchregion turned off (not set), radius of 0.1 degrees (radunits) is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    LH (XML results)
    nph-atlas?mission=LH&locstr=159.738690+54.932062+eq+B1950®Size=0.5&covers=on&radius=0.1&radunits=deg&mode=PI
    LH [mission] data are searched at location of source "159.738690 54.932062 eq B1950" [locstr]; size of search is 0.5 [regSize] degrees; with searchregion turned off (not set), radius of 0.1 degrees (radunits) is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  19. MIGA (HTTP results)
    nph-atlas?mission=MIGA&locstr=335.762875+59.146226®Size=12.5&covers=on
    MIGA [mission] data are searched at location of source "335.762875 59.146226" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    MIGA (XML results)
    nph-atlas?mission=MIGA&locstr=335.762875+59.146226®Size=12.5&covers=on&mode=PI MIGA [mission] data are searched at location of source "335.762875 59.146226" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  20. MIPSGAL (HTTP results)
    nph-atlas?mission=MIPSGAL&locstr=NGC+6631®Size=12.5&covers=on
    MIPSGAL [mission] data are searched at location of source "NGC 6631" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    MIPSGAL (XML results)
    nph-atlas?mission=MIPSGAL&locstr=NGC+6631®Size=12.5&covers=on&mode=PI
    MIPSGAL [mission] data are searched at location of source "NGC 6631" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  21. NExScI_PTI_KI (HTTP results)
    nph-atlas?mission=NExScI_PTI_KI&locstr=GLC388&radius=6.25&searchregion=none&radunits=deg
    NExScI_PTI_KI [mission] data are searched at location of source "GLC388" [locstr]; radius size of search is 6.25 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is not set (HTTP output).

    NExScI_PTI_KI (XML results)
    nph-atlas?mission=NExScI_PTI_KI&locstr=GLC388&radius=6.25&searchregion=none&radunits=deg&mode=PI
    NExScI_PTI_KI [mission] data are searched at location of source "GLC388" [locstr]; radius size of search is 6.25 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is set to Program Interfer (PI).

  22. MSX (HTTP results)
    nph-atlas?mission=MSX&locstr=46.5377+-0.2518+ga®Size=12.5&covers=on
    MSX [mission] data are searched at location "46.5377 -0.2518 ga" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    MSX (XML results)
    nph-atlas?mission=MSX&locstr=46.5377+-0.2518+ga®Size=12.5&covers=on&mode=PI MSX [mission] data are searched at location "46.5377 -0.2518 ga" [locstr]; size of search is 12.5 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  23. NED (HTTP results)
    nph-atlas?mission=NED&locstr=M52®Size=2.0&covers=none
    NED [mission] data are searched at location of source "M52" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned off, all images which fall anywhere within the regSize are returned; mode is not set (HTTP output).

    NED (XML results)
    nph-atlas?mission=NED&locstr=M52®Size=2.0&covers=none&mode=PI
    NED [mission] data are searched at location of source "M52" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned off, all images which fall anywhere within the regSize are returned; mode is set to Program Interfer (PI).

  24. SAGE (HTTP results)
    nph-atlas?mission=SAGE&locstr=NGC+2070®Size=2.0&covers=on
    SAGE [mission] data are searched at source location "NGC 2070" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on; mode is not set (HTTP output).

    SAGE (XML results)
    nph-atlas?mission=SAGE&locstr=NGC+2070®Size=2.0&covers=on&mode=PI
    SAGE [mission] data are searched at source location "NGC 2070" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on; mode is set to Program Interfer (PI).

  25. Scrapbook (HTTP results)
    nph-atlas?mission=Scrapbook&locstr=M18®Size=5.0&covers=on&searchregion=on
    Scrapbook [mission] data are searched at location of source "M18" [locstr]; size of search is 5.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    Scrapbook (XML results)
    nph-atlas?mission=Scrapbook&locstr=M18®Size=5.0&covers=on&searchregion=on&mode=PI Scrapbook [mission] data are searched at location of source "M18" [locstr]; size of search is 5.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  26. SINGS (HTTP results)
    nph-atlas?mission=SINGS&locstr=hoii®Size=3.0&covers=on&searchregion=on
    SINGS [mission] data are searched at location of source "hoii" [locstr]; size of search is 3.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SINGS (XML results)
    nph-atlas?mission=SINGS&locstr=hoii®Size=3.0&covers=on&searchregion=on&mode=PI SINGS [mission] data are searched at location of source "hoii" [locstr]; size of search is 3.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  27. SWIRE (HTTP results)
    nph-atlas?mission=SWIRE&locstr=ELAISR20+J163640%2B413132®Size=1.0&covers=on&searchregion=on
    SWIRE [mission] data are searched at location of source "ELAISR20 J163640+413132" [locstr]; size of search is 1.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SWIRE (XML results)
    nph-atlas?mission=SWIRE&locstr=ELAISR20+J163640%2B413132®Size=1.0&covers=on&searchregion=on&mode=PI
    SWIRE [mission] data are searched at location of source "ELAISR20 J163640+413132" [locstr]; size of search is 1.0 [regSize] degrees; with searchregion turned on, regSize/2.0 is used for the source search region; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  28. SWS (HTTP results)
    nph-atlas?mission=SWS&locstr=290.971773+11.774474+EQ&radius=5.0&searchregion=none&radunits=deg
    SWS [mission] data are searched at location "290.971773 11.774474 EQ" [locstr]; radius size of search is 5.0 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is not set (HTTP output).

    SWS (XML results)
    nph-atlas?mission=SWS&locstr=290.971773+11.774474+EQ&radius=5.0&searchregion=none&radunits=deg&mode=PI
    SWS [mission] data are searched at location of source "290.971773 11.774474 EQ" [locstr]; radius size of search is 5.0 [radius] degrees [radunits]; with searchregion turned off, regSize is ignored (not needed as input) and radius is used as the search size; mode is set to Program Interfer (PI).

  29. Taurus (HTTP results)
    nph-atlas?mission=Taurus&locstr=68.74+26.205+eq®Size=2.0&covers=on
    Taurus [mission] data are searched at location "68.74 26.205 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    Taurus (XML results)
    nph-atlas?mission=Taurus&locstr=68.74+26.205+eq®Size=2.0&covers=on&mode=PI
    Taurus [mission] data are searched at location "68.74 26.205 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  30. SASS (HTTP results)
    nph-atlas?mission=SASS&locstr=337.82+50.282+eq®Size=2.0&covers=on
    SASS [mission] data are searched at location "337.82 50.282 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SASS (XML results)
    nph-atlas?mission=SASS&locstr=337.82+50.282+eq®Size=2.0&covers=on&mode=PI
    SASS [mission] data are searched at location "337.82 50.282 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  31. SDWFS (HTTP results)
    nph-atlas?mission=SDWFS&locstr=216.88+32.147+eq®Size=2.0&covers=on
    SDWFS [mission] data are searched at location "216.88 32.147 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SDWFS (XML results)
    nph-atlas?mission=SDWFS&locstr=216.88+32.147+eq®Size=2.0&covers=on&mode=PI
    SDWFS [mission] data are searched at location "216.88 32.147 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  32. BLAST (HTTP results)
    nph-atlas?mission=BLAST&locstr=233.74+23.503+eq®Size=2.0&covers=on
    BLAST [mission] data are searched at location "233.74 23.503 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is not set (HTTP output).

    BLAST (XML results)
    nph-atlas?mission=BLAST&locstr=233.74+23.503+eq®Size=2.0&covers=on&mode=PI
    BLAST [mission] data are searched at location "233.74 23.503 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only images which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  33. 5MUSES (HTTP results)
    nph-atlas?mission=5MUSES&locstr=241.04+54.973+eq®Size=2.0&covers=on
    5MUSES [mission] data are searched at location "241.04 54.973 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is not set (HTTP output).

    5MUSES (XML results)
    nph-atlas?mission=5MUSES&locstr=241.04+54.973+eq®Size=2.0&covers=on&mode=PI
    5MUSES [mission] data are searched at location "241.04 54.973 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  34. SSGSS (HTTP results)
    nph-atlas?mission=SSGSS&locstr=160.34+58.894+eq®Size=2.0&covers=on
    SSGSS [mission] data are searched at location "160.34 58.894 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SSGSS (XML results)
    nph-atlas?mission=SSGSS&locstr=160.34+58.894+eq®Size=2.0&covers=on&mode=PI
    SSGSS [mission] data are searched at location "160.34 58.894 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  35. SpUDS (HTTP results)
    nph-atlas?mission=SpUDS&locstr=34.50+-5.000+eq®Size=2.0&covers=on
    SpUDS [mission] data are searched at location "34.50 -5.000 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SpUDS (XML results)
    nph-atlas?mission=SpUDS&locstr=34.50+-5.000+eq®Size=2.0&covers=on&mode=PI
    SpUDS [mission] data are searched at location "34.50 -5.000 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  36. SIMPLE (HTTP results)
    nph-atlas?mission=SIMPLE&locstr=53.33+-28.20+eq®Size=2.0&covers=on
    SIMPLE [mission] data are searched at location "53.33+-28.20 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is not set (HTTP output).

    SIMPLE (XML results)
    nph-atlas?mission=SIMPLE&locstr=53.33+-28.20+eq®Size=2.0&covers=on&mode=PI
    SIMPLE [mission] data are searched at location "53.33+-28.20 eq" [locstr]; size of search is 2.0 [regSize] degrees; with covers turned on, only spectra which directly overlap the coordinate are returned; mode is set to Program Interfer (PI).

  
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 two types of information: counts (e.g. how many Images were found) and links (URLs you can use to download data files from a temporary workspace). Some of these data files are 'wget' scripts provided as a convenience for people who want to use that mechanism for bulk data downloads.

Below we give example XML output for three of the use cases above. The first block is from Example 13 above (a normal return), the second is an example error return (using a bogus coordinate locstr value of "bla") and the third is an example of a notication that no sources were found for a valid position. 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 similar in layout with varying number of result images, catalog sources and spectra; when none are found the result tags are skipped.

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.

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

The structure of the XML file is straightforward and is fully illustrated by the above examples; we do not feel it necessary to provide formal 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
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 mission or data collection. All values of missions can be found in the Manadatory Search Parameters for Specific Data Collections section above.
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.