Search with the VO
The Virtual Observatory (VO) is the concept that astronomical research should be able to seamlessly incorporate data from active missions, archives, and other institutional resources worldwide. Many projects and data centers collaborate toward this goal. MAST has been involved in the IVOA (International Virtual Observatory Alliance) community since its inception, and is dedicated to sharing our holdings in VO-compatible ways. Many MAST catalogs, images, spectra, and even raw database tables are available through VO standard services, described below. MAST also provides a service registry, listing VO services worldwide that can be correlated with our own holdings.
-
Search the Virtual Observatory in the Portal
In drop down, select "all virtual observatory collections" to search for MAST data using the Virtual Observatory. Using the VO, you can access data from not just MAST, but other archives at universities and data centers worldwide. Search MAST along with Spitzer, IPAC, Chandra, WISE, ADS, HEASARC, CDS, and many others.
Catalogs
Simple Cone Search (SCS) is an International Virtual Observatory Alliance (IVOA) protocol defining a web service for querying catalogs of astronomical entities that have well-defined positions on the sky. The query describes sky position and an angular distance, defining a cone on the sky. The query results are a list of the astronomical entities whose position overlaps the given cone. The formal IVOA document describing the SCS protocol is here: http://www.ivoa.net/documents/latest/ConeSearch.html
Once we have a source catalog available for JWST, we will implement an SCS service to access that catalog. For now, we will instead implement the SCS service to access the catalog of JWST observations. Each result will represent a JWST observation that overlaps the search cone, and will contain a variety of metadata about the observation.
Following is a description of information for how to call SCS services, and the main ones available at MAST. Many more are available through searching the registry.
Accordion
-
The supported input parameters are:
- RA – Required
A right-ascension in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees. - DEC – Required
A declination in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees. - SR – Required
The radius of the cone to search, given in decimal degrees. - VERB – Optional
May be either 1, 2 or 3. Suggests to the service how many result columns the service should have, where 1 is minimum number of columns and 3 is a maximum number of columns. Since there are not that many columns in this catalog, this service will always return the same number of columns.
- RA – Required
-
MISSION & SERVICE INFO BASE URL SAMPLE CONE SEARCH Kepler Planets http://archive.stsci.edu/kepler/confirmed_planets/search.php? RA: 285.67943Dec: 50.24132Radius: 1.0 degKOI http://archive.stsci.edu/kepler/koi/search.php? RA: 285.67943Dec: 50.24132Radius: 1.0 degHSC Summary http://archive.stsci.edu/hst/hsc_sum/search.php? RA: 210.80227Dec: 54.34895Radius: 0.001 degHSC Detailed http://archive.stsci.edu/hst/hsc/search.php? RA: 210.80227Dec: 54.34895Radius: 0.001 degTIC http://gsss.stsci.edu/webservices/vo/ConeSearch.aspx?CAT=TESSINPUT& RA: 210.80227Dec: 54.34895Radius: 0.001 deg -
A successful VOTable result will contain the FIELDs (columns) described below. FIELDs have metadata attributes that describe the content of the FIELD, including the IVOA metadata concepts of Universal Content Descriptors (UCDs) and Universal Type Descriptors (UTypes). UCDs and UTypes will be supplied for columns only when they are somewhat well-defined by IVOA standards.
Result field (column) names vary from collection to collection, but the RA, Dec and ID columns are uniquely identified by Universal Content Descriptor (UCD).
UCD DESCRIPTION ID_MAIN Unique identifier of the result object POS_EQ_RA_MAIN Right Ascension of the result object POS_EQ_DEC_MAIN Declination of the result object
Images
Simple Image Access (SIA), is an International Virtual Observatory Alliance (IVOA) protocol defining a web service for querying for image products. The query describes sky position and an angular distance, defining a cone on the sky. The query results are a list of the images whose footprint overlaps the given cone. The formal IVOA document describing the SIA protocol (version 1.0, as supported at MAST) is here: http://www.ivoa.net/documents/SIA/20091116/
Following is a description of information for how to call SIA services, and the main ones available at MAST. Many more are available through searching the registry.
Accordion
-
• POS (Required) - The position of the region of interest, expressed as the right-ascension and declination of the field center, in decimal degrees using the ICRS coordinate system. A comma should delimit the two values; embedded whitespace is not permitted. Example: "POS=12.821,-33.4".
• SIZE (Optional) - The coordinate angular size of the region given in decimal degrees. The region may be specified using either one or two values. If only one value is given it applies to both coordinate axes. If two values are given the first value is the angular width in degrees of the right-ascension axis of the region, and the second value is the angular width in degrees of the declination axis. Note that the angular width along the right-ascension axis is not the coordinate width of the region in right-ascension, which is equal to the coordinate angular width multiplied by cos(DEC). If not specified, the size defaults to 0.
• FORMAT (Optional) - Specifies the types of image products that are desired. Only images of the type requested will be returned. The parameter value is a comma-separated list of format types (image/jpg, image/jpeg, image/png, image/fits are recognized) or one of these special values:
• ALL – Denotes all formats supported by the service.
• GRAPHIC – Denotes any of the following graphics formats: JPEG, PNG, GIF. These are types typically supported "in-line" by web-browsers.
• METADATA – Denotes a Metadata Query: no images are requested; only metadata should be returned.
-
HLA http://hla.stsci.edu/cgi-bin/hlaSIAP.cgi?imagetype=best&inst=ACS,ACSGrism,WFC3,WFPC2,NICMOS,NICGRISM,COS,STIS,FOS,GHRS&proprietary=false& POS: 210.80227,54.348950SIZE: 0.24 degGALEX http://mast.stsci.edu/portal/Mashup/VoQuery.asmx/SiaV1?MISSION=GALEX& POS: 210.802,54.349SIZE: 0.15 degCANDELS (HLSP) http://archive.stsci.edu/siap/search.php?id=candels& POS: 189.25684,62.50686950SIZE: 0.24 deg -
All successful responses by the service will be in the form of a VOTable. The IVOA specification for VO Table is here: http://www.ivoa.net/documents/VOTable/20130920/. Sections 7.1 and 7.2 have good summary pictures of the grammar.
The successful VOTable result will contain exactly one RESOURCE which will contain exactly one TABLE. The TABLE will have FIELDs (columns) as defined in the next section, with each row representing a single image product.
Controlled error responses, such as those resulting from invalid input parameters, will also be in VOTables. -
A successful VOTable result will contain the FIELDs (columns) described below. FIELDs have metadata attributes that describe the content of the FIELD, sometimes including Universal Content Descriptors (UCDs).
When present, the FIELD's ucd attribute determines the meaning of the field (see table below).
UCD DESCRIPTION ID_DATASET Collection name POS_EQ_RA_MAIN Right Ascension of image center POS_EQ_DEC_MAIN Declination of image center INSTR_DET Name of the instrument that produced the data VOX:Image_AccessReference URL to download the image product VOX:Image_FileSize Size of the image product in bytes VOX:Image_Naxes Number of image axes VOX:Image_Naxis Array of length in pixels of each image axis VOX:Image_Scale Array of image scale for each image axis VOX:Image_Format Mime type of the image product VOX:STC_CoordRefFrame Coordinate Frame VOX:WCS_CoordProjection Projection VOX:WCS_CoordRefPixel Pixel coordinates of the reference pixel VOX:WCS_CoordRefPixel World coordinates of the reference pixel VOX:WCS_CDMatrix CD matrix that defines the scale and rotation of the image VOX:BandPass_ID Bandpass VOX:BandPass_Unit Units for spectral values
Spectra
Simple Spectral Access (SSA), version 1.03, is an International Virtual Observatory Alliance (IVOA) protocol defining a web service for querying for spectral data products. The query describes sky position and an angular distance, defining a cone on the sky, and also allows constraining the search by waveband and time range. The query results are a list of the products whose footprint overlaps the given cone and/or match the specified waveband or time ranges. The formal IVOA document describing the SSA protocol is here: http://www.ivoa.net/documents/cover/SSA-20071220.html
Following is a description of information for how to call SSA services, and the main ones available at MAST. Many more are available through searching the registry.
Accordion
-
The supported input parameters are:
- POS – Required
The position of the region of interest, expressed as the right-ascension and declination of the field center, in decimal degrees using the ICRS coordinate system. A comma should delimit the two values; embedded whitespace is not permitted. Example: "POS=12.821,-33.4". - SIZE – Optional
The coordinate angular size of the region given in decimal degrees. The region may be specified using either one or two values. If only one value is given it applies to both coordinate axes. If two values are given the first value is the angular width in degrees of the right-ascension axis of the region, and the second value is the angular width in degrees of the declination axis. Note that the angular width along the right-ascension axis is not the coordinate width of the region in right-ascension, which is equal to the coordinate angular width multiplied by cos(DEC).
If not specified, the size defaults to 0. - BAND – Optional
This parameter specifies a range of wavelengths. All results will then have a minimum wavelength that is less than the upper end of the range or a maximum wavelength that is greater than the lower end of the range.
The range is specified in meters, and can be a single decimal value or a pair of decimal values separated by "/". For a single value, the value represents both the lower and upper ends of the bounds. For the pair, the first value is the lower end and the second is the upper.
Scientific notation is allowed, for example, this specifies the range of 0.0000003m to 0.000005m:
3.0E-7/5.0E-6 - TIME – Optional
This parameter specifies a range of times. All results will then have a start time that is less than the upper end of the range or an end time that is greater than the lower end of the range.
The range is specified as either a single value, or a pair of values. For a single value, the value represents both the lower and upper ends of the bounds. For the pair, the first value is the lower end and the second is the upper. A single time may be any one of these formats:
- yyyy
- yyyy-mm
- yyyy-mm-dd
- yyyy-mm-ddThh:mm:ss
- FORMAT – Optional
Specifies the types of image products that are desired. Only images of the type requested will be returned. The parameter value is a comma-separated list of format types (image/jpg, image/jpeg, image/png, image/fits are recognized) or one of these special values:- ALL – Denotes all formats supported by the service.
- GRAPHIC – Denotes any of the following graphics formats: JPEG, PNG, GIF. These are types typically supported "in-line" by web-browsers.
- METADATA – Denotes a Metadata Query: no images are requested; only metadata should be returned.
Note that currently there are only guaranteed to be spectral products in fits format.
- POS – Required
-
MISSION & SERVICE INFO BASE URL SAMPLE SSA SEARCH HST (all) http://archive.stsci.edu/ssap/search2.php?id=HST& POS: 258.953,50.241SIZE: 0.5 degHST (FOS only) http://archive.stsci.edu/ssap/search2.php?id=FOS& POS: 258.953,50.241SIZE: 0.4 degHST (STIS only) http://archive.stsci.edu/ssap/search2.php?id=STIS& POS: 258.953,50.241SIZE: 0.4 degIUE http://archive.stsci.edu/ssap/search2.php?id=IUE& POS: 83.67,5-69.03SIZE: 0.2 deg -
All successful responses by the service will be in the form of a VOTable. The IVOA specification for VO Table is here: http://www.ivoa.net/documents/VOTable/20130920/. Sections 7.1 and 7.2 have good summary pictures of the grammar.
The successful VOTable result will contain exactly one RESOURCE which will contain exactly one TABLE. The TABLE will have FIELDs (columns) as defined in the next section, with each row representing a single image product.
Controlled error responses, such as those resulting from invalid input parameters, will also be in VOTables -
A successful VOTable result will contain the FIELDs (columns) described below. FIELDs have metadata attributes that describe the content of the FIELD, sometimes including Universal Content Descriptors (UCDs) and or Universal Type Decsriptors (UTypes).
When present for these spectral results, the FIELD's utype attribute (not the ucd) uniquely determines the meaning of the field (see table below).
UTYPE DESCRIPTION ssa:char.spatialaxis.coverage.location.value RA and Dec of target as a space-delimited pair of decimal values in degrees. ssa:access.reference URL of spectrum file ssa:target.name Target Name ssa:dataset.datamodel Datamode name and version ssa:dataset.length Number of data points. ssa:char.timeaxis.coverage.bounds.extent Total exposure time ssa:char.timeaxis.coverage.bounds.start Observation start MJD ssa:char.timeaxis.coverage.location.value Observation mid point MJD ssa:char.timeaxis.coverage.bounds.stop Observation stop MJD ssa:access.format Mime type of the image product ssa:coordsys.spaceframe.name Coordinate system of the reference frame ssa:coordsys.spaceframe.equinox Equinox ssa:char.spectralaxis.coverage.bounds.start Minimal wavelength represented within the data set (meters) ssa:char.spectralaxis.coverage.bounds.stop Maximal wavelength represented within the data set (meters) ssa:dataid.title data set name and target name ssa:coordsys.timeframe.name time reference frame ssa:coordsys.spectralframe.refpos spectrum reference frame ssa:curation.publisher Description ssa:dataid.creator Data creator ssa:dataid.datasetid data set identifier ssa:dataid.instrument Name of the instrument that produced the data ssa:dataid.datasource type of data source ssa:dataid.bandpass Bandpass ssa:char.spectralaxis.coverage.location.value Mean wavelength (meters) ssa:char.spectralaxis.coverage.bounds.extent Wavelength range (Wmax - Wmin in meters) ssa:char.spectralaxis.respower Resolving Power (i.e., W divided by dW) ssa:char.spatialaxis.coverage.bounds.extent Approximate size of region in degrees (based on largest dimension of aperture) ssa:dataid.collection Mission ssa:access.size Size of the file in kilobytes ObsCore.Char.SpatialAxis.Coverage.Support.Area STC/S Footprint
Table Access Protocol (TAP)
Accordion
-
Table Access Protocol (TAP), version 1.0, is an International Virtual Observatory Alliance (IVOA) protocol defining a web service for directly querying database tables and therefore catalogs. The query is written in a superset of basic SQL called Astronomical Data Query Language, or ADQL, which provides additional support for positionally based queries where appropriate for individual data resources. TAP services are self-descriptive in terms of announcing their schema, their support for positional capabilities, and providing sample queries for services providing data outside an IVOA data model.
- The formal IVOA document describing the TAP protocol is here: http://www.ivoa.net/Documents/TAP
- The formal IVOA document describing the ADQL protocol is here: http://http://www.ivoa.net/documents/latest/ADQL.html
-
As TAP services are powerful and flexible, they are also rather complex. Several clients and software libraries exist for interacting with any TAP service, and this is recommended over directly writing your own web calls in most cases.
- TOPCAT (Java, desktop): http://www.star.bris.ac.uk/~mbt/topcat/
- PyVO/Astropy: https://pyvo.readthedocs.io/en/latest/
-
Registry
The NAVO Directory is an interface for finding data collections and catalogs by searching their descriptions. The Directory search interface queries an underlying registry, or database of descriptive metadata about collections and catalogs. The Directory has access to the metadata of every registry hosted by an astronomical project in the IVOA as well as locally managed information. The registry and its records are defined by VO standards derived from ones widely used in library science.
The Directory web portal has been developed to provide direct search access for the scientific, student, or casual user, and programmatic search capabilities are also available for interoperability with other research tools.