Web API¶

Blast provides an HTTP application programming interface (API) for fetching data programmatically. The API allows queries on individual data objects associated with a transient, as well as fetching all data for a given transient.

Downloading all Blast data for a given transient¶

A transient dataset is the complete set of information associated with a transient: it consists of the information stored in Blast database objects and associated data files, such as the cutout images and the SED fit files.

A full transient dataset can be exported using /api/transient/export/<transient_name>/all, which packages the data into a compressed archive file (standard .tar.gz format) that the user downloads.

There are currently two API endpoints that return all tabular data associated with a transient (i.e. data stored as text instead of as binary files) as a JSON-formatted document:

/api/transient/get/<transient_name>?format=json

The structure, or schema, of the document returned by this endpoint is detailed in the Science payload data schema section below. It is a relatively flat hierarchy.

Here is an example Python snippet to load data as a Python dictionary for the transient 2026dix.
```
from urllib.request import urlopen
import json

response = urlopen('<base_blast_url>/api/transient/get/2026dix?format=json')
data = json.loads(response.read())
```
/api/transient/export/<transient_name>

The schema of the document returned by this endpoint serializes transient-associated objects more closely to the internal models (see models.py). It was designed is to capture a transient dataset in a self-contained way amenable to import into any Blast instance. The result is a more hierarchical structure, but one with static keys and less redundancy that also supports simpler parsing algorithms. The schema includes additional related objects: cutouts, surveys, and filters. Although the surveys and filters exist independently of a particular transient, they are included because transient cutout objects are associated with filters associated with surveys.

Downloading individual Blast data objects¶

Internally, Blast defines a set of data models (transient, host, aperture, etc.) that define the structure of objects associated with an astronomical transient.

There are API endpoints to fetch these objects from the Blast database, with URLs of the form /api/<model_name> (e.g. /api/host). Each of these functions, detailed below, offers filtering options that narrow the scope of the returned results (e.g. /api/host/?redshift_gte=4&format=json). As the Blast database continues to grow, requesting all objects by omitting filters is discouraged.

As a concrete example, here is a Python script that will fetch the transient database object associated with the transient 2026dix:

from urllib.request import urlopen
import json

response = urlopen('<base_blast_url>/api/transient/?name=2026dix&format=json')
data = json.loads(response.read())

This returns a JSON document like:

[
  {
     "id": 76390,
     "ra_deg": 177.6559502,
     "dec_deg": 55.3535889,
     "name": "2026dix",
     "display_name": null,
     "public_timestamp": "2026-02-16T09:26:15.072000Z",
     "redshift": 0.003185,
     "spectroscopic_class": "SN IIb",
     "milkyway_dust_reddening": 0.0110031844861805,
     "progress": 100,
     "software_version": "1.8.7",
     "host": {
       "id": 92200,
       "ra_deg": 177.662201,
       "dec_deg": 55.353867,
       "name": "NGC3913",
       "redshift": 0.0041580065070319,
       "redshift_err": 0.0012474019521095,
       "photometric_redshift": null,
       "photometric_redshift_err": null,
       "milkyway_dust_reddening": 0.011014966275543,
       "software_version": "1.8.7"
     }
  }
]

Manage aliases for Transient and Host objects¶

Authorized users can associate an arbitrary number of aliases to Transient and Host objects. The alias itself must be unique across both types of target objects.

GET /api/alias/<alias>/ - Fetch information about an existing alias
DELETE /api/alias/<alias>/ - Delete existing alias
POST /api/alias/<alias>/(transient|host)/<name>/ - Create a new alias by specifying
the name of the target object and whether the target object is a “transient” or a “host”.

Blast API data schema¶

Each API endpoint for fetching the various Blast data objects, along with its response data schema, is described below. Foreign key-linked fields are also displayed to simplify API calls; for example, the attributes of the associated Host are returned in addition to the Transient fields when a given transient is queried.

Transient fields¶

API link: /api/transient/

name - name of the transient e.g., 2022abc
ra_deg - transient Right Ascension in decimal degrees e.g., 132.34564
dec_deg - transient declination in decimal degrees e.g., 60.123424
redshift - transient redshift e.g., 0.01
milkyway_dust_reddening - transient E(B-V) e.g, 0.2
processing_status - Blast processing status of the transient.
“processed” - transient has been complement processed by Blast and all data should be present in the science payload. “processing” - Blast is still processing this transient and some parts of the science payload may not be populated at the current time. “blocked” - this transient has not been successfully fully processed by Blast and some parts of the science payload will not be populated.
spectroscopic_class - spectroscopic classification, if any
host - foreign key link to the Host object, described below.

