Background Model: Program Interface

Introduction   Input Parameters   Examples   XML Output   Description of XML Tags

Back to Main page.


The Background Model can be accessed via an HTTP GET program interface for a single request. Returned is an XML document containing the results: estimates of the infrared background from different components. (Table upload is not an option in the program interface since one can simply program single requests in a loop.)

The following shows a typical query,



  • Base URL for the service is


  • Input parameters are specified by standard parameter/value pairs. See table below.

  • Output is an XML document containing the background estimates.

From the command-line, you can use the commonly available curl or wget commands.

curl -o out.xml "https://irsa.ipac.caltech.edu/cgi-bin/BackgroundModel/nph-bgmodel?locstr=m51&wavelength=2.0&year=2019&day=180&obslocin=0&ido_viewin=0"

wget -O out.xml "https://irsa.ipac.caltech.edu/cgi-bin/BackgroundModel/nph-bgmodel?locstr=m51&wavelength=2.0&year=2019&day=180&obslocin=0&ido_viewin=0"

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 Range Description
locstr (locstr examples) NA If the input is a recognizable object name, it will be resolved into coordinates using NED or, if that fails, SIMBAD (required).
wavelength float 0.5-1000.0 Wavelength in microns (defaults to 2.0).
year char varies Year. Limited to 2018 to 2029 for L2 position. Defaults to 2019.
day char 1-366 Day. Limited to 2018 Day 274 to 2029 Day 120 for L2 position and ido_viewin=0. Defaults to 180.
obslocin char 0 or 3 Observing location. 0 is Earth-Sun L2 region; 3 is Earth (defaults to 0).
obsverin char 1 or 4 Code version (optional, defaults to 4).
ido_viewin char 0 or 1 0 = find zodiacal on Day; 1 = find median zodiacal over a likely viewing range (defaults to 1, see Help).


Note: The following examples can be run through a browser by clicking their links; examples 1-2 produce valid results while 3 is an error. You can get the XML file directly using a "wget" or "curl" request (see above).

  1. nph-bgmodel?locstr=m51&wavelength=2.0&year=2019&day=180&obslocin=0&ido_viewin=0
    Generates background estimates for the sky toward object "m51". (see the output from Example 1 in XML Output below).

  2. nph-bgmodel?locstr=266.0+-60.+equ+j2000&wavelength=2.0&year=2019&day=180&obslocin=0&ido_viewin=0
    Generates background model estimates centered on coordinate "266.0 -60. equ j2000".

  3. nph-bgmodel?wavelength=2.0&year=2019&day=180&obslocin=0&ido_viewin=0
    The input location of this query is unresolvable, it produces the error condition: "Required input [location] is missing."

XML Output

Normally, when you run a web application the return is HTML text which is rendered in a browser. 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.

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 3). The XML tags for the data values are given below.

Output from Example 1:

    <?xml version="1.0"?>
    <results status="ok">
        <objname>202.484170 47.230560 equ J2000</objname>
        <wavelength>2.0 microns</wavelength>
        <desc>Background Model Estimates</desc>
          <zody>0.126087 (MJy/sr)</zody>
          <ism>0.002024 (MJy/sr)</ism>
          <stars>0.118022 (MJy/sr)</stars>
          <cib>0.006865 (MJy/sr)</cib>
          <totbg>0.252997 (MJy/sr)</totbg>
          <refCoordinate>202.484170 47.230560 equ J2000</refCoordinate>

Output from Example 3:

    <results status="error">
      ERROR: required input [location] is missing.

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 successful, "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).
wavelength Wavelength in microns.
year Year.
day Day (1-366), or -999 if viewing range was selected.
selon Solar elongation (0-180 deg), or -999 if viewing range was selected.
obsloc Observer's location. 0 = Earth-Sun L2; 3 = Earth.
obsver Code version.
result Results.
desc Background Model Estimates.
statistics Model estimates.
zody Zodiacal light background (MJy/sr).
ism Interstellar medium background (MJy/sr).
stars Stellar background (MJy/sr).
cib Cosmic infrared background (MJy/sr).
totbg Total background (MJy/sr).
refCoordinate The input coordinates.

Back to Main page.