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 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.
.
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/vizspectra/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.
Example: https://mast.stsci.edu/vizspectra/api/v0.1/retrieve?uri=mast:JWST/product/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "status": 1, "message": "Successfully found data for jw01039-o004_t001_miri_ch3-long_x1d.fits", "uri": null, "mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits", "filename": "jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits", "column_metadata": { "wavelength": { "units "dtype": "umfloat", "description": "wavelength values", "dtype"units": "floatum", "fitsExt": "WAVELENGTH" }, "flux": {...}, ... }, "data": { "wavelength" : [15.411499847425148, 15.414499847451225, ...], "flux" : [0.31976015668259855, 0.32322893464617114,...], "err" "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 is https://mast.stsci.edu/vizspectra/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 > 05 ;", "results": [ { "fileName": "jw00668jw01022-o007o015_s00000t001_nirspec_f070lpg140h-g140mf100lp_x1d.fits", "x": 658851, "y": null, "wavelength": 1.20005138149095482000044446967135, "flux": 29353185927662.84466219771384713414, "derSnr": 034.0965381487041646839563686027962 }, { "fileName": "jw00668jw01022-o007o015_s00000t001_nirspec_f070lpg140h-g140mf100lp_x1d.fits", "x": 660852, "y": null, "wavelength": 1.201316540285484200239444696234, "flux": 125894186828761.0893811492136920592, "derSnr": 034.0965381487041646839563686027962 }, { "fileName": "jw00668jw01022-o007o015_s00000t001_nirspec_f070lpg140h-g140mf100lp_x1d.fits", "x": 661853, "y": null, "wavelength": 1.20194911432799432004744446957543, "flux": 151836172866204.0581332362210833856, "derSnr": 034.0965381487041646839563686027962 }, {...}, ] } |