ALeRCE Package

ALeRCE Python Client

A Python client for accessing ALeRCE astronomical data services.

Usage

>>> from alerce.core import Alerce
>>> client = Alerce()
>>> objects = client.query_objects(survey="ztf", ra=10.0, dec=-20.0, radius=30)

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

Main 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

Exceptions

exception alerce.exceptions.APIError(message=None, code=None, data={}, response=None)[source]

Bases: Exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args: !! processed by numpydoc !!

code = -1

data = {}

message = 'An error with the API occurred.'

response = None

exception alerce.exceptions.CandidError[source]

Bases: Exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args: !! processed by numpydoc !!

code = -1

data = {}

message = 'Object has no stamps.'

response = None

exception alerce.exceptions.FormatValidationError(message=None, code=None, data={}, response=None)[source]

Bases: ParseError

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args: !! processed by numpydoc !!

code = -1

data = {}

message = 'An error with the API occurred.'

response = None

exception alerce.exceptions.ObjectNotFoundError(message=None, code=None, data={}, response=None)[source]

Bases: APIError

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args: !! processed by numpydoc !!

code = -1

data = {}

message = 'An error with the API occurred.'

response = None

exception alerce.exceptions.ParseError(message=None, code=None, data={}, response=None)[source]

Bases: APIError

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args: !! processed by numpydoc !!

code = -1

data = {}

message = 'An error with the API occurred.'

response = None

alerce.exceptions.handle_error(response, response_format='json')[source]

alerce.utils module

class alerce.utils.Client(**kwargs)[source]

Bases: object

Methods

load_config_from_object

load_config_from_object(object)[source]

class alerce.utils.Result(format='json')[source]

Bases: ABC

Methods

`result`([index, sort])	Creates the result depending on the arguments and the expected format
`to_pandas`([index, sort])	Convert the result to a pandas dataframe

to_csv
to_json
to_votable

result(index=None, sort=None)[source]

Creates the result depending on the arguments and the expected format

Index:: if format is pandas, this is the index column
Sort:: if format is pandas, this is the sort column
Returns:: Result in the indicated format

abstract to_csv()[source]

abstract to_json()[source]

abstract to_pandas(index=None, sort=None)[source]

Convert the result to a pandas dataframe

Index:: index for the pandas dataframe
Sort:: sorting column for the dataframe
Returns:: the processed dataframe

abstract to_votable()[source]

class alerce.utils.ResultCsv(csv_result_byte, **kwargs)[source]

Bases: Result

Object that holds a csv type result

Methods

`result`([index, sort])	Creates the result depending on the arguments and the expected format
`to_pandas`([index, sort])	Convert the result to a pandas dataframe

to_csv
to_json
to_votable

result(index=None, sort=None)

Creates the result depending on the arguments and the expected format

Index:: if format is pandas, this is the index column
Sort:: if format is pandas, this is the sort column
Returns:: Result in the indicated format

to_csv()[source]

to_json()[source]

to_pandas(index=None, sort=None)[source]

Convert the result to a pandas dataframe

Index:: index for the pandas dataframe
Sort:: sorting column for the dataframe
Returns:: the processed dataframe

to_votable()[source]

class alerce.utils.ResultJson(json_result, **kwargs)[source]

Bases: Result

Object that holds a json type result

Methods

`result`([index, sort])	Creates the result depending on the arguments and the expected format
`to_pandas`([index, sort])	Convert the result to a pandas dataframe

to_csv
to_json
to_votable

result(index=None, sort=None)

Creates the result depending on the arguments and the expected format

Index:: if format is pandas, this is the index column
Sort:: if format is pandas, this is the sort column
Returns:: Result in the indicated format

to_csv()[source]

to_json()[source]

to_pandas(index=None, sort=None)[source]

Convert the result to a pandas dataframe

Index:: index for the pandas dataframe
Sort:: sorting column for the dataframe
Returns:: the processed dataframe

to_votable()[source]

alerce.utils.load_config(service)[source]

Return type:: Dict[str, Any]

alerce.ztf_search module

