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. Here is an example for existing data, followed by the response:

https://mast.stsci.edu/spectra/api/v0.1/retrieve?uri=mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits

Example Output
{	
 	"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. 

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 request is given below, followed by the response:

https://mast.stsci.edu/spectra/api/v0.1/search?wavelength=1.2,1.3&flux.gte=10&derSnr.gt=5

Example Output
{
	"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
	  },
	  {...},
	]
}

For Further Reading...

  • No labels

Data Use | Acknowledgements | DOI | Privacy

Send comments & corrections on this MAST document to: archive@stsci.edu