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.
| MISSION & SERVICE INFO | BASE URL | SAMPLE CONE SEARCH |
|---|---|---|
| Kepler Planets | http://archive.stsci.edu/kepler/confirmed_planets/search.php? |
RA: 285.67943
Dec: 50.24132
Radius: 1.0 deg
|
| KOI | http://archive.stsci.edu/kepler/koi/search.php? |
RA: 285.67943
Dec: 50.24132
Radius: 1.0 deg
|
| HSC Summary | http://archive.stsci.edu/hst/hsc_sum/search.php? |
RA: 210.80227
Dec: 54.34895
Radius: 0.001 deg
|
| HSC Detailed | http://archive.stsci.edu/hst/hsc/search.php? |
RA: 210.80227
Dec: 54.34895
Radius: 0.001 deg
|
| TIC | http://gsss.stsci.edu/webservices/vo/ConeSearch.aspx?CAT=TESSINPUT& |
RA: 210.80227
Dec: 54.34895
Radius: 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.348950
SIZE: 0.24 deg
|
| GALEX | http://mast.stsci.edu/portal/Mashup/VoQuery.asmx/SiaV1?MISSION=GALEX& |
POS: 210.802,54.349
SIZE: 0.15 deg
|
| CANDELS (HLSP) | http://archive.stsci.edu/siap/search.php?id=candels& |
POS: 189.25684,62.50686950
SIZE: 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.
| MISSION & SERVICE INFO | BASE URL | SAMPLE SSA SEARCH |
|---|---|---|
| HST (all) | http://archive.stsci.edu/ssap/search2.php?id=HST& |
POS: 258.953,50.241
SIZE: 0.5 deg
|
| HST (FOS only) | http://archive.stsci.edu/ssap/search2.php?id=FOS& |
POS: 258.953,50.241
SIZE: 0.4 deg
|
| HST (STIS only) | http://archive.stsci.edu/ssap/search2.php?id=STIS& |
POS: 258.953,50.241
SIZE: 0.4 deg
|
| IUE | http://archive.stsci.edu/ssap/search2.php?id=IUE& |
POS: 83.67,5-69.03
SIZE: 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.