NED Simple Image Access (SIA) Service

  • Overview of the NED SIA interface for images
  • SIA query output information
  • Running program-friendly query
  • SIA query input parameters
  • Examples of queries with valid input
  • Examples of queries with invalid input

Overview of the NED SIA interface for images

NED is providing access to its image metadata archive (including links to data) using a IVAO Simple Image Access based service, based on the Simple Image Access protocol (SIA) Version 2.0 defined by the International Virtual Observatory Alliance (IVOA). The NED Image archive currently has over 2.5 million images and data-cubes in its holdings from over 500 literature references. This service provides an SIA program interface to discover images for a list of parameters (TARGET; POS (CIRCLE or RANGE); FACILITY (Telescope); ID/REFCODE; BAND; FOV; SPATRES; EXPTIME), from the NED image archive files that contain FITS compliant world-coordinate specifications. Results are returned in IVOA XML/VOTable format. The IVOA SIA protocol defines a query returning a list of the images in a VOTable formatted document. Briefly, NED's API discovers the images for a specified set of parameters, and return links to those images in VOTable formatted output from the query. This output can be parsed by a program or script.

SIA query output information

NED query results provide image metadata information, which includes the following, when available:
  • object/target name
  • reference code from literature
  • information about central wavelength in meters
  • coordinates of the target, image was produced for
  • resolution(FWHM) of the image in the arcseconds
  • exposure time in seconds
  • telescope/facility name
  • info about axis: naxis1, naxis2
  • field of view in degrees
  • field of view dimensions in arcminutes
  • size of the image in Kbytes
  • date
  • url to the location of the image
  • image Identifier
Query results by Target name (or any other parameter, or combination of) also return an IVOA "data access" url to retrieve the actual image. Note that some fields are specific to NED. Other metadata, required by the SIA standard, may not be available from NED. These are included with "null" values.

Running a program-friendly query

Any HTTP 1.1 compliant client can be used to submit a query and retrieve results. Note that results are always XML/VOTable, which are handled in browser/client-specific ways. Curl and wget are two such clients. An example using 'curl' is: curl -o NED-result.xml 'https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&MAXREC=10'

SIA query input parameters

1. The NED SIA service requires as input a value for at least one parameter:
  • TARGET or POS (They cannot be used together)
  • REFCODE/ID (Can be used alone or in the combination with one of the above)
TARGET is a recognized object name in the NED database. (M31, Messier 31, MESSIER 031) Examples of using POS parameter:
POS=CIRCLE 12 12 0.2 (RA DEC Radius- all in degrees)
POS=RANGE 12.1 12.5 34.0 34.6 (RA1 RA2 DEC1 DEC2 - all in degrees)
REFCODE/ID is bibcode/reference code used in NED's Database, value must be url encoded. Examples are (all valid refcodes to use for queries):
 1983MNRAS.205..787U
 1984A&A...135..213K
 1991AJ....101..127W
 1994ApJ...421L..23R
 1996JAD.....2....1d
 1996RMxAA..32...89G
 1999ApJS..124..285R
 2001MNRAS.325..385T
 2003AJ....125..525J
 2003MNRAS.346..333K
 2008AJ....136.1259R
 2010PASP..122.1397S
 2013MNRAS.432.1796A
 2015AJ....150...81W
The other 5 parameters: FACILITY, BAND, FOV, SPATRES, EXPTIME; can be used as additional filters with the main parameters described above. FACILITY is being used in NED as mostly telescope name. Examples of FACILITY:
2MASS
SDSS
Blanco
BLAST
CARMA
CTIO
Effelsberg
GALEX
Spitzer
VLA
WSRT
Here are the explanations how to use BAND, FOV, SPATRES, EXPTIME:
Between:  Value1 Value2 (0.205 0.215)
Longer/Bigger/Lower-Bound: Value +Inf (0.02 +Inf)
Shorter/Smaller/Upper-Bound: -Inf Value (-Inf 0.02)
Exact Match: Value (0.21)

2. If queried with MAXREC=0, the service will return only the data description for SIA service response, with no data. (See example below.)

3. NED adds the parameter FIRSTREC, to specify how many records to skip before beginning the list. https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&FIRSTREC=0&MAXREC=25&BAND=-Inf%200.000000654&REFCODE=2006AJ....131.2478M Returns the first 25 image records for MESSIER 31, beginning with number 1, where BAND is less than 0.000000654 (6.54e-07), from REFCODE 2006AJ....131.2478M. 4. Supported Parameters: The NED SIA service also supports COLLECTION, and CALIB constrained queries. However NED has only one collection "NED/Images", and only has Images for which CALIB=1, FORMAT parameter in this version is set to (applications/x-fits). Queries constrainted to other values will return no images. 5. Unsupported SIA parameters: POL, INSTRUMENT, DPTYPE, TIMERES, SPECTRP, FORMAT are NOT supported.

Examples of queries with valid input

