Skip to main content

imagecodecovimage

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.

Metadata

Release files for alerce 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alerce 2.4.0
File Size Uploaded Provenance Actions
alerce-2.4.0.tar.gz 20.4 kB Without provenance Details for alerce-2.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alerce 2.4.0
File Interpreter ABI Platform Actions
alerce-2.4.0-py3-none-any.whl Python 3 none any Details for alerce-2.4.0-py3-none-any.whl

Total release size: 43.9 kB

Release files / alerce-2.4.0.tar.gz

Download URL alerce-2.4.0.tar.gz
Size 20.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5047528ebceb7eff35554c9c436d703b23817f57b94f76189d9d5c9ddf3095f9
BLAKE2b-256 checksum
How to use checksums
fdcaa56938154173a31780ecc727aa0b88ed5a284abb40e502cf3c28293eae2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / alerce-2.4.0-py3-none-any.whl

Download URL alerce-2.4.0-py3-none-any.whl
Size 23.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9d70e66830a9efbacee8a6a28b8f56710484baac80fa0aca48c094c1d6023993
BLAKE2b-256 checksum
How to use checksums
9f2e10cdc3f4b7b8037ce4127f6db05baacf408ba60a25b2463f4d96ae10d973
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for alerce 2.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page