Page History

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

hidden	true

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

Panel

borderColor	#00617E
borderWidth	2
borderStyle	solid

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/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits

Code Block

language	yml
title	Example Output
collapse	true

{
  	"dataproduct_type": "cube",
  	"calib_level": 3,
  	"obs_collection": "JWST",
  	"obs_id": "jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong",
  	"obsType": "PRIME",
  	"intentType": "science",
  	"target_name": "TARGET2-CVZ-SOUTHNGC6552",
  	"s_ra": 90270.755416666666660302116666667,
  	"s_dec": -66.5605555555555461509722222222,
  	"mtFlag": false,
  	"t_min": 5899059706.4558764189850301039352,
  	"t_max": 5899059706.4803185416751692592593,
  	"t_exptime": 666555.008,
  	"wavelength_region": ""null,
  	"instrument_name": "MIRI",
  	"filters": "MRS"null,
  	"em_min": null,
  	"em_max": null,
  	"pol_states": null,
  	"target_classification": null,
  	"obs_title": "MIRI Detector SORLatent Image observationsCharacterization",
  	"t_obs_release": 5910959774.8541666,
  	"proposal_pi": "LennonDicken, Daniel J.",
  	"proposal_id": "002121039",
  	"proposal_type": "JWST;B7.4",
  	"provenance_name": "CALJWST",
  	"project": "JWST",
  	"sequence_number": -999,
  	"s_region": "POLYGON 90-89.75444602975360290000026 -66.5599777759444259 90-89.75407587967807240000013 -66.5609972259444259 90-89.75640132967807240000212 -66.561141665955008252255 90-89.75675044966547260000027 -66.56010833 90.75444602 -66.55997777 90.75444602 -66.559977775955008 ...",
  	"jpegURL": "mast:JWST/product/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1ds3d.pngjpg",
  	"dataURL": "mast:JWST/product/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1ds3d.fits",
  	"dataRights": "PUBLIC",
  	"metaDataRights": "PUBLIC",
  	"srcDen": null,
  	"obsid": 5573011683209967,
  	"objID": 95953761165643579
}

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/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits

Code Block

language	yml
title	Example Output
collapse	true

