Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MickaelRigault/ztfquery/llms.txt

Use this file to discover all available pages before exploring further.

ztfquery is a Python library that gives astronomers a single, consistent interface to the data products of the Zwicky Transient Facility (ZTF). Rather than juggling multiple web portals and custom HTTP requests, you import one package and query images, light curves, spectra, alert streams, and observing logs through straightforward Python calls. The library is maintained by M. Rigault (CNRS/IN2P3) and S. Reusch (DESY) and is available on PyPI under the Apache Software License.

​
What is ZTF?

The Zwicky Transient Facility is a wide-field optical survey operating at Palomar Observatory. Using the 48-inch Samuel Oschin Telescope equipped with a 47 square-degree camera, ZTF systematically scans the sky in the g, r, and i bands, generating tens of thousands of alerts every night. These alerts, images, and derived data products are distributed through several complementary services that ztfquery wraps into a unified Python API.

​
What ztfquery Does

ztfquery connects to the following ZTF data services on your behalf, handling authentication, file caching, and data structure automatically:
  • IRSA — the NASA/IPAC Infrared Science Archive hosts ZTF images and pipeline products (science frames, raw frames, calibration frames, reference images) as well as forced-photometry light curves. Public data requires no special access; full collaboration data requires a ZTF-linked IRSA account.
  • Fritz / SkyPortal — the ZTF-II collaboration broker at fritz.science stores source classifications, redshifts, photometry, and spectra. Access is token-based.
  • Marshal — the ZTF-I Growth Marshal at skipper.caltech.edu holds source information and data from the first phase of ZTF operations.
  • SEDM / Pharos — the SED Machine spectrograph data, including IFU cubes and extracted target spectra, is served through pharos.caltech.edu.
  • SkyVision — provides ZTF collaboration observing logs and night summaries.

​
Quick-Start Imports

Importing ztfquery exposes three top-level names directly: 
import ztfquery

print(ztfquery.__version__)   # "1.28.0"

from ztfquery import get_file       # ztfquery.io.get_file — resolve and download a ZTF file by URL
from ztfquery import ZTFQuery       # ztfquery.query.ZTFQuery — main query class
from ztfquery import get_metadata   # ztfquery.query.get_metadata — convenience metadata fetch
All three are re-exported from ztfquery/__init__.py so you can import them from the top-level package without reaching into the sub-modules directly.

​
Key Modules

query.py

Query and download ZTF images and pipeline products (science, raw, calibration, reference frames) from the IRSA web API. The main entry points are ZTFQuery and get_metadata.

lightcurve.py

Retrieve IRSA-hosted ZTF light curves (forced photometry and aperture photometry) without going through image subtraction.

fritz.py

Download source data from the Fritz/SkyPortal broker: classifications, redshifts, photometry, spectra, and alert packets stored under the ZTF-II programme.

marshal.py

Access ZTF-I Growth Marshal data including source lists, photometry, spectra, and classifications from the first phase of ZTF operations.

sedm.py

Fetch SEDM spectrograph data from Pharos, including reduced IFU cubes and extracted target spectra organised by observation date.

alert.py

Read ZTF Avro alert packets. Currently provides a straightforward alert reader for working with the standard ZTF alert schema.

skyvision.py

Pull ZTF observing logs and night summaries from SkyVision to inspect what fields were observed and when.

fields.py

Work with ZTF field geometry — look up field IDs, sky coordinates, and CCD/quadrant layout using the companion ztffields package.

​
Citation and Acknowledgments

If you use ztfquery in research you are publishing, you must both cite the software and include the acknowledgment text below.Citation:
Mickael Rigault. (2018, August 14). ztfquery, a python tool to access ZTF data (Version doi). Zenodo. http://doi.org/10.5281/zenodo.1345222
Required acknowledgment text:“The ztfquery code was funded by the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (grant agreement n°759194 - USNAC, PI: Rigault).”Citations are important because they enable the authors to justify to funding agencies the time invested in building and maintaining tools like ztfquery.

​
Maintainers

NameAffiliationContact
M. RigaultCNRS/IN2P3m.rigault@ipnl.in2p3.fr
S. ReuschDESYsimeon.reusch@desy.de
The source code is hosted on GitHub at github.com/MickaelRigault/ztfquery and the package is distributed via PyPI.

Build docs developers (and LLMs) love

Get started for freeTalk to us