Page History
| Excerpt | ||
|---|---|---|
| ||
Use this MAST API to search and/or retrieve science pixels from JWST data products |
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
The Spectral DB API provides programmatic access for searching, and retrieving, the science pixels from level 3 JWST data products. This article provides a brief summary of the available API endpoints. See the complete API documentation for more details. On this page...
|
The Spectral DB API
The global API URL is https://mast.stsci.edu/viz/api/v0.1/, which has the following endpoints:
- retrieve: return pixels from data products
- search: search through data products by their pixel information
The examples on this page assume basic knowledge of APIs and making HTTP requests. For a refresher, see the Basics of an API. Unless otherwise specified, all API calls and URLS on this page are HTTP GET requests.
Retrieving Pixel Data
You can access the pixel level data for any level 3 JWST spectroscopic data product, given a MAST DATA URI. Products currently supported are those ending in "x1d", "c1d", "s2d", and "s3d". Use the endpoint https://mast.stsci.edu/spectra/api/v0.1/retrieve, which accepts a URI query parameter with syntax "uri=[MAST_DATA_URI]". See the Retrieve API Documentation for complete details. The parameters returned by this endpoint, in JSON format, are some status information about response, a dictionary of metadata about the data columns returns, and a dictionary of array data. The pixel array data returned by this point matches the FITS extensions from the Stage 3 Data Products, e.g. the x1d EXTRACT1D, or the s3d.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"status": 1,
"message": "Successfully found data for jw01039-o004_t001_miri_ch3-long_x1d.fits",
"uri": "mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits",
"filename": "jw01039-o004_t001_miri_ch3-long_x1d.fits",
"column_metadata": {
"wavelength": {
"dtype": "float", "description": "wavelength values", "units": "um", "fitsExt": "WAVELENGTH"},
"flux": {...},
...
},
"data": {
"wavelength": [15.411499847425148, 15.414499847451225, ...],
"flux": [0.31976015668259855, 0.32322893464617114,...],
"fluxErr": [0.0003309399844085619, 0.00032996967321051527,...],
...
}
} |
Searching by Pixel Data
All level 3 spectroscopic science data products are ingested into a new Spectra Database. You can search the pixel-level information across these data products, with a simple conditional syntax. Use the endpoint https://mast.stsci.edu/viz/api/v0.1/search. See the Pixel Search API Documentation for complete details. This endpoint, in JSON format, includes status information about the request, the string representation of the SQL query, and the a list of search results matching the search criteria. Each item in the list of results represents a single data pixel matching your condition.
| Note |
|---|
The pixel search API currently only supports searching on 1D (x1d) spectroscopic data products. Support for 2D and 3D spectroscopic pixel searches is coming soon. |
Example: To search for 1d spectroscopic (x1d) JWST data products that have a derived global SNR > 5 and a flux value >= 10 in the wavelength range of 1.2-1.3 microns, the URL route is https://mast.stsci.edu/spectra/api/v0.1/search?wavelength=1.2,1.3&flux.gte=10&derSnr.gt=5
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"status": 1,
"query": "select d.fileName, s.x, s.y, s.wavelength, s.flux, c.derSnr from dbo.DataProduct as d join dbo.SpectralCharacteristics as c on d.DataProductID=c.DataProductID join dbo.SpectralPixel as s on d.DataProductID=s.DataProductID where d.productType = 'x1d' and s.wavelength between 1.2 and 1.3 and s.flux >= 10 and c.derSnr > 5 ;",
"results": [
{
"fileName": "jw01022-o015_t001_nirspec_g140h-f100lp_x1d.fits",
"x": 851,
"y": null,
"wavelength": 1.2000044446967135,
"flux": 185927662.84713414,
"derSnr": 34.39563686027962
},
{
"fileName": "jw01022-o015_t001_nirspec_g140h-f100lp_x1d.fits",
"x": 852,
"y": null,
"wavelength": 1.200239444696234,
"flux": 186828761.36920592,
"derSnr": 34.39563686027962
},
{"fileName": "jw01022-o015_t001_nirspec_g140h-f100lp_x1d.fits",
"x": 853, "y": null, "wavelength": 1.2004744446957543,
"flux": 172866204.10833856,
"derSnr": 34.39563686027962
},
{...},
]
} |