class alerce.ztf_search.ZTFSearch[source]

Bases: Client

Attributes:

ztf_url

Methods

`query_classes`(classifier_name, ...[, format])	Gets classes from a specified classifier
`query_classifiers`([format])	Gets all classifiers and their classes
`query_detections`(oid[, format, index, sort])	Gets all detections of a given object
`query_feature`(oid, name[, format])	Gets a single feature of a specified object id
`query_features`(oid[, format, index, sort])	Gets features of a given object
`query_forced_photometry`(oid[, format, ...])	Gets all forced photometry epochs of a given object
`query_lightcurve`(oid[, format])	Gets the lightcurve (detections and non_detections) of a given object
`query_magstats`(oid[, format, index, sort])	Gets magnitude statistics of a given object
`query_non_detections`(oid[, format, index, sort])	Gets all non detections of a given object
`query_object`(oid[, format])	Gets a single object by object id
`query_objects`([format, index, sort])	Gets a list of objects filtered by specified parameters.
`query_probabilities`(oid[, format, index, sort])	Gets probabilities of a given object

load_config_from_object

load_config_from_object(object)

query_classes(classifier_name, classifier_version, format='json')[source]

Gets classes from a specified classifier

Parameters:

classifier_namestr: The classifier unique name
classifier_versionstr: The classifier’s version

query_classifiers(format='json')[source]: Gets all classifiers and their classes

query_detections(oid, format='json', index=None, sort=None)[source]

Gets all detections of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’
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’

query_feature(oid, name, format='json')[source]

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’

query_features(oid, format='json', index=None, sort=None)[source]

Gets features of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

query_forced_photometry(oid, format='json', index=None, sort=None)[source]

Gets all forced photometry epochs of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

query_lightcurve(oid, format='json')[source]

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’

query_magstats(oid, format='json', index=None, sort=None)[source]

Gets magnitude statistics of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

query_non_detections(oid, format='json', index=None, sort=None)[source]

Gets all non detections of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

query_object(oid, format='json')[source]

Gets a single object by object id

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

query_objects(format='pandas', index=None, sort=None, **kwargs)[source]

Gets a list of objects filtered by specified parameters. It is strongly advised to look at the documentation of `ALERCE ZTF API`_

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’

**kwargs

Keyword arguments. Each argument can be one of the `ALERCE ZTF API`_ object query parameters.

classifierstr
classifier name
class_namestr
class name
ndetint[]
Range of detections.
probabilityfloat
Minimum probability.
firstmjdfloat[]
First detection date range in mjd.
lastmjdfloat[]
Last detection date range in mjd.
rafloat
Ra in degrees for conesearch.
decfloat
Dec in degrees for conesearch.
radiusfloat
Radius in arcsec for conesearch.
pageint
Page or offset to retrieve. Default value : 1
page_sizeint
Number of objects to retrieve in each page. Default value: 10
countstr (bool like)
Whether to count total objects or not. Can be a string representation of boolean like “True”, “true”, “yes”, “false”, …
order_bystr
Column used for ordering. Available values : oid, ndethist, ncovhist, mjdstarthist, mjdendhist, corrected, stellar, ndet, g_r_max, g_r_max_corr, g_r_mean, g_r_mean_corr, meanra, meandec, sigmara, sigmadec, deltamjd, firstmjd, lastmjd, step_id_corr, object, classifier_name, class_name, probability, probabilities
order_modestr
Ordering could be ascendent or descendent. Available values : ASC, DESC

query_probabilities(oid, format='json', index=None, sort=None, **kwargs)[source]

Gets probabilities of a given object

Parameters:

oidstr: The object identifier
formatstr: Return format. Can be one of ‘pandas’ | ‘votable’ | ‘json’

property ztf_url: !! processed by numpydoc !!

Module contents

ALeRCE Python Client

A Python client for accessing ALeRCE astronomical data services.

Usage

>>> from alerce.core import Alerce
>>> client = Alerce()
>>> objects = client.query_objects(survey="ztf", ra=10.0, dec=-20.0, radius=30)

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