The Jdaviz.MAST API provides programmatic access to a variety of parameters and metadata related to JWST data products and observations. This article provides a brief summary of the available API endpoints. See the complete API documentation for more details. 

On this page...

The Jdaviz.MAST API

The global URL for the Jdaviz.MAST API is https://mast.stsci.edu/viz/api/v0.1/, which has the following service endpoints:

  • parameters: return observation parameters
  • keywords/search: return instrument keywords
  • products: return related data products
  • info/keywords: return instrument keyword metadata
  • info/mnemonics: return engineering mnemonic metadata

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.

Accessing Observation Parameters

You can access the observations parameters for any JWST data product given a MAST DATA URI.  Use the endpoint https://mast.stsci.edu/viz/api/v0.1/parameters, which accepts a URI query parameter with syntax "uri=[MAST_DATA_URI]".  See the Parameters API Documentation for complete details.  The parameters returned by this endpoint, in JSON format, are the same as the Portal Product File Details. 

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

Example Output 
{
	"dataproduct_type":"cube",
	"calib_level":3,
	"obs_collection":"JWST",
	"obs_id":"jw01039-o004_t001_miri_ch3-long",
	"obsType":"PRIME",
	"intentType":"science",
	"target_name":"NGC6552",
	"s_ra":270.0302116666667,
	"s_dec":66.61509722222222,
	"mtFlag":false,
	"t_min":59706.50301039352,
	"t_max":59706.51692592593,
	"t_exptime":555.008,
	"wavelength_region":null,
	"instrument_name":"MIRI",
	"filters":null,
	"em_min":null,
	"em_max":null,
	"pol_states":null,
	"target_classification":null,
	"obs_title":"MIRI Detector Latent Image Characterization",
	"t_obs_release":59774.8541666,
	"proposal_pi":"Dicken, Daniel",
	"proposal_id":"1039",
	"proposal_type":"JWST",
	"provenance_name":"CALJWST",
	"project":"JWST",
	"sequence_number":-999,
	"s_region":"POLYGON -89.975360290000026 66.59444259 -89.967807240000013 66.59444259 -89.967807240000212 66.5955008252255 -89.966547260000027 66.5955008 ...",
	"jpegURL":"mast:JWST/product/jw01039-o004_t001_miri_ch3-long_s3d.jpg",
	"dataURL":"mast:JWST/product/jw01039-o004_t001_miri_ch3-long_s3d.fits",
	"dataRights":"PUBLIC",
	"metaDataRights":"PUBLIC",
	"srcDen":null,
	"obsid":83209967,
	"objID":165643579
}

Accessing Science Instrument Keywords

You can access the science instrument (SI) keywords for any JWST data product given a MAST DATA URI or product filename. Use the endpoint https://mast.stsci.edu/viz/api/v0.1/keywords/search, which accepts a URI query parameter with syntax "uri=[MAST_DATA_URI]". See the Keywords API Documentation for complete details. This endpoint returns the SI keywords in JSON format.  

Example: https://mast.stsci.edu/viz/api/v0.1/keywords/search?uri=mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits

