API Reference

The ALeRCE Client provides a unified interface for querying astronomical data from multiple surveys.

Getting Started

Import and instantiate the client:

from alerce.core import Alerce

client = Alerce()

Note

Important: Survey Parameter

Most methods now require a survey parameter to specify which survey data to query. Currently supported surveys: "ztf" and "lsst".

While some methods still default to "ztf" for backward compatibility, this behavior is deprecated and will be removed in future versions. Always specify the survey explicitly.

ALeRCE Client

class alerce.Alerce(**kwargs)[source]

Bases: AlerceCommonSearch, AlerceXmatch, AlerceCommonStamps

The ALeRCE Client for accessing astronomical data from multiple surveys.

This is the main entry point for the ALeRCE Python Client. It provides unified access to query astronomical objects, photometry, classifications, stamps, and perform crossmatching operations across multiple surveys.

Methods

`catshtm_conesearch`(ra, dec, radius[, ...])	catsHTM conesearch given an object and catalog_name.
`catshtm_crossmatch`(ra, dec, radius[, ...])	catsHTM crossmatch given an object and catalog_name.
`catshtm_redshift`(ra, dec, radius[, format, ...])	Get redshift given an object.
`get_avro`(oid[, candid, use_multisurvey_api, ...])	Download avro of some alert.
`get_stamps`(oid[, candid, measurement_id, ...])	Download Stamps for a specific alert.
`plot_stamps`(oid[, candid, measurement_id, ...])	Plot stamp in a notebook given oid.
`query_classes`(classifier_name, ...[, ...])	Gets classes from a specified classifier
`query_classifiers`([format, survey])	Gets all classifiers and their classes
`query_detections`(oid[, format, survey, ...])	Gets all detections of a given object
`query_feature`(oid, name[, format, survey])	Gets a single feature of a specified object id
`query_features`(oid[, format, survey, index, ...])	Gets features of a given object
`query_forced_photometry`(oid[, format, ...])	Gets all forced photometry of a given object
`query_lightcurve`(oid[, format, survey])	Gets the lightcurve (detections and non_detections) of a given object
`query_magstats`(oid[, format, survey, index, ...])	Gets all magnitude statistics of a given object
`query_non_detections`(oid[, format, survey, ...])	Gets all non detections of a given object
`query_object`(oid[, format, survey])	Gets a single object by object id
`query_objects`([format, index, sort, survey])	Gets a list of objects filtered by specified parameters.
`query_probabilities`(oid[, format, survey, ...])	Gets all probabilities of a given object

catshtm_catalog_translator
load_config_from_object

See also

migration_guide: Guide for migrating to the multi-survey API

Notes

Most methods require a survey parameter to specify which survey’s data to query. Currently supported surveys are “ztf” and “lsst”. While some methods still default to “ztf” for backward compatibility, this behavior is deprecated and will be removed in future versions. Always explicitly specify the survey parameter.

Examples

Basic usage:

>>> from alerce.core import Alerce
>>> client = Alerce()

Query objects from ZTF:

>>> objects = client.query_objects(
...     survey="ztf",
...     ra=10.0,
...     dec=-20.0,
...     radius=30
... )

Get a lightcurve:

>>> lc = client.query_lightcurve("ZTF21aaeyldq", survey="ztf")

Retrieve stamps:

>>> stamps = client.get_stamps(
...     oid="ZTF21aaeyldq",
...     candid=1234567890,
...     survey="ztf"
... )

catshtm_catalog_translator(catalog)

catshtm_conesearch(ra, dec, radius, catalog_name='all', format='pandas')

catsHTM conesearch given an object and catalog_name.

Parameters:

rafloat: Right ascension in Degrees.
decfloat: Declination in Degrees.
catalog_namestr: catsHTM Catalog name. Use “all” to query all available catalogs. A list of available catalogs can be found on the catsHTM docs.
radiusfloat: Conesearch radius in arcsec.
formatstr: Output format: “votable” or “pandas”.

Returns:

