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
Basics of an API
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.
Warning |
---|
The following examples use test pixel data, and do not represent accurate scientific pixel searches. |
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/viz/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, "uri": null, "filename": "jw00212-o035_t007_miri_ch2-short_x1d.fits", "column_metadata": { "wavelength": { "units": "um", "description": "wavelength values", "dtype": "float", "fitsExt": "WAVELENGTH" }, "flux": {...}, ... }, "data": { "wavelength" : [], "flux" : [], "err" : [], ... } } |
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/viz/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 > 0 ;", "results": [ { "fileName": "jw00668-o007_s00000_nirspec_f070lp-g140m_x1d.fits", "x": 658, "y": null, "wavelength": 1.2000513814909548, "flux": 29353.844662197713, "derSnr": 0.09653814870416468 }, { "fileName": "jw00668-o007_s00000_nirspec_f070lp-g140m_x1d.fits", "x": 660, "y": null, "wavelength": 1.201316540285484, "flux": 125894.08938114921, "derSnr": 0.09653814870416468 }, { "fileName": "jw00668-o007_s00000_nirspec_f070lp-g140m_x1d.fits", "x": 661, "y": null, "wavelength": 1.2019491143279943, "flux": 151836.05813323622, "derSnr": 0.09653814870416468 }, {...}, ] } |