Example Output 
{
  "ArchiveFileID":5924537,
  "filename":"jw01039-o004_t001_miri_ch3-long_x1d.fits",
  "fileSetName":"jw01039-o004_t001_miri",
  "productLevel":"3",
  "act_id":"01",
  "apername":"MIRIFU_CHANNEL1A",
  "asnpool":"jw01039_20220702t204540_pool.csv",
  "asntable":"jw01039-o004_20220702t204540_spec3_001_asn.json",
  "bartdelt":-198.8018335774541,
  "bendtime":59706.5108916159,
  "bkgdtarg":"f",
  "bkglevel":null,
  "bkgsub":null,
  "bmidtime":59706.51049015499,
  "bstrtime":59706.51008869405,
  "category":"COM",
  "cont_id":null,
  "datamode":7,
  "dataprob":"f",
  "date":"2022-07-02T22:16:43.890000",
  "date_mjd":59762.92828576389,
  "date_end":"2022-05-07T12:24:21.760000",
  "date_end_mjd":59706.516918518515,
  "date_obs":"2022-05-07T12:04:20.097999",
  "date_obs_mjd":59706.50301037037,
  "detector":"MIRIFULONG",
  "drpfrms1":0,
  "drpfrms3":0,
  "duration":555.008,
  "effexptm":555.008,
  "effinttm":69.376,
  "eng_qual":"OK",
  "exp_type":"MIR_MRS",
  "expcount":1,
  "expend":59706.51691851852,
  "expmid":59706.5099846412,
  "exposure":6,
  "expripar":"PRIME",
  "expstart":59706.50301039352,
  "fastaxis":1,
  "filter":null,
  "frmdivsr":1,
  "gainfact":null,
  "gdstarid":"N4E8004471",
  "groupgap":0,
  "gs_dec":66.77963507876898,
  "gs_mag":15.89793395996094,
  "gs_order":1,
  "gs_ra":269.9185220667708,
  "gsendtim":"2022-05-07T12:01:50.338000",
  "gsendtim_mjd":59706.50127703704,
  "gsstrttm":"2022-05-07T12:00:21.250000",
  "gsstrttm_mjd":59706.50024594907,
  "gs_udec":0.000722415601193118,
  "gs_umag":0.05136068910360336,
  "gs_ura":0.000455751810140842,
  "helidelt":-199.7010667808354,
  "hendtime":59706.51088120813,
  "hga_move":"f",
  "hmidtime":59706.51047974721,
  "hstrtime":59706.51007828626,
  "instrume":"MIRI",
  "intarget":"f",
  "is_psf":null,
  "lamp":"OFF",
  "mu_dec":0.0,
  "mu_epoch":"2015-07-02T12:00:00",
  "mu_epoch_mjd":57205.5,
  "mu_ra":0.0,
  "nexposur":8,
  "nextend":null,
  "nframes":1,
  "ngroups":25,
  "nints":1,
  "nresets":1,
  "nrststrt":0,
  "nsamples":1,
  "numdthpt":8,
  "nwfsest":59706.90709584491,
  "obs_id":"V01039004001P0000000002101",
  "observtn":4,
  "obslabel":"Latent soak Imager F560W - Position 3",
  "origin":"STSCI",
  "pcs_mode":"FINEGUIDE",
  "pi_name":"Dicken,
   Daniel",
  "pps_aper":"MIRIM_ILLUM",
  "prd_ver":"PRDOPSSOC-054",
  "program":1039,
  "prop_dec":66.61509722222222,
  "prop_ra":270.0302116666667,
  "pwfseet":59705.6527646875,
  "readpatt":"FASTR1",
  "sca_num":494,
  "scicat":null,
  "sdp_ver":"2022_2a",
  "selfref":null,
  "seq_id":"1",
  "slowaxis":2,
  "subarray":"FULL",
  "subcat":"MIRI",
  "subsize1":1032,
  "subsize2":1024,
  "substrt1":1,
  "substrt2":1,
  "targ_dec":66.61509722222222,
  "targ_ra":270.0302116666667,
  "targname":"NGC 6552",
  "targoopp":"f",
  "targprop":"NGC-6552",
  "targtype":"FIXED",
  "targudec":0.1,
  "targura":0.1,
  "telescop":"JWST",
  "template":"MIRI External Flat",
  "tframe":2.77504,
  "tgroup":2.77504,
  "timesys":"UTC",
  "title":"MIRI Detector Latent Image Characterization",
  "tsample":10.0,
  "tsovisit":"f",
  "visit":1,
  "visit_id":"01039004001",
  "visitend":"2022-05-07T12:25:40.864000",
  "visitend_mjd":59706.5178340625,
  "visitgrp":"02",
  "visitsta":"SUCCESSFUL",
  "visitype":"PRIME_TARGETED_FIXED",
  "vststart":"2022-05-07T11:55:26.338000",
  "vststart_mjd":59706.496832592595,
  "xoffset":5.332307520493426,
  "yoffset":6.47702245978903,
  "zerofram":"f",
  "errtype":null,
  "rois":null,
  "roiw":null,
  "wpower":null,
  "wtype":null,
  "datamodl":"MultiSpecModel",
  "exp_only":"f",
  "exsegnum":null,
  "exsegtot":null,
  "intstart":null,
  "intend":null,
  "date_beg":"2022-05-07T12:04:20.098000",
  "date_beg_mjd":59706.50301037037,
  "obsfoldr":"Latent observations",
  "sctarate":-0.720384722948798,
  "opmode":null,
  "osf_file":"2022127T123106704_002_osf.xml",
  "expsteng":null,
  "expsteng_mjd":null,
  "masterbg":null,
  "scatfile":null,
  "srctyapt":"UNKNOWN",
  "tcatfile":null,
  "texptime":null,
  "patt_num":6,
  "pattsize":null,
  "patttype":"4-POINT-SETS",
  "pridtpts":null,
  "subpxpts":null,
  "crowdfld":"f",
  "engqlptg":"CALCULATED_TRACK_TR_202111",
  "oss_ver":"8.4.2",
  "noutputs":null,
  "gs_v3_pa":223.1384655404019,
  "dirimage":null,
  "pixfrac":null,
  "pxsclrt":null,
  "segmfile":null,
  "va_dec":66.59280573616425,
  "va_ra":270.039912295606,
  "compress":null,
  "bkgmeth":null,
  "s_region":null,
  "cal_ver":"1.5.3",
  "cal_vcs":"RELEASE",
  "crds_ctx":"jwst_0913.pmap",
  "crds_ver":"11.16.3",
  "band":"LONG",
  "cccstate":"OPEN",
  "channel":"3",
  "coronmsk":null,
  "pattstrt":null,
  "spat_num":null,
  "spatnstp":null,
  "spatstep":null,
  "spcoffst":null,
  "spec_num":null,
  "specnstp":null,
  "specstep":null,
  "sptoffst":null,
  "mirngrps":null,
  "mirnfrms":null,
  "dithdirc":"POSITIVE",
  "dithopfr":"EXTENDED-SOURCE",
  "dithpnts":null,
  "dsetstrt":null,
  "mrsprchn":null,
  "numdsets":null,
  "pattnpts":null,
  "detmode":null,
  "cmd_tsel":null,
  "fpe_side":"A",
  "ice_side":"A",
  "fileSize":190080,
  "checksum":"988f90cad25ebfcae20481d6d7aa35e1",
  "ingestStartDate":"2022-07-02T22:17:45.037000",
  "ingestStartDate_mjd":59762.928993472226,
  "ingestCompletionDate":"2022-07-02T22:17:59.651000",
  "ingestCompletionDate_mjd":59762.92916261574,
  "FileTypeID":63,
  "publicReleaseDate":"2022-07-14T20:30:00",
  "publicReleaseDate_mjd":59774.854166666664,
  "isRestricted":false,
  "isItar":false,
  "isStale":false,
  "FileSetId":876299
}