Transient filtering options¶

name= - search on transient name
redshift_gte= - filter on redshifts greater than or equal to the value provided
redshift_lte= - filter on redshifts less than or equal to the value provided
host_redshift_gte= - filter on host redshifts greater than or equal to the value provided
host_redshift_lte= - filter on host redshifts less than or equal to the value provided
host_photometric_redshift_gte= - filter on host photometric redshifts greater than or equal to the value provided
host_photometric_redshift_lte= - filter on host photometric redshifts less than or equal to the value provided

Example: <blast_base_url>/api/transient/?redshift_gte=0.02

Host fields¶

API link: /api/host/

name - name of the host e.g., NGC123
ra_deg - host Right Ascension in decimal degrees e.g., 132.34564
dec_deg - host declination in decimal degrees e.g., 60.123424
redshift - host redshift e.g., 0.01
milkyway_dust_reddening - host E(B-V) e.g, 0.2
object_id - Object ID provided by the host matcher from the external catalog
catalog_name - Name of the external catalog containing the associated host information
catalog_release - Specific release of the external catalog containing the associated host information

Host filtering options¶

name= - search on host name
redshift_gte= - filter on redshifts greater than or equal to the value provided
redshift_lte= - filter on redshifts less than or equal to the value provided
photometric_redshift_gte= - filter on photometric redshifts greater than or equal to the value provided
photometric_redshift_lte= - filter on photometric redshifts less than or equal to the value provided

Example: <blast_base_url>/api/host/?photometric_redshift_lte=0.02

Aperture fields¶

API link: /api/aperture/

ra_deg - aperture Right Ascension in decimal degrees e.g., 132.3456
dec_deg - aperture declination in decimal degrees e.g., 60.123424
orientation_deg - orientation angle of the aperture in decimal degrees e.g., 30.123
semi_major_axis_arcsec - semi major axis of the aperture in arcseconds
semi_minor_axis_arcsec - semi minor axis of the aperture in arcseconds
cutout - link to the Cutout object used to create aperture, described below
type - “local” or “global” aperture

Aperture filtering options¶

transient= - select apertures associated with a given transient name

Example: <blast_base_url>/api/aperture/?transient=2010H

AperturePhotometry fields¶

API link: /api/photometry/

flux - Aperture photometry flux in mJy
flux_error - Aperture photometry flux error in mJy
magnitude - Aperture photometry magnitude
magnitude_error - Aperture photometry magnitude error
aperture - link to Aperture object, described above
filter - link to photometric Filter object
transient - link to Transient object
is_validated - checks on contaminating objects in the aperture (global apertures only) or ability to resolve 2 kpc in physical scale (local apertures only)

Photometry filtering options¶

transient= - select aperture photometry associated with a given transient
filter= - select aperture photometry associated with a given photometric filter name

Example: <blast_base_url>/api/aperturephotometry/?filter=H

SEDFittingResult fit fields¶

API link: /api/sedfittingresult/

<aperture_type> can either be “local” or “global”. <parameter> can be either,

“log_mass” (log base 10 of the surviving host stellar mass [solar masses])
“log_sfr” (log base 10 of the host star formation rate [solar masses / year])
“log_ssfr” (log base 10 of the host specific star formation rate [/ year])
“log_age” (host stellar age [gigayear]) (DEPRECATED, use “age”)
“age” (host stellar age [gigayear])

<posterior_percentile> is the percentile value from the posterior distribution which can either be “16”, “50” ot “84”

mass_surviving_ratio - ratio of the surviving stellar mass to the total formed stellar mass
<aperture_type>_aperture_host_<parameter>_<posterior_percentile>
transient - link to Transient object
aperture - link to Aperture object
chains_file - MCMC chains for each parameter; files can be downloaded with the URL path <base_blast_url>/download_chains/<transient_name>/<aperture_type>
percentiles_file - 16,50,84th percentiles for all parameters in the prospector-alpha model; files can be downloaded with the URL path <base_blast_url>/download_percentiles/<transient_name>/<aperture_type>
model_file - best-fit spectrum, photometry, and uncertainties (downloaded in units of maggies); files can be downloaded with the URL path <base_blast_url>/download_modelfit/<transient_name>/<aperture_type>

