Contents of page/chapter:
+Overview
+Quick Start
+Constructing a Catalog Search Query
+Objstr Keyword
+Query URL Examples
+Moving Objects
IRSA offers program-friendly interfaces to all of its catalogs. Through an application program interface (API), users can access IRSA catalogs directly (within a script or on the command line) without the need to go through interactive web pages.
IRSA offers three APIs for searching catalogs.
SCS is a VO-compliant method of searching catalogs for sources that
lie within a specified radius of any position on the sky. The output
can be VO Table ,
IPAC Table , comma-separated values (CSV) table, tab-separated
values table, or FITS table. The ability to upload a list of sources
positions is not supported. Users interested in table upload
functionality should use the TAP protocol (below).
TAP is a VO-compliant method of searching catalogs. TAP allows cone, box, polygon, and multi-position searches with optional SQL constraints, a variety of output formats, and the option of selecting output columns.
IRSA Catalog Search API
This is an older API that does not conform to VO standards and is maintained for historical reasons. New users should choose from either of the two protocols above.
The rest of this page describes this API.
The output can be HTML, VO table
, IPAC table file (ASCII text with a certain format), Extensible Markup
Language (XML), or a simple SVC (software handshaking structure)
message. It also provides the option of selecting output columns.
Some catalogs are equipped with a moving object search capability; see
Moving Objects below.
curl -o irsa_catalogs.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-scan?mode=ascii"Examining the 'description' and 'catname' columns of this file, we find that the AllWISE Source Catalog has a cat name of "allwise_p3as_psd".
. The full table download is difficult for a human to parse.
Examining the output, the basic photometry is in the columns w1mpro, w2mpro, w3mpro, and w4mpro.
The general format for the Catalog Search Service query URL is:
https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?[keyword1=value1]&[keyword2=value2]&...[keywordn=valuen]
Note especially that setting the 'spatial' field to "No Spatial Constraints" will search the entire catalog, and additional constraints should be placed on the query. Users are cautioned to use this feature wisely as very large result tables are possible.
Input keywords:
| Keyword | Required? | Description | Values |
| catalog | required | Catalog name in IRSA's database | Query for catalog names |
| spatial | required | Type of query |
cone box polygon Upload (see example below) None (= All-sky search) |
| objstr | required when spatial=cone or box |
Target name or coordinates of spatial search center | |
| radius | optional if spatial=cone, otherwise ignored |
Cone search radius in units of radunits | Limit varies; default=10 arcsec |
| radunits | optional if spatial=Cone, otherwise ignored |
Units of Cone search radius | arcsec, arcmin, deg; default = arcsec |
| posang | optional | Position angle (E of N) in deg of semi-major access of elliptical cone | 0-180 deg; default=0 |
| ratio | optional | Semi-minor/semi-major axis ratio of elliptical cone | <=1.0; default=1.0 |
| uradius uradunits uposang uration |
optional | As above for table upload. | NOTE: Absence of a value for uradius will lead it to use values of radius ("major") from table. |
| size | required when spatial=box | Width of box in arcsec | Limit varies |
| polygon | required if spatial=polygon | Vertices of an irregular, convex (interior
angles < 180 degrees) polygon within which to search.
Up to 15 vertices may be specified. Each vertex is given as a space-separated RA Dec pair. For the program interface, the space must be URL encoded as "+" (plus sign). The coordinates must be in decimal degrees, J2000. Each vertex must be separated by a comma. You do not need to repeat the first vertex. |
|
| outfmt | optional | Output format |
0: HTML (default) 1: ASCII table 2: SVC (software handshaking structure) message 3: VO Table 6: XML |
| constraints | optional | SQL query constraints | |
| selcols | optional | Comma-separated list of output columns desired | Query for available columns |
| one_to_one | optional | If nonzero, then a one-to-one match will be performed | |
| order | optional | Column by which to order results | |
| outrows | optional | Maximum number of rows to return | |
| mailcheck | optional | Send email upon completion. | use this combination to have it email you upon completion: &mailcheck=Send+email&email=your_email |
An optional keyword is objstr, which specifies the search center for a cone or box spatial search. The keyword objstr is a string that specifies either the target name (as resolved by SIMBAD or NED) or the coordinates of the spatial search center.
This string must be URL encoded. URL encoding replaces unsafe ASCII characters with a percent sign ("%") followed by two hexadecimal digits. See the table below for a list of commonly used values that need to be URL encoded.
URL Encoding for Commonly Used Characters| Character | URL encoding |
| Plus ("+") | %2B |
| Comma (",") | %2C |
| Forward slash ("/") | %2F |
| Colon (":") | %3A |
| Semi-colon (";") | %3B |
| Equals ("=") | %3D |
| Question mark ("?") | %3F |
| Space (" ") | %20 or + |
| Quotation marks (") | %22 |
| Less than ("<") | %3C |
| Greater than (">") | %3E |
| Percent ("%") | %25 |
Examples
https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?catalog=slphotdr4&spatial=polygon&polygon=148.87+69.8,148.87+69.9,148.90+69.9&outfmt=6&selcols=ra,dec,M1_F_PSF,M1_dF_PSF
Some IRSA catalogs allow queries on moving objects. The query calculates the object's ephemeris to determine positions (and times) within the data, and does a cone search around those positions. Below is an example: a search by object name (324 Bamberga) over the entire time range of the WISE All-Sky Single Exposure (L1b) Source Table with output in an IPAC ASCII table. (For the larger merged NEOWISE catalogs, it is best to restrict the time range.):
curl -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?outfmt=1&searchForm=MO&spatial=cone&catalog=allsky_4band_p1bs_psd&moradius=5&mobj=smo&mobjstr=324"
Note that "mobjstr" is the asteroid number in this case; the name Bamberga would also work. It can also search for a comet using its numeric designation. For example, periodic comet P/29 Schwassmann-Wachmann 1 can be called 29P or P/29 (but not P29). For non-periodic comets, use for example C/2010+N1, where the "+" is shorthand for a space for URL encoding. Planetary satellites (or planets, where available in the dataset) are searchable by name, e.g. Titan.
There can be name ambiguities. For example, entering "WISE" is a
problem as there were many asteroids and comets discovered by
the WISE mission. Entering "Neptune" is unclear as there are
ephemeris files for both Neptune and the Neptune system
barycenter. Gator will deliver a messsage if there is an
ambiguity. This will be via a link to a log file. The
message will contain suggested NAIF
ID's, and you can use them as follows, e.g. "1003094:NID" for
comet 317P/WISE or "899:NID" for Neptune. In a few cases,
there are satellites and asteroids with the same name, and you
may distinguish them by, e.g. "Europa:SAT" and
"Europa:AST".
It is also possible to input objects in Minor Planet Circular (MPC) format, or by orbital elements, see the Solar System Object page and the examples below. But object name/number input is best, as it will query JPL Horizons to get the osculating orbital elements closest in time to the observations.
The general format for the Moving Object query URL is:
https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?searchForm=MO&spatial=cone&[keyword1=value1]&[keyword2=value2]&...[keywordn=valuen]
Adjustable keywords:
| Keyword | Required? | Description | Values |
| catalog | required | Catalog name. NOTE: Catalog needs to be moving-object search enabled. |
Current moving-object enabled catalogs: All-Sky: allsky_4band_p1bs_psd WISE 3band: allsky_3band_p1bs_psd WISE 2band: allsky_2band_p1bs_psd NEOWISE-R: neowiser_p1bs_psd |
| moradius | optional | Cone search radius (arcsec) | default=10 arcsec |
| mobj | required | Type of input | smo = by name or number mpc = MPC format obt = orbital elements |
| mobjstr | required for object input | Name or numeric designation of object (see above) |
e.g. "324" or "Bamberga" (asteroid) or "29P" (comet) |
| mobjtype | required for MPC or orbital elements input |
Solar-system object type | Asteroid or Comet |
| mpc | required for MPC input | MPC string | See Moving Object page or examples below. |
| mobjmaj/perih_dist | required for orbital elements input |
Semi-major axis (asteroid) or perihelion distance (comet) in AU |
>0 |
| mobjecc | required for orbital elements input |
Eccentricity of orbit | 0.0-1.0 |
| mobjinc | required for orbital elements input |
Inclination of orbit (deg) | 0.0-180.0 |
| mobjper | required for orbital elements input |
Argument of perihelion (deg) | 0.0-360.0 |
| mobjasc | required for orbital elements input |
Longitude of ascending node (deg) | 0.0-360.0 |
| mobjanom/perih_time | required for orbital elements input |
Mean anomaly (asteroid) in deg, or perihelion time (comet) in yyyy+mm+dd+hh:mm:ss |
0.0-360.0 for mean anomaly |
| mobjdsg | required for orbital elements input |
Designation for returned ephemeris | e.g. Bamberga |
| mobjepo | required for orbital elements input |
Epoch of coordinates in MJD (Modified Julian Date) |
e.g. 55203.0 for start of WISE mission |
| btime | optional | Earliest observation date (UT) to include | yyyy+mm+dd+hh:mm:ss |
| etime | optional | Latest observation date (UT) to include | yyyy+mm+dd+hh:mm:ss |
| outfmt | optional | Output format |
0: HTML (default) 1: ASCII table 2: SVC (software handshaking structure) message 3: VO Table 6: XML output |
| selcols | optional | Comma-separated list of output columns desired |
Query for available columns |
| outrows | optional | Maximum number of rows to return |
Asteroid:
Example with MPC input at time of WISE 4-band observation of Bamberga:
curl -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?searchForm=MO&spatial=cone&catalog=allsky_4band_p1bs_psd&moradius=5&mobj=mpc&mobjtype=Asteroid&outfmt=1&mpc=00324+6.82+0.09+K103I+64.7389713+43.9047086+
327.9898280+11.1080776+0.33709263+0.2240550+2.684723515+0+MPO344295+2289+63+
1892-2015+0.50+M-v+38h+MPCLINUX+0000+(324)+Bamberga+20150614"
Example with orbital elements at time of WISE 4-band observation of Bamberga:
curl -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?searchForm=MO&spatial=cone&catalog=allsky_4band_p1bs_psd&moradius=5&mobj=obt&outfmt=1&mobjtype=Asteroid&mobjanom=64.7389713&mobjper=43.9047086&mobjasc=327.9898280&mobjinc=11.1080776&mobjecc=0.33709263&mobjmaj=2.684723515&mobjepo=55273.0&mobjdsg=Bamberga"
Comet:
Example with MPC input at time of WISE 4-band observation for comet P/2010 N1 (WISE):
curl -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?searchForm=MO&spatial=cone&catalog=allsky_4band_p1bs_psd&moradius=5&mobj=mpc&mobjtype=Comet&outfmt=1&mpc=PK10N010+2010+08+16.1477+1.494525+0.533798+
153.4910+113.2118+12.8762+20100621+17.0+4.0+
P/2010+N1+(WISE)+MPC+75712"
Example with orbital elements at time of WISE 4-band observation for comet P/2010 N1 (WISE) :
curl -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?searchForm=MO&spatial=cone&catalog=allsky_4band_p1bs_psd&moradius=5&mobj=obt&outfmt=1&mobjtype=Comet&perih_time=2455424.64772&mobjper=153.49099443&mobjasc=113.21175889&mobjinc=12.87619139&mobjecc=0.53379824&perih_dist=1.49452503&mobjepo=55368.0&mobjdsg=P/2010+N1+(WISE)"