Accessing Related Data Products

You can access all related data product for any JWST data product given a MAST DATA URI. Use the endpoint https://mast.stsci.edu/viz/api/v0.1/products, which accepts a URI query parameter with syntax "uri=[MAST_DATA_URI]", and level query parameter, indicating the MAST Calibration Level of the products. See the Products API Documentation for complete details. This endpoint returns a list of data products for a given JWST observation ID. Each item in the list is a dictionary of data product parameters.

Example: https://mast.stsci.edu/viz/api/v0.1/products?uri=mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits&level=3

Example Output 
{
  "jw01039-o004_t001_miri_ch3-long":[
 {
  "obsID":83209967,
  "obs_collection":"JWST",
  "obs_id":"jw01039-o004_t001_miri_ch3-long",
  "dataproduct_type":"cube",
  "type":"D",
  "productType":"SCIENCE",
  "productGroupDescription":"Minimum Recommended Products",
  "productSubGroupDescription":"S3D",
  "productDocumentationURL":null,
  "project":"CALJWST",
  "prvversion":"1.5.3",
  "proposal_id":"1039",
  "dataURI":"mast:JWST/product/jw01039-o004_t001_miri_ch3-long_s3d.fits",
  "productFilename":"jw01039-o004_t001_miri_ch3-long_s3d.fits",
  "description":"exposure/target (L2b/L3): 3D image of spectrum",
  "size":370405440,
  "parent_obsid":83209967,
  "dataRights":"PUBLIC",
  "calib_level":3,
  "exp_type":"MIR_MRS",
  "template":"MIRI External Flat"
 },
 {
  "obsID":83209967,
  "obs_collection":"JWST",
  "obs_id":"jw01039-o004_t001_miri_ch3-long",
  "dataproduct_type":"cube",
  "type":"D",
  "productType":"SCIENCE",
  "productGroupDescription":"Minimum Recommended Products",
  "productSubGroupDescription":"X1D",
  "productDocumentationURL":null,
  "project":"CALJWST",
  "prvversion":"1.5.3",
  "proposal_id":"1039",
  "dataURI":"mast:JWST/product/jw01039-o004_t001_miri_ch3-long_x1d.fits",
  "productFilename":"jw01039-o004_t001_miri_ch3-long_x1d.fits",
  "description":"exposure/target (L2b/L3): 1D extracted spectrum",
  "size":190080,
  "parent_obsid":83209967,
  "dataRights":"PUBLIC",
  "calib_level":3,
  "exp_type":"MIR_MRS",
  "template":"MIRI External Flat"
 }
]
}

Accessing Metadata Information

