Background Model: Program Interface
Introduction Input Parameters Examples XML Output Description of XML Tags
Back to Main page.
Introduction
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,
where:
Base URL for the service is
https://irsa.ipac.caltech.edu/cgi-bin/BackgroundModel/nph-bgmodel-
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.
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). |
Examples
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).-
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). -
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". -
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">
<input>
<objname>202.484170 47.230560 equ J2000</objname>
<wavelength>2.0 microns</wavelength>
<year>2019</year>
<day>180</day>
<selon>83</selon>
<obslocin>0</obslocin>
<obsverin>4</obsverin>
<idoview_in>0</ido_viewin>
</input>
<result>
<desc>Background Model Estimates</desc>
<statistics>
<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>
</statistics>
</result>
</results>
Output from Example 3:
<results status="error">
<message>
ERROR: required input [location] is missing.
</message>
</results>
| 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.
The Euclid NASA Science Center is located within the Infrared Processing and Analysis Center, located on the campus of the California Institute of Technology.