API tools

There are a number of tools provided at https://grizli-cutout.herokuapp.com/ for interacting with the DJA database, for example, making image thumbnails and querying for processed exposures that touch a particular sky location.

In general, query centers can be specified either as decimal degrees or HMSDMS sexagesimal strings, either with separate ?ra=&dec= parameters or with coords=0.000,0.000 and with the latter separated by either a comma or whitespace, e.g.,

Imaging

The DJA provides reduced Hubble and JWST imaging data from many observing programs covering many different fields, from rich survey fields like COSMOS to individual pointings on targeted sources. Quick access to the imaging metadata is necessary for many different analysis applications.

Association metadata

DJA defines its own exposure associations essentially split by program, epoch, instrument, filter, detector, and these associations are the basic processing unit of the imaging data analysis. That is, the assocation exposures are aligned relative to one-another and to an external astrometric reference, multiple overlapping exposures are used to identify additional bad pixels and cosmic rays, etc. The JWST association queries are generally specified manually, so not every existing observation is necessarily in the DJA database. Furthermore, while an association may be defined, it may not necessarily have been processed, e.g., for proprietary data. Associations with status=2 in the query results below have generally been processed successfully.

The API query assoc?ra=34.405&dec=-5.22487&arcmin=1 returns a table of metadata for associations close to a specified position within a specified tolerance. The default returns a readable HTML table.

Specifying …&output=csv returns tabular data that can be read directly with, e.g., astropy or pandas:

Specifying …&output=figure returns a PNG figure:

output=figure	&polygon=rect(34.405,-5.22487,1)	&instruments=NIRCAM&filters=F200W-CLEAR,F444W-CLEAR

Exposure metadata

The positions of the data in the associations database are taken directly from the MAST metadata for a particular dataset. Similar to querying the association metadata, it is also possible to perform direct spatial queries using the explicit footprints of discrete exposures in the database. This is more precise for answering a specific question like, “what is the total F090W-CLEAR exposure time at position (34.405,-5.22487)?”.

The exposures?ra=34.405&dec=-5.22487&arcmin=1 API query has many of the same functionality as the assoc query. By default the result is a list of individual exposures that include the specified position.

Here the default is machine-readable CSV (below) and &output=table provides a more readable HTML table.

Figure output:

output=figure	&polygon=rect(34.405,-5.22487,1)	&instruments=NIRCAM&filters=F200W-CLEAR,F444W-CLEAR

Processed data by epoch

The assoc_mosaic tool provides an extension to the assoc queries to help identify distinct observing epochs that cover a particular position, e.g., for transient searches. Note that here only coords specification is implemented, as

• coords=ra,dec
• coords=ra,dec,box_arcmin
• coords=ra,dec,width_arcmin,height_arcmin

&filters=F444W-CLEAR&round_epoch=5	&filters=F444W-CLEAR&round_epoch=30 (epochs grouped over 30 days)

The table outputs include links to sub-mosaics created from the exposures of a particluar association. The sub-mosaics of the associations at roughly the same part of the sky are drizzled to a common tangent point such that they can be combined or differenced using integer pixel slices without the need for any resampling. Though not returned in the table, there are inverse variance images available corresponding to each science image that can be retrieved modifying the file URLs sci.fits.gz → wht.fits.gz.

file	assoc_name	filter	modtime	tile	pixscale_mas	detector	version	status	nexp	visit	instrument	exptime	expstart	sky	ra	dec	t_obs_release	footprint	dateobs	preview
j021744m0514_unknown-f444w_00287-f444w-clear_drc_sci.fits.gz	j021744m0514_unknown-f444w_00287	F444W-CLEAR	2025-04-22 18:05:13	1183	40	NRCALONG	v7.0	2	2	jw01837001006	NIRCAM	837.5	59960.59	0.45	34.407724	-5.263120	59961.297939814816	POLYGON((34.39704,-5.286045),(34.430714,-5.2733455),(34.41859,-5.240085),(34.384377,-5.252073)) POLYGON((34.39706,-5.2865286),(34.430733,-5.273829),(34.41861,-5.2405686),(34.384396,-5.252557))	2023-01-16 14:15:21
j021744m0514_unknown-f444w_00291-f444w-clear_drc_sci.fits.gz	j021744m0514_unknown-f444w_00291	F444W-CLEAR	2025-04-22 17:57:14	1183	40	NRCBLONG	v7.0	2	2	jw01837001006	NIRCAM	837.5	59960.59	0.43	34.391558	-5.217158	59961.31527777778	POLYGON((34.38065,-5.240183),(34.414635,-5.2274103),(34.402393,-5.1941385),(34.368366,-5.206002)) POLYGON((34.38067,-5.240667),(34.414658,-5.227895),(34.402412,-5.1946225),(34.368385,-5.206486))	2023-01-16 14:15:21
…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…	…