You can access metadata information about the JWST Science Instrument (SI) keywords and Engineering Mnemonics using the API endpoint https://mast.stsci.edu/viz/api/v0.1/info/. See the Info API Documentation for complete details. 

Science Instrument Keywords

To access the metadata information about the science instrument keywords, use the endpoint https://mast.stsci.edu/viz/api/v0.1/info/keywords/. You can optionally specify a name query parameter, specifying the name of the keyword you wish to return information on. This endpoint returns the Instrument Keyword schema information in JSON format, the same information as displayed in the JWST Keyword Dictionary. 

Example - Return all keywords: https://mast.stsci.edu/viz/api/v0.1/info/keywords/

Example Output 
{
  "all.dither.schema.json": {
    "total_points": {
      "fits_keyword": "NUMDTHPT",
      "title": "Total number of points in dither pattern",
      "description": "Total number of points in entire dither pattern",
      "type": "integer",
      "units": "",
      "example": "3",
      "default_value": "1",
      "source": "Proposal and Planning System (PPS)",
      "sw_source": "",
      "calculation": "maximum(PPS:exposures.dither_point_index) in pattern (for program, observation, and pattern dither_id)",
      "destination": [
        "ScienceCommon.numdthpt"
       ],
      "sql_dtype": "int",
      "si": "All",
      "mode": "All",
      "level": "1b",
      "fits_hdu": "PRIMARY",
      "section": "Dither",
      "misc": ""
      },
    "position_number": {
      "fits_keyword": "PATT_NUM",
      "title": "Position number within dither pattern",
      "description": "Position number within dither pattern",
      "type": "integer",
      "units": "",
      "example": "1",
      "default_value": "1",
      "source": "Proposal and Planning System (PPS)",
      "sw_source": "PPS:exposures.dither_point_index",
      "calculation": "",
      "destination": [
       "ScienceCommon.patt_num"
       ],
      "sql_dtype": "smallint",
      "si": "All",
      "mode": "All",
      "level": "1b", 
      "fits_hdu": "PRIMARY",
      "section": "Dither",
      "misc": ""
      },
    ...
}

Example - Return a single keyword: https://mast.stsci.edu/viz/api/v0.1/info/keywords?name=BKGDTARG

Example Output 
{
  "science.observation.schema.json": {
    "bkgdtarg": {
      "fits_keyword": "BKGDTARG",
      "title": "Background target",
      "description": "Indicates whether the proposer flagged the target or target field contained in the exposure to be used as a background target for other exposures.",
      "type": "boolean",
      "units": "",
      "example": "T",
      "default_value": "F",
      "source": "",
      "sw_source": "PPS:dms_target_view.background",
      "calculation": "",
      "destination": [
       "ScienceCommon.bkgdtarg"
       ],
      "sql_dtype": "nchar(1)",
      "si": "Multiple",
      "mode": "All",
      "level": "1b",
      "fits_hdu": "PRIMARY",
      "section": "Observation identifiers",
      "misc": ""
      }
   }
}

Engineering Mnemonics

To access the metadata information about the engineering mnemonics, use the endpoint https://mast.stsci.edu/viz/api/v0.1/info/mnemonics/. You can optionally specify a name query parameter, specifying the name of the mnemonic you wish to return information on. This endpoint returns the mnemonic schema information in JSON format, the same information as displayed in the JWST Engineering Portal. 

Example - Return all mnemonics: https://mast.stsci.edu/viz/api/v0.1/info/mnemonics/

Example Output 
{
 "data": [
  {
   "subsystem": "FOS",
   "tlmMnemonic": "FGDP_ICDH_STATE",
   "tlmIdentifier": 570000,
   "description": "ICDH state",
   "sqlDataType": "varchar",
   "unit": ""
  },
  {
   "subsystem": "FOS",
   "tlmMnemonic": "FGDP_INRS_FPE_A1FL",
   "tlmIdentifier": 570067,
   "description": "NIRSpec FPE ASIC1 Files Loaded Status",
   "sqlDataType": "varchar",
   "unit": ""
  },
  {...},
  {...},
 ]
}


Example - Return a single mnemonic: https://mast.stsci.edu/viz/api/v0.1/info/mnemonics/?name=so_zfxposns

Example Output 
{
 "data": [
  {
   "subsystem": "OTE",
   "tlmMnemonic": "SO_ZFXPOSNS",
   "tlmIdentifier": 81669,
   "description": "x axis position of the FSM",
   "sqlDataType": "float",
   "unit": "rad"
  }
 ]
}

For Further Reading...

  • No labels

Data Use | Acknowledgements | DOI | Privacy

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