ALeRCE Python Client

ALeRCE client is a Python library to interact with ALeRCE services and databases.

This README highlights installation, quickstart usage and migration notes for the multi-survey client (ZTF and LSST). For the full reference and tutorials, see the official documentation at https://alerce.readthedocs.io/en/latest/

Key features

• Multi-survey support: query ZTF and LSST data through a unified client.
• Access to objects, lightcurves (detections / non-detections / forced photometry), stamps, classifiers, crossmatches (catsHTM) and more.
• Return formats: json (default), pandas, and votable where applicable.

Installing

Install from PyPI:

pip install alerce

Or install from source:

git clone https://github.com/alercebroker/alerce_client.git
cd alerce_client
python setup.py install

Quickstart

Basic usage with the Alerce client:

from alerce.core import Alerce
client = Alerce()

# Query objects (must specify survey for multi-survey API)
ztf_objects = client.query_objects(survey="ztf", classifier="lc_classifier", class_name="SN", probability=0.8, format="pandas")

# Query a lightcurve (detections/non-detections/forced photometry)
lightcurve = client.query_lightcurve(oid="ZTF18abbuksn", survey="ztf", format="json")

# Query detections only
detections = client.query_detections(oid="ZTF18abbuksn", survey="ztf", format="pandas")

# Get stamps for an object (first detection by default or use measurement_id)
stamps = client.get_stamps(oid="ZTF18abkifng", survey="ztf")

# Crossmatch (catsHTM conesearch)
ra, dec, radius = 10.0, 20.0, 1000  # radius in arcsec
cone = client.catshtm_conesearch(ra, dec, radius, "GAIA/DR1", format="pandas")

See the documentation for many more examples and parameters.

Multi-survey notes / Migration from ZTF-only API

The client supports multiple surveys. Most query methods now require an explicit survey parameter. Supported surveys:

• ztf — Zwicky Transient Facility
• lsst — Legacy Survey of Space and Time (Rubin Observatory)

Backward compatibility: many methods default to survey="ztf" when omitted, but this behavior is deprecated and will be removed in a future release. Update your code to always pass survey="ztf" or survey="lsst" explicitly.

Object ID formats differ between surveys:

• ZTF: string IDs like "ZTF18abbuksn"
• LSST: numeric-like IDs such as 45121627560013211

Contributing

Please read CONTRIBUTING.rst for the project's contribution guidelines.

License

This project is licensed under the terms in LICENSE.txt.