Metadata-Version: 2.4
Name: alerce
Version: 2.1.0
Summary: ALeRCE Client
Author: ALeRCE Team
Author-email: contact@alerce.online
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=1.1.2
Requires-Dist: astropy>=4.0.1
Requires-Dist: requests>=2.24.0
Requires-Dist: ipython
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![image](https://github.com/alercebroker/alerce_client/workflows/Tests/badge.svg)[![codecov](https://codecov.io/gh/alercebroker/alerce_client/graph/badge.svg?token=Y2AQJ3SWFE)](https://codecov.io/gh/alercebroker/alerce_client)![image](https://readthedocs.org/projects/alerce/badge/?version=latest)

# 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:

```bash
pip install alerce
```

Or install from source:

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

## Quickstart

Basic usage with the `Alerce` client:

```python
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`.
