API Access

The ALeRCE API Wrapper gives an easy access to ALeRCE services with python.

from alerce.api import AlerceAPI
alerce = AlerceAPI()
class alerce.api.AlerceAPI(**kwargs)[source]

ALeRCE API Wrapper.

Parameters:
ztf_url : str

URL for ALeRCE ZTF data access API. (default ALeRCE current url).

catsHTM_url : str

URL for catsHTM service. (default ALeRCE current url).

Methods

catsHTM_conesearch(self, oid, radius[, …]) catsHTM conesearch given an object and catalog_name.
catsHTM_crossmatch(self, oid[, radius, …]) catsHTM crossmatch given an object and catalog_name.
catsHTM_redshift(self, oid, radius[, format]) Get redshift given an object.
get_detections(self, oid[, format]) Get detections for an object.
get_features(self, oid[, format]) Get features given object.
get_non_detections(self, oid[, format]) Get Non detections for an object.
get_probabilities(self, oid[, early, late, …]) Get probabilities for a given object.
get_sql(self, params) Get the SQL statement executed on the database given a set of filters
get_stamps(self, oid[, candid]) Download Stamps for an specific alert.
get_stats(self, oid[, format]) Get object aggregated statistics.
plot_stamp(self, oid[, candid]) Plot stamp in a notebook given oid.
query(self, params[, format]) Query the ALeRCE API to get matching objects into a pandas dataframe.
catsHTM_conesearch(self, oid, radius, catalog_name='all', format='votable')[source]

catsHTM conesearch given an object and catalog_name.

Parameters:
oid : str

object ID in ALeRCE DBs.

catalog_name : str

catsHTM Catalog name, “all” can be used to query all available catalogs. List of available catalogs can be found in here.

radius : float

Conesearch radius in arcsec.

format : str

Output format [votable|pandas]

Returns:
dict

Dictionary with the following structure: {

}

catsHTM_crossmatch(self, oid, radius=100, catalog_name='all', format='votable')[source]

catsHTM crossmatch given an object and catalog_name.

Parameters:
oid : str

object ID in ALeRCE DBs.

catalog_name : str

catsHTM Catalog name, “all” can be used to query all available catalogs. List of available catalogs can be found in here.

radius : float

Crossmatch radius in arcsec. (Default 100 arcsec)

format : str

Output format [votable|pandas]

Returns:
dict

Dictionary with the following structure: {

}

catsHTM_redshift(self, oid, radius, format='votable')[source]

Get redshift given an object.

Parameters:
oid : str

object ID in ALeRCE DBs.

radius : float

catsHTM conesearch radius in arcsec.

format : str

Output format [votable|pandas]

Returns:
float

Check if redshift is in a catsHTM xmatch response.

get_detections(self, oid, format='votable')[source]

Get detections for an object.

Parameters:
oid : str

object ID in ALeRCE DBs.

format : str

Output format [votable|pandas]

Returns:
astropy.table.Table or pandas.DataFrame

VoTable or DataFrame with detections.

The schema used is the same as ZTF (schema), also the fields with _corr suffix are corrected magnitudes with the object reference magnitude.

get_features(self, oid, format='votable')[source]

Get features given object.

Parameters:
oid : str

object ID in ALeRCE DBs.

format : str

Output format [votable|pandas]

Returns:
astropy.table.Table or pandas.Series

Features calculated for the late classification.

get_non_detections(self, oid, format='votable')[source]

Get Non detections for an object.

Parameters:
oid : str

object ID in ALeRCE DBs.

format : str

Output format [votable|pandas]

Returns:
astropy.table.Table or pandas.DataFrame

VoTable or DataFrame with non detections.

get_probabilities(self, oid, early=True, late=True, format='votable')[source]

Get probabilities for a given object.

Parameters:
oid : str

object ID in ALeRCE DBs.

early : bool

Get probabilities from Early Classifier.

late : bool

Get probabilities from Late Classifier.

format : str

Output format [votable|pandas]

Returns:
dict
:py:class:`dict`ionary with the following structure:
{

“early”: astropy.table.Table or pandas.Series,

“late”: astropy.table.Table or pandas.Series

}

get_sql(self, params)[source]

Get the SQL statement executed on the database given a set of filters

Parameters:
params : dict

Same parameters used in alerce.api.AlerceAPI.query()

Returns:
string

SQL Statement.

get_stamps(self, oid, candid=None)[source]

Download Stamps for an specific alert.

Parameters:
oid : str

object ID in ALeRCE DBs.

candid : int (default First Stamps)

Candid of the stamp to be displayed, if not set shows the Discovery stamp (first one).

Returns:
astropy.io.fits.HDUList

Science, Template and Difference stamps for an specific alert.

get_stats(self, oid, format='votable')[source]

Get object aggregated statistics.

Parameters:
oid : str

object ID in ALeRCE DBs.

format : str

Output format [votable|pandas]

Returns:
astropy.table.Table or pandas.Series

VoTable or Series with the object statistics.

plot_stamp(self, oid, candid=None)[source]

Plot stamp in a notebook given oid. It uses IPython HTML.

Parameters:
oid : str

object ID in ALeRCE DBs.

candid : int

Candid of the stamp to be displayed, if not set shows the Discovery stamp (first one).

Returns:
Display the stamps on a jupyter notebook.
query(self, params, format='votable')[source]

Query the ALeRCE API to get matching objects into a pandas dataframe.

Parameters:
params : dict

Dictionary of parameters for the API. The current fields to query the db are the following:

{
total: number (if not set the total is counted and the query is slower),
records_per_pages: number (default 20),
page: number (default 1),
sortBy: :py:class:`str` columnName (default nobs),
query_parameters:{
   filters:{
      //ZTF object id
      oid: "ZTFXXXXXX",
      //Number of detections
      nobs: {
          min: int
          max: int
      },
      //Late Classifier (Random Forest)
      classrf: string or int,
      pclassrf: float [0-1],
      //Early Classifier (Stamp Classifier)
      classearly: list, string or int,
      pclassearly: float [0-1],
      },
      //Coordinate based search (RA,DEC) and Search Radius.
      coordinates:{
        ra: float degrees,
        dec: float degrees,
        sr: float degrese
        },
      dates:{
      //First detection (Discovery date)
      firstmjd: {
         min: float mjd,
         max: float mjd
        }
      }
   }
}

for a more updated available fields check ZTF API documentation

format : str

Output format [votable|pandas]

Returns:
astropy.table.Table or pandas.DataFrame

The response contains the objects matching the filtering parameters with their statistics.