1. Get metadata for all images for object m31 (which is 'MESSIER 031') in NED: https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31 2. Query to get the first 10 images from archive for m31 ('MESSIER 031' object): https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&MAXREC=10 3. Example of query to get only descriptive data, describing fields in the SIA response: https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&MAXREC=0 NOTE: Parameter "MAXREC" set to the value=0, the query will retrieve only descriptive information, even if the TARGET parameter has valid name in it or other parameters added. 4. Example of query to get first 100 images for the cone search around 14(RA) 15(DEC) 5(Radius): https://vo.ned.ipac.caltech.edu/services/sia?MAXREC=100&pos=CIRCLE%2014%2015%205 5. Example of query to get images for the same search, but restrict the search by adding refcode=1991AJ....102..537L: https://vo.ned.ipac.caltech.edu/services/sia?MAXREC=100&pos=CIRCLE%2014%2015%205&ID=1991AJ....102..537L NOTE: Parameters "ID" and "REFCODE" are aliases, with the same meaning in NED. 6. Example of query to get images for REFCODE=2001ApJS..132..129M: https://vo.ned.ipac.caltech.edu/services/sia?refcode=2001ApJS..132..129M 7. Example of query to get image for NGC 3837 from REFCODE=2001ApJS..132..129M: https://vo.ned.ipac.caltech.edu/services/sia?target=n3837&refcode=2001ApJS..132..129M 8. Example of query to get all images for the range: 13 14 14 15 with FOV smaller than 1 degree and BAND smaller than 7.0e-07: https://vo.ned.ipac.caltech.edu/services/sia?pos=RANGE%2013%2014%2014%2015&fov=-Inf%201&Band=-Inf%200.0000007 9. The same as above, plus only the images associated with REFCODE=2007ApJS..173..185G: https://vo.ned.ipac.caltech.edu/services/sia?pos=RANGE%2013%2014%2014%2015&fov=-Inf%201&Band=-Inf%200.0000007&refcode=2007ApJS..173..185G 10. The same range, but extract the data for SDSS Facility/Telescopes: https://vo.ned.ipac.caltech.edu/services/sia?pos=RANGE%2013%2014%2014%2015&Facility=SDSS

Examples of queries with invalid input

1. Example with TARGET name unknown to NED: https://vo.ned.ipac.caltech.edu/services/sia?TARGET=3c Response:
<INFO name="QUERY_STATUS" value="ERROR">
UsageFault: invalid TARGET name.
</INFO>
2. Example with No TARGET name provided: https://vo.ned.ipac.caltech.edu/services/sia?TARGET= Response:
<INFO name="QUERY_STATUS" value="ERROR">
UsageFault:  String Empty.
Missing required key constraint
</INFO>
3. Example of a query using unsupported parameters: https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&MAXREC=10&POL=1 Response:
<INFO name="QUERY_STATUS" value="ERROR">
UsageFault: The following unsupported constraints were specified:
Keyword POL unsupported.
 Some parameters are invalid
</INFO>
4. Example of a query using TARGET and POS parameters, which is not allowed: https://vo.ned.ipac.caltech.edu/services/sia?TARGET=m31&POS=RANGE%2012%2013%2013%2014 Response:
<INFO name="QUERY_STATUS" value="ERROR">
UsageFault: Too many key constraints supplied
</INFO>

References

  1. Patrick Dowler, Doug Tody, Françs Bonnarel, IVOA Simple Image Access. Version 2.0, IVOA Recommendation 2015-12-23, https://www.ivoa.net/documents/SIA/20151223/REC-SIA-2.0-20151223.pdf
  2. Patrick Dowler, Markus Demleitner, Mark Taylor, Doug Tody, Data Access Layer Interface Version 1.0 IVOA Recommendation 29 November 2013, https://www.ivoa.net/documents/DALI/20131129/REC-DALI-1.0-20131129.pdf
  3. Matthew Graham, Guy Rixon. IVOA Support Interfaces Version 1.0 IVOA Recommendation 31 May 2011 https://www.ivoa.net/documents/VOSI/20110531/REC-VOSI-1.0-20110531.pdf
  4. Doug Tody (NRAO) Ray Plante (NCSA) Simple Image Access Specification Version 1.0 IVOA Recommendation 11 November 2009 https://www.ivoa.net/Documents/SIA/20091116/REC-SIA-1.0.pdf
  5. Francois Ochsenbein, Roy Williams, Clive Davenhall, Markus Demleitner, Daniel Durand, Pierre Fernique, David Giaretta, Robert Hanisch, Tom McGlynn, Alex Szalay, Mark Taylor, Andreas Wicenec VOTable Format Definition Version 1.3 IVOA Recommendation 20 September 2013 https://www.ivoa.net/documents/VOTable/20130920/REC-VOTable-1.3-20130920.pdf
  6. Mireille Louys, Francois Bonnarel, David Schade, Patrick Dowler, Alberto Micol, Daniel Durand, Doug Tody, Laurent Michel, Jesus Salgado, Igor Chilingarian, Bruno Rino, Juan de Dios Santander, Petr Skoda, Observation Data Model Core Components and its Implementation in the Table Access Protocol Version 1.0 IVOA Recommendation 28 October 2011, https://www.ivoa.net/documents/ObsCore/20111028/REC-ObsCore-v1.0-20111028.pdf
  7. Patrick Dowler, Françs Bonnarel, Laurent Michel, Markus Demleitner, VOA DataLink Version 1.0 IVOA Recommendation 17 June 2015, https://www.ivoa.net/documents/DataLink/20150617/REC-DataLink-1.0-20150617.pdf