:
dict or astropy.table.Table or pandas.DataFrame or None: If catalog_name is “all”, returns a dictionary mapping catalog name to an astropy Table or pandas DataFrame. If a single catalog is requested, returns the Table/DataFrame for that catalog. Returns None when an empty response is received for a single catalog.

catshtm_crossmatch(ra, dec, radius, catalog_name='all', format='pandas')

catsHTM crossmatch given an object and catalog_name.

Parameters:

rafloat: Right ascension in Degrees.
decfloat: Declination in Degrees.
catalog_namestr: catsHTM Catalog name. Use “all” to query all available catalogs. A list of available catalogs can be found on the catsHTM docs.
radiusfloat: Crossmatch radius in arcsec.
formatstr: Output format: “votable” or “pandas”.

Returns:

:
dict or astropy.table.Table or pandas.Series: If catalog_name is “all”, returns a dictionary mapping catalog name to an astropy Table or pandas DataFrame/Series. If a single catalog is requested, returns the Table/Series for that catalog.

catshtm_redshift(ra, dec, radius, format='votable', verbose=False)

Get redshift given an object.

Parameters:

rafloat: Right ascension in Degrees.
decfloat: Declination in Degrees.
radiusfloat: catsHTM conesearch radius in arcsec.
formatstr: Output format: “votable” or “pandas”.

Returns:

:
float or None: Redshift value if found in crossmatch results; otherwise None.

get_avro(oid, candid=None, use_multisurvey_api=False, survey=None)

Download avro of some alert.

Parameters:

oidstr: Object ID in ALeRCE DBs.
candidint, optional: Candid of the avro to be downloaded. If None, uses the first detection.
use_multisurvey_apibool: If True, uses the multisurvey API. Requires survey parameter.
surveystr, optional: The survey to query. Required when use_multisurvey_api is True.

Returns:

:
bytes: Avro data of a given alert.

Raises:

ValueError: If use_multisurvey_api is True and survey is not provided.
NotImplementedError: If multisurvey get_avro is not implemented.

get_stamps(oid, candid=None, measurement_id=None, format='HDUList', survey=None)

Download Stamps for a specific alert.

Parameters:

oidstr: Object ID in ALeRCE DBs.
candidint, optional: Candid of the stamp to be downloaded. If None, uses the first detection.
measurement_idint, optional: Alias for candid parameter (for multisurvey compatibility).
formatstr: Output format. Options: ‘HDUList’ | ‘numpy’
surveystr, optional: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).

Returns:

:
HDUList or list: Science, Template and Difference stamps for a specific alert. Returns HDUList if format=’HDUList’, otherwise list of numpy arrays.

Raises:

ValueError: If the survey is not in the list of valid surveys.

load_config_from_object(object)

plot_stamps(oid, candid=None, measurement_id=None, survey=None)

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

Parameters:

oidstr: Object ID in ALeRCE DBs.
candidint, optional: Candid of the stamp to be displayed. If None, uses the first detection.
measurement_idint, optional: Alias for candid parameter (for multisurvey compatibility).
surveystr, optional: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).

Returns:

:
None: Displays the stamps on a jupyter notebook.

Raises:

ValueError: If the survey is not in the list of valid surveys.

query_classes(classifier_name, classifier_version, format='json', survey=None, **kwargs)

Gets classes from a specified classifier

Parameters:

classifier_namestr: The classifier unique name
classifier_versionstr: The classifier’s version
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
**kwargs: Additional keyword arguments for the multisurvey API

Returns:

:
The classes data in the specified format

query_classifiers(format='json', survey=None, **kwargs)

Gets all classifiers and their classes

Parameters:

formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
**kwargs: Additional keyword arguments for the multisurvey API

Returns:

:
The classifiers data in the specified format

query_detections(oid, format='json', survey=None, index=None, sort=None)

Gets all detections of a given object

Parameters:

oidstr | int: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The detections data in the specified format

query_feature(oid, name, format='json', survey=None)

Gets a single feature of a specified object id

