https://github.com/alercebroker/alerce_client
🐍 ALeRCE Python Client
https://github.com/alercebroker/alerce_client
alerce astronomy lsst python ztf
Last synced: 3 months ago
JSON representation
🐍 ALeRCE Python Client
- Host: GitHub
- URL: https://github.com/alercebroker/alerce_client
- Owner: alercebroker
- License: mit
- Created: 2019-09-03T21:22:03.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2026-03-04T18:14:44.000Z (3 months ago)
- Last Synced: 2026-03-05T00:42:24.666Z (3 months ago)
- Topics: alerce, astronomy, lsst, python, ztf
- Language: Python
- Homepage: https://alerce.readthedocs.io/en/latest/index.html
- Size: 435 KB
- Stars: 9
- Watchers: 10
- Forks: 1
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://codecov.io/gh/alercebroker/alerce_client)
# 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`.