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

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

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

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

• MAST Data Holdings