Image cutouts

https://grizli-cutout.herokuapp.com/thumb?ra=34.4048289&dec=-5.22487 generates thumbnail cutouts in any HST or JWST dataset that has been processed in the DJA. The default URL returns images as below, and the options thumb?output=fits or thumb?output=fits_weight provide FITS cutouts with optional inverse variance WHT extensions.

The monochrome and RGB scaling is generated on the fly with parameters demonstrated below. The images below are generated from the API itself and may take a bit of time to load if the API VM needs to spin up.

default_filters=hst (f814w,f125w,f160w)	thumb?default_filters=jwst (f115w,f277w,f444w)	default_filters=jwst&rgb_min=0.0 (rgb_min black point)	default_filters=jwst&asinh=True (asinh scaling instead of Lupton 2004)
filters=f090w-clear,f115w-clear,f150w-clear	filters=f090w-clear,f115w-clear,f150w-clear&rgb_scl=1.0,2.0,1.01	filters=f090w-clear,f115w-clear,f150w-clear&pl=1	filters=f115w-clear,f150w-clear,f200w-clear&pl=1
filters=f115w-clear&size=2 (default size=4 arcsec)	filters=f115w-clear&invert=True	filters=f115w-clear&invert=True&scl=4.0	filters=f115w-clear&invert=True&scl=0.2

default_filters=jwst&all_filters=True

filters=f090w-clear,f115w-clear,f150w-clear,f200w-clear,f277w-clear,f356w-clear,f444w-clear&all_filters=True&rgb_scl=1.4,0.7,1.2

Draw NIRspec slits from the database: coords=34.2775,-5.2282&nirspec=True	Highlight shutters from a particular MSA plan: nirspec=True&metafile=jw04233001002	Draw an arbitrary slit (see the image URLs for additional parameters): thumb?slit={ra},{dec},{length_arcsec},{width_arcsec},{PA}

Spectroscopy

