IRSA Catalog Search Service
Application Program Interface (API)

  1. Overview
  2. Quick Start
  3. Constructing a Catalog Search Query
  4. Examples
  5. Moving Objects

Overview

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. This page describes the IRSA Catalog Search Service, which offers cone, box, polygon, all-sky, and multi-position table upload searches. The output can be HTML, VO table, ASCII table in IPAC table 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.

The other two APIs are part of the Virtual Observatory (VO) standards. Users familiar with the VO and not requiring advanced query features may be interested in using the Simple Cone Search API. Also available is the more powerful Table Access Protocol (TAP) interface.

Users brand new to searching IRSA's catalogs on the command line may consult this Step-by-Step Guide.

Quick Start

 IRSA's Catalog Search Tool API consists of three services.
  • Catalog Search Service - This service returns the rows from a given catalog that meet spatial or other constraints set by the user. The bulk of this page describes this service.
  • Catalog List Service - This service returns a list of catalogs held at IRSA in either XML or HTML format.
  • Catalog Data Dictionary Form Service - This service returns information about the columns in a given catalog.

The following example uses each of these three services:

Search the AllWISE Source Catalog for all objects within 300 arcsec of the position ra = 00h 42m 44.32s, dec = 41d 16m 08.5s. Return only a subset of the photometric measurements in an ASCII table.

1. Get a list of all public catalogs in IPAC Table format:

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

2. Get a list of the available columns in the AllWISE Source Catalog:

The following URL can be typed right into a browser window, and will result in a nicely formatted table containing the columns and their descriptions. Alternatively, this URL could be embedded in a wget or curl command to download an XML version.

https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-dd?mode=html&catalog=allwise_p3as_psd

Examining the output, the basic photometry is in the columns w1mpro, w2mpro, w3mpro, and w4mpro.

3. Execute the search.

  • curl -o search_results.tbl "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?catalog=allwise_p3as_psd&spatial=cone&radius=300&radunits=arcsec&objstr=00h+42m+44.32s+41d+16m+08.5s&size=300&outfmt=1&selcols=ra,dec,w1mpro,w2mpro,w3mpro,w4mpro"

Constructing a Catalog Search Service Query URL

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]

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
mailcheck optional Send e-mail when job is finished Send+email
email optional Your e-mail address
outrows optional Maximum number of rows to return

Query URL Examples
  1. Search the 2MASS Point Source Catalog for all objects within 300 arcsec of M31. Return the result in HTML format.

    • https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?spatial=cone&catalog=fp_psc&objstr=M31&radius=300&radunits=arcsec&outfmt=0


  2. Search the AllWISE Source Catalog for all objects within a 300 arcsec wide box centered on the position ra = 00h 42m 44.32s, dec = 41d 16m 08.5s. Return the results as an ASCII table.

    • https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?spatial=box&catalog=allwise_p3as_psd&objstr=00h+42m+44.32s+41d+16m+08.5s&size=300&outfmt=1


  3. Search the Spitzer Enhanced Imaging Products Source List for all objects within the polygon with corners described by the following coordinates. Return the results as a program interface xML, and only return the MIPS 24 micron PSF fit flux density and error.

    4. (ra1 dec1) = (148.87 69.8)
    (ra2 dec2) = (148.87 69.9)
    (ra3 dec3) = (148.90 69.9)

    • 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


  4. Search the COSMOS Cassata Morphology Catalog v1.1 for the nearest match within 2 arcsec for each object listed in the IPAC Table cosmos_example.tbl. Return the otuput as an IPAC Table.

    • curl -F filename=@cosmos_example.tbl \
      -F catalog=cosmos_morph_cassata_1_1 \
      -F spatial=Upload \
      -F uradius=2 \
      -F outfmt=1 \
      "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query" \
      -o cosmos_output.tbl


  5. Search the entire HERITAGE LMC PACS 100 micron Catalog all-sky search for objects with flux > 0. Order the output by flux, and only return the first 7 rows as an ASCII table.

    • https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?catalog=heritagel100&spatial=None&outfmt=1&order=flux&outrows=7&constraints=flux%3E0


  6. Upload a table to the AllWISE Source Catalog and receive e-mail when the query is done. This can be used to get results even if the query would normally lead to a connection timeout.

    • curl -o out_message -F filename=@example.tbl -F catalog=allwise_p3as_psd -F spatial=Upload -F uradius=5 -F outfmt=1 -F mailcheck=Send+email -F email=you@youraddress.edu "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query"

    • If not uploading a table, a call to the same catalog for 3.4 micron magnitudes between 12.0 and 12.005 would be:

    • curl -o out_message "https://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-query?catalog=allwise_p3as_psd&outfmt=1&spatial=None&constraints=w1mpro%3E12.000+and+w1mpro%3C12.005&mailcheck=Send+email&email=you@youraddress.edu"

Moving Objects

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 Gator Moving Object help 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 Gator Moving Object help 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)"