{
  "ArchiveFileID": 95282075924537,
  "filename": "jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits",
  "fileSetName": "jw00212jw01039-o035o004_t007t001_miri",
  "productLevel": "3",
  "act_id": "01",
  "apername": "MIRIFU_CHANNEL1A",
  "asnpool": "jw00212jw01039_20210302t13064620220702t204540_pool.csv",
  "asntable": "jw00212jw01039-o035o004_20210302t13064620220702t204540_spec3_001_asn.json",
  "bartdelt": 351-198.92936311941598018335774541,
  "bendtime": 5899059706.462168096295108916159,
  "bkgdtarg": "f",
  "bkglevel": null,
  "bkgsub": "f"null,
  "bmidtime": 5899059706.46200749751049015499,
  "bstrtime": 5899059706.4618468977251008869405,
  "category": "ENGCOM",
  "cont_id": null,
  "datamode": 17,
  "dataprob": "f",
  "date": "20212022-0307-02 1702T22:3216:2943.325000890000",
  "date_mjd": 5927559762.7308949768592828576389,
  "date_end": "20202022-05-21 1107T12:3124:3921.522000760000",
  "date_end_mjd": 5899059706.480318553244516918518515,
  "date_obs": "20202022-05-21 1007T12:5604:2720.722999097999",
  "date_obs_mjd": 5899059706.4558764236150301037037,
  "detector": "MULTIPLEMIRIFULONG",
  "drpfrms1": 0,
  "drpfrms3": 0,
  "duration": 666555.008,
  "dva_dec": null,
  "dva_ra": null,
  "effexptm": 666555.008,
  "effinttm": 1369.8752376,
  "eng_qual": "OK",
  "exp_type": "MIR_MRS",
  "expcount": 1,
  "expend": 5899059706.4803185416751691851852,
  "expmid": 5899059706.468089082375099846412,
  "exposure": 26,
  "expripar": "PRIME",
  "expstart": 5899059706.4558764189850301039352,
  "fastaxis": 1,
  "filetype": "1d spectrum",
  "filter": null,
  "frmdivsr": 1,
  "gainfact": null,
  "gdstarid": "S4E8273118N4E8004471",
  "groupgap": 0,
  "gs_dec": -66.5689959779157677963507876898,
  "gs_mag": 15.7159042358398489793395996094,
  "gs_order": 1,
  "gs_ra": 90269.179151101952979185220667708,
  "gsendtim": "20202022-05-21 1007T12:5401:3450.018000338000",
  "gsendtim_mjd": 5899059706.45456037037450127703704,
  "gsstrttm": "20202022-05-21 1007T12:5000:0721.752000250000",
  "gsstrttm_mjd": 5899059706.4514786226950024594907,
  "gs_udec": 0.000119077307601839000722415601193118,
  "gs_umag": 0.0353993251919746405136068910360336,
  "gs_ura": 0.00011834900961995000455751810140842,
  "helidelt": 354-199.68851570039997010667808354,
  "hendtime": 5899059706.4622000309251088120813,
  "hga_move": "f",
  "hmidtime": 5899059706.4620394316451047974721,
  "hstrtime": 5899059706.4618788323651007828626,
  "instrume": "MIRI",
  "intarget": "f",
  "is_psf": null,
  "lamp": "OFF",
  "mu_dec": 0.0018090,
  "mu_epoch": "20002015-0107-01 0002T12:00:00",
  "mu_epoch_mjd": 5154457205.5,
  "mu_ra": 0.0032090007240961470,
  "nexposur": 128,
  "nextend": null,
  "nframes": 1,
  "ngroups": 525,
  "nints": 21,
  "nresets": 01,
  "nrststrt": 0,
  "nsamples": 1,
  "numdthpt": 18,
  "nwfsest": 5900159706.8846408796390709584491,
  "obs_id": "V00212035001P0000000002101V01039004001P0000000002101",
  "observtn": 354,
  "obslabel": "SouthLatent Polesoak -Imager MIRIF560W MRS nOPS6-OTB-20190828 ObsPosition 293",
  "origin": "STSCI",
  "pcs_mode": "FINEGUIDE",
  "pi_name":"Dicken,
   Daniel"N/A",
  "pps_aper": "MIRIFUMIRIM_CHANNEL1AILLUM",
  "prd_ver": "PRDOPSSOC-034054",
  "program": 2121039,
  "prop_dec": -66.5605555555555561509722222222,
  "prop_ra": 90270.755416666666660302116666667,
  "pwfseet": 5898859705.830019224546527646875,
  "readpatt": "FASTFASTR1",
  "sca_num": 494,
  "scicat": null,
  "sdp_ver": "20212022_12a",
  "selfref": null,
  "seq_id": "1",
  "slowaxis": 2,
  "subarray": "FULL",
  "subcat": null"MIRI",
  "subsize1": 1032,
  "subsize2": 1024,
  "substrt1": 1,
  "substrt2": 1,
  "targ_dec": -66.5605555555555461509722222222,
  "targ_ra": 90270.755416666666660302116666667,
  "targname":"NGC 6552"TARGET2-CVZ-SOUTH",
  "targoopp": "f",
  "targprop": "TARGET2NGC-CVZ-SOUTH6552",
  "targtype": "FIXED",
  "targudec": 0.1,
  "targura": 0.1,
  "telescop": "JWST",
  "template": "MIRI MediumExternal Resolution SpectroscopyFlat",
  "tframe": 2.77504,
  "tgroup": 2.77504,
  "timesys": "UTC",
  "title": "MIRI Detector SORLatent Image observationsCharacterization",
  "tsample": 10.0,
  "tsovisit": "f",
  "visit": 1,
  "visit_id": "0021203500101039004001",
  "visitend": "20202022-05-21 1107T12:3225:4440.937000864000",
  "visitend_mjd": 5899059706.4810756481465178340625,
  "visitgrp": "02",
  "visitsta": "SUCCESSFUL",
  "visitype": "PRIME_TARGETED_FIXED",
  "vststart": "20202022-05-21 1007T11:3955:5826.410000338000",
  "vststart_mjd": 5899059706.444426041664496832592595,
  "xoffset": 05.1173889577430032332307520493426,
  "yoffset": -16.22096462101427547702245978903,
  "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": "20202022-05-21 1007T12:5604:2720.723000098000",
  "date_beg_mjd": 5899059706.4558764236150301037037,
  "obsfoldr": "MRS- MIRI nOPS6-OTB-20190828Latent observations",
  "sctarate": -0.3547650522774825720384722948798,
  "opmode": null,
  "osf_file": "2020142T1107281632022127T123106704_01002_osf.xml",
  "expsteng": null,
  "expsteng_mjd": null,
  "masterbg": null,
  "scatfile": null,
  "srctyapt": "POINTUNKNOWN",
  "tcatfile": null,
  "texptime": null,
  "patt_num": 26,
  "pattsize": null,
  "patttype": "24-POINT-SETS",
  "pridtpts": null,
  "subpxpts": null,
  "crowdfld": "f",
  "engqlptg": "CALCULATED_TRACK_TR_202111",
  "oss_ver": null"8.4.2",
  "noutputs": null,
  "gs_v3_pa": null223.1384655404019,
  "s_regiondirimage": null,
  "cal_verpixfrac":null,
  "1.1.0"pxsclrt":null,
  "cal_vcssegmfile": "RELEASE"null,
  "crdsva_ctxdec": "jwst_0682.pmap"66.59280573616425,
  "crdsva_verra": "10.3.8"270.039912295606,
  "bandcompress":null,
  "MULTIPLEbkgmeth":null,
  "cccstates_region": "OPEN"null,
  "channelcal_ver": "2 "1.5.3",
  "coronmskcal_vcs": null"RELEASE",
  "pattstrtcrds_ctx": null"jwst_0913.pmap",
  "spatcrds_numver":"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": "NEGATIVEPOSITIVE",
  "dithopfr": "EXTENDED-SOURCE",
  "dithpnts": null,
  "dsetstrt": null,
  "mrsprchn": "ALL"null,
  "numdsets": null,
  "pattnpts": null,
  "detmode": null,
  "cmd_tsel": nullnull,
  "fpe_side":"A",
  "ice_side":"A",
  "fileSize": 103680190080,
  "checksum": "258f66f01f9e9ac30b819e426bc03e5a988f90cad25ebfcae20481d6d7aa35e1",
  "ingestStartDate": "20212022-0307-02 02T22:17:37:3145.878000037000",
  "ingestStartDate_mjd": 5927559762.734396712964928993472226,
  "ingestCompletionDate": "20212022-0307-02 02T22:17:37:3259.973000651000",
  "ingestCompletionDate_mjd": 5927559762.7344094097292916261574,
  "FileTypeID": 63,
  "publicReleaseDate": "20202022-0907-17 0014T20:0030:00",
  "publicReleaseDate_mjd": 5910959774.854166666664,
  "isRestricted": false,
  "isItar": false,
  "isStale": truefalse,
  "FileSetId": 165929876299
}

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/jw00212jw01039-o035o004_t007t001_miri_ch2ch3-shortlong_x1d.fits&level=3