SED filtering options¶

transient= - select SED fitting results associated with a given transient
aperture_type= - select “global” or “local” SED fitting results

Example:

<blast_base_url>/api/sedfittingresult/?transient=2010H
<blast_base_url>/api/sedfittingresult/?aperture_type=local

Cutout fields¶

API link: /api/cutout/

name - the name of the cutout object transient - link to Transient object filter - link to photometric Filter object

Cutout filtering options¶

transient - select cutout images associated with a given transient
filter - select cutout images in a given photometric filter

Example: <blast_base_url>/api/cutout/?transient=2010H

Task fields¶

API link: /api/task/

name - name of each task

TaskRegister fields¶

API link: /api/taskregister/

task - link to Task object
status - link to Status object, which contains messages like “processed” or “failed”
transient - link to Transient object
user_warning - see if user has flagged a given stage as problematic (true/false)

TaskRegister filtering options¶

transient - check the status of tasks for a given transient
status - search for all tasks with status “failed”, for example
task - look for all instances of a given task

Example: <blast_base_url>/api/taskregister/?status=failed

Science payload data schema¶

The data schema for the JSON-formatted response of the API endpoint /api/transient/get/<transient_name>?format=json contains the components detailed in subsections below. Field names differ slightly from those in the API data schema above for the sake of clarity.

Transient fields¶

transient_name - name of the transient e.g., 2022abc
transient_ra_deg - transient Right Ascension in decimal degrees e.g., 132.34564
transient_dec_deg - transient declination in decimal degrees e.g., 60.123424
transient_redshift - transient redshift e.g., 0.01
transient_milkyway_dust_reddening - transient E(B-V) e.g, 0.2
transient_processing_status - Blast processing status of the transient.
“processed” - transient has been complement processed by Blast and all data should be present in the science payload. “processing” - Blast is still processing this transient and some parts of the science payload may not be populated at the current time. “blocked” - this transient has not been successfully fully processed by Blast and some parts of the science payload will not be populated.

Host fields¶

host_name - name of the host e.g., NGC123
host_ra_deg - host Right Ascension in decimal degrees e.g., 132.34564
host_dec_deg - host declination in decimal degrees e.g., 60.123424
host_redshift - transient redshift e.g., 0.01
host_milkyway_dust_reddening - host E(B-V) e.g, 0.2

Aperture fields¶

<aperture_type> can either be “local” or “global”.

<aperture_type>_aperture_ra_deg - aperture Right Ascension in decimal degrees e.g., 132.3456
<aperture_type>_aperture_dec_deg - aperture declination in decimal degrees e.g., 60.123424
<aperture_type>_orientation_deg - orientation angle of the aperture in decimal degrees e.g., 30.123
<aperture_type>_semi_major_axis_arcsec - semi major axis of the aperture in arcseconds
<aperture_type>_semi_minor_axis_arcsec - semi minor axis of the aperture in arcseconds
<aperture_type>_cutout - name of the cutout used to create aperture e.g, 2MASS_H, None if not cutout was used

Photometry fields¶

<aperture_type> can either be “local” or “global”. <filter> can be any of the filters Blast downloads cutouts for e.g., 2MASS_H, 2MASS_J, SDSS_g … . If the data for a particular filter and transient does not exist the values will be None.

<aperture_type>_aperture_<filter>_flux - Aperture photometry flux in mJy
<aperture_type>_aperture_<filter>_flux_error - Aperture photometry flux error in mJy
<aperture_type>_aperture_<filter>_magnitude - Aperture photometry magnitude
<aperture_type>_aperture_<filter>_magnitude_error - Aperture photometry magnitude error

SED fit fields¶

<aperture_type> can either be “local” or “global”. <parameter> can be either,

“log_mass” (log base 10 of the host stellar mass [solar masses])
“log_sfr” (log base 10 of the host star formation rate [solar masses / year])
“log_ssfr” (log base 10 of the host specific star formation rate [/ year])
“log_age” (log base 10 of the host stellar age [year])
“log_tau” (log base 10 of the host star formation rate decline exponent [year])

<posterior_percentile> is the percentile value from the posterior distribution which can either be “16”, “50” ot “84”

<aperture_type>_aperture_host_<parameter>_<posterior_percentile>