The DJA includes a large and growing compilation of multi-object spectroscopy from NIRSpec. The [nirspec-merged-table-v4](https://dawn-cph.github.io/dja/blog/2025/05/01/nirspec-merged-table-v4/ post describes the recent large release of ~80,000 NIRspec MSA spectra. The API provides some functionality for querying the spectroscopy database.

NIRSpec MSA slits

The last image cutout example above shows how the thumbnails can include an overlay of the NIRSpec MSA shutters that may cover a particluar position. The shutter footprint data can be retrieved with nirspec_slits?coords=34.2775,-5.2282&size=1, where size is the query radius in arcsec.

The default output is CSV data:

The &count=True&output=json option returns a summary collated by program and grating (output as CSV or JSON):

{
    "program":{"0":4233,"1":4233},
    "count":{"0":10,"1":10},
    "grating":{"0":"PRISM","1":"G395M"},
    "filter":{"0":"CLEAR","1":"F290LP"}
}

Extracted NIRSpec MSA spectra

If the shutters above correspond to public data that have been processes by the DJA, the spectra themselves can be queried with nirspec_extractions?coords=34.2775,-5.2282&size=0.4&output=csv:

The nirspec_extractions?…&output=html option gives a human-readable table that also includes the spectrum preview images and links to download the spectrum FITS files. The locations of the preview images and FITS products have the filename patterns below, where prefix is the part of file before the “.spec.fits” extension.

Pattern	Product
https://s3.amazonaws.com/msaexp-nirspec/extractions/{root}/{file}	rubies-uds3-v4_prism-clear_4233_50352.spec.fits
https://s3.amazonaws.com/msaexp-nirspec/extractions/{root}/{prefix}.fnu.png
https://s3.amazonaws.com/msaexp-nirspec/extractions/{root}/{prefix}.flam.png

Individual MSA spectrum redshifts

The nirspec_file_redshift?file=… query gives a summary of the redshift estimate associated with a particular spectrum:

The redshifts are populated based on the table merging potentially multiple observations of a unique source. These may be more reliable than the redshift fits for the spectrum itself, e.g., where there are no strong features in a particular spectrum but where another spectrum of the same source (e.g., deeper or in a different grating) better constrains the redshift.

MSA trace overlaps

Some MSA programs such as RUBIES (GO-4233) explicitly allow overlapping grating spectra, which can result in ambiguous contamination and line identifications. The /nirspec_trace_overlap?spec_file=rubies-uds3-v4_prism-clear_4233_50352.spec.fits API query provides some diagnostics of traces that may overlap with the one of interest. The default query returns a figure of the traces that may overlap with the primary object associated with the file:

The primary trace is shown in black and the overlaps are shown in the curved colored lines. (The example is from RUBIES, which potentially allows a lot of overlaps!).

The overlap data can be retrieved programmatically with &output=json:

{
    "spec_file": "rubies-uds3-v4_prism-clear_4233_50352.spec.fits",
    "yoffset": {
        "4233_49731": 25.009008473508857
        "4233_52910": 13.180923825151922
        "4233_44376": 12.905045711645016
        "4233_51139": 9.516967793545064
        "4233_47720": 5.294313204489072
        "4233_48507": -14.63311231132775
        "4233_46885": -15.269179055199402
        "4233_46566": -15.537329521182642
        "4233_45469": -26.484612871712784
        "4233_46145": -25.87319624823249
        "4233_45210": -31.936282457944003
    }
}

The closest trace to that of the primary source (4233_50352) is 4233_47720, about 5 pixels ~ 1 shutter away. Source 4233_47720 is significantly fainter than 4233_50352, and indeed there is an apparent signature of the latter contaminating the fainter source in its own diagnostic figure:

Legacy MOSFIRE spectra

Much of the archival MOSFIRE data were processed prior to JWST launch and are available within the DJA interface. These have not been revisited much since the advent of the rich JWST spectra, but the processed MOSFIRE reductions can be queried with the mosfire? tool. The output isn’t as well developed as the other queries above, but a JSON version of the query data can be retrieved with mosfire?…&mode=json:

[
    {
        "ra_targ": 34.405167,
        "dec_targ": -5.224939,
        "datemask": "UDS_field_new4_20160128",
        "progpi": "mosfireeng",
        "target_name": "lensed_target",
        "filter": "H",
        "wmin": 14616.5,
        "wmax": 17898.85,
        "exptime": 7157.6,
        "file": "UDS_field_new4_20160128/Reduced/UDS_field_new4/2016jan28/H/UDS_field_new4_20160128-H-slit_12-lensed_target_sp.fits",
        "slit_width": 0.7,
        "slit_length": 15.1,
        "skypa3": 10.0,
        "ra_slit": 34.405,
        "dec_slit": -5.22575
    },
    {
        "ra_targ": 34.405167,
        "dec_targ": -5.224236,
        "datemask": "UDSK1_20160118",
        "progpi": "Scoville",
        "target_name": "DM_uds_9612",
        "filter": "K",
        "wmin": 19681.02,
        "wmax": 24050.97,
        "exptime": 2147.3,
        "file": "UDSK1_20160118/Reduced/UDSK1/2016jan18/K/UDSK1_20160118-K-slit_13-DM_uds_9612_sp.fits",
        "slit_width": 0.7,
        "slit_length": 22.8,
        "skypa3": 39.0,
        "ra_slit": 34.403875,
        "dec_slit": -5.225817
    }
 ]

The file entries listed in the query result are available at https://s3.amazonaws.com/mosfire-pipeline/Spectra/{file}.

For DJA questions, please use the Discussions or Issues functionality on the repository page.

For grizli or msaexp software questions or problems, please file an Issue on the respective GitHub repository pages.

• Cosmic Dawn Center
  Niels Bohr Institute
  University of Copenhagen
  Jagtvej 128, 2200 København N