Code Block

language	yml
title	Example Output
collapse	true

{
  "jw00212jw01039-o035o004_t007t001_miri_ch1ch3-long": [
 {
  "obsID": 5573015883209967,
  "obs_collection": "JWST",
  "obs_id": "jw00212jw01039-o035o004_t007t001_miri_ch1ch3-long",
  "dataproduct_type": "cube",
  "type": "D",
  "productType": "SCIENCE",
  "productGroupDescription": null"Minimum Recommended Products",
  "productSubGroupDescription": "X1DS3D",
  "productDocumentationURL": null,
  "project": "CALJWST",
  "prvversion": "1.15.03",
  "proposal_id": "002121039",
  "dataURI": "mast:JWST/product/jw00212jw01039-o035o004_t007t001_miri_ch1ch3-long_x1ds3d.fits",
  "productFilename": "jw00212jw01039-o035o004_t007t001_miri_ch1ch3-long_x1ds3d.fits",
  "description": "exposure/target (L2b/L3): 3D 1Dimage extractedof spectrum",
  "size": 141120370405440,
  "parent_obsid": 5573011683209967,
  "dataRights": "PUBLIC",
  "calib_level": 3,
  "exp_type": "MIR_MRS",
  "template": "MIRI MediumExternal Resolution SpectroscopyFlat"
 },
 {
  "obsID": 5573016383209967,
  "obs_collection": "JWST",
  "obs_id": "jw00212jw01039-o035o004_t007t001_miri_ch1ch3-mediumlong",
  "dataproduct_type": "cube",
  "type": "D",
  "productType": "SCIENCE", 
  "productGroupDescription": null"Minimum Recommended Products",
  "productSubGroupDescription": "X1D",
  "productDocumentationURL": null,
  "project": "CALJWST",
  "prvversion": "1.15.03",
  "proposal_id": "002121039",
  "dataURI": "mast:JWST/product/jw00212jw01039-o035o004_t007t001_miri_ch1ch3-mediumlong_x1d.fits",
  "productFilename": "jw00212jw01039-o035o004_t007t001_miri_ch1ch3-mediumlong_x1d.fits",
  "description": "exposure/target (L2b/L3): 1D extracted spectrum",
  "size": 135360190080,
  "parent_obsid": 55730116,
  "dataRights": "PUBLIC",
  "calib_level": 3,
  "exp_type": "MIR_MRS",
  "template": "MIRI Medium Resolution Spectroscopy"
 },
 {...},
 {...},
 {...},
 {...},
 {...},
 {...},
 {...},
 {...},
 {...},
 {...}
 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 Definition PortalDictionary.

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

Code Block

language	yml
title	Example Output
collapse	true

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

Code Block

language	yml
title	Example Output
collapse	true

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

language	yml
title	Example Output
collapse	true

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

Code Block

language	yml
title	Example Output
collapse	true

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

For Further Reading...

Using MAST APIs

Content

Space Tools

Versions Compared

Old Version 2

New Version 3

Key

The Jdaviz.MAST API

Basics of an API

Accessing Observation Parameters

Accessing Science Instrument Keywords

Accessing Related Data Products

Accessing Metadata Information

Science Instrument Keywords

Engineering Mnemonics

For Further Reading...