Parameters:

oidstr: The object identifier
namestr: The feature’s name
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).

Returns:

:
The feature data in the specified format

query_features(oid, format='json', survey=None, index=None, sort=None)

Gets features of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The features data in the specified format

query_forced_photometry(oid, format='json', survey=None, index=None, sort=None)

Gets all forced photometry of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The forced photometry data in the specified format

query_lightcurve(oid, format='json', survey=None)

Gets the lightcurve (detections and non_detections) of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).

Returns:

:
The lightcurve data in the specified format

query_magstats(oid, format='json', survey=None, index=None, sort=None)

Gets all magnitude statistics of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The magnitude statistics data in the specified format

query_non_detections(oid, format='json', survey=None, index=None, sort=None)

Gets all non detections of a given object

Parameters:

oidstr | int: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The non-detections data in the specified format

query_object(oid, format='json', survey=None, **kwargs)

Gets a single object by object id

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
survey: str | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
kwargs: dict: Additional parameters specific to the multisurvey API

Returns:

:
The object data in the specified format

query_objects(format='pandas', index=None, sort=None, survey=None, **kwargs)

Gets a list of objects filtered by specified parameters.

Parameters:

formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
indexstr: Name of the column to use as index when format is ‘pandas’
sortstr: Name of the column to sort when format is ‘pandas’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in a future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
**kwargs: Keyword arguments specific to the survey being queried. For ZTF, these can include: classifier, class_name, ndet, probability, firstmjd, lastmjd, ra, dec, radius, page, page_size, count, order_by, order_mode.

Returns:

:
The queried objects data in the specified format

Raises:

ValueError: If the survey is not in the list of valid surveys.

query_probabilities(oid, format='json', survey=None, index=None, sort=None)

Gets all probabilities of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
surveystr | None: The survey to query. If None, defaults to ‘ztf’. Note: relying on the default (omitting the survey parameter) is deprecated and will be removed in future release; callers should explicitly pass the desired survey (e.g. survey=’ztf’).
indexstr: The name of the column to use as index when format is ‘pandas’
sortstr: The name of the column to sort when format is ‘pandas’

Returns:

:
The probabilities data in the specified format

Object Queries

Methods for querying astronomical objects and their metadata.

`alerce.Alerce.query_objects`	Gets a list of objects filtered by specified parameters.
`alerce.Alerce.query_object`	Gets a single object by object id

Photometry Queries

Methods for querying photometric measurements and statistics.

`alerce.Alerce.query_lightcurve`	Gets the lightcurve (detections and non_detections) of a given object
`alerce.Alerce.query_detections`	Gets all detections of a given object
`alerce.Alerce.query_non_detections`	Gets all non detections of a given object
`alerce.Alerce.query_forced_photometry`	Gets all forced photometry of a given object
`alerce.Alerce.query_magstats`	Gets all magnitude statistics of a given object

Classification & Features

Methods for querying object classifications and features.

`alerce.Alerce.query_probabilities`	Gets all probabilities of a given object
`alerce.Alerce.query_features`	Gets features of a given object
`alerce.Alerce.query_feature`	Gets a single feature of a specified object id
`alerce.Alerce.query_classifiers`	Gets all classifiers and their classes
`alerce.Alerce.query_classes`	Gets classes from a specified classifier

Stamps

Methods for retrieving and visualizing image stamps.

`alerce.Alerce.get_stamps`	Download Stamps for a specific alert.
`alerce.Alerce.plot_stamps`	Plot stamp in a notebook given oid.
`alerce.Alerce.get_avro`	Download avro of some alert.

Crossmatching

Methods for crossmatching astronomical catalogs.

`alerce.Alerce.catshtm_conesearch`	catsHTM conesearch given an object and catalog_name.
`alerce.Alerce.catshtm_crossmatch`	catsHTM crossmatch given an object and catalog_name.
`alerce.Alerce.catshtm_redshift`	Get redshift given an object.
`alerce.Alerce.catshtm_catalog_translator`