Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space DraftMASTDOCS and version 22.07
Excerpt
hiddentrue

Use the Jdaviz.MAST API to access parameters for JWST observations

Panel
borderColor#00617E
borderWidth2
borderStylesolid

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

Table of Contents

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

Code Block
languageyml
titleExample Output
collapsetrue
{
	"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.  

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

Code Block
languageyml
titleExample Output
collapsetrue
{
  "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.

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

Code Block
languageyml
titleExample Output
collapsetrue
{
  "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/

Code Block
languageyml
titleExample Output
collapsetrue
{
  "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 keywordhttps://mast.stsci.edu/viz/api/v0.1/info/keywords?name=BKGDTARG

Code Block
languageyml
titleExample Output
collapsetrue
{
  "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/

Code Block
languageyml
titleExample Output
collapsetrue
{
 "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 mnemonichttps://mast.stsci.edu/viz/api/v0.1/info/mnemonics/?name=so_zfxposns

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

For Further Reading...