Access ZTF Source Data from Fritz (SkyPortal)

The ztfquery.fritz module is a Python interface to fritz.science, the ZTF-II data broker built on the SkyPortal platform. It lets you download and work with photometry, spectra, alerts, and source/group information for any target you have access to on Fritz — all directly from Python, with optional local caching under $ZTFDATA/fritz/.

This documentation covers ztfquery ≥ 1.12.0. The API described here reflects the module as of that version. For the very latest features introduced in v1.14+, refer to the tutorial notebooks which supersede parts of this page.

Requirements

Create a Fritz account

Install ztfquery ≥ 1.12.0

pip install ztfquery --upgrade

Store your Fritz token

The first time you call any Fritz function without an explicit token= argument, ztfquery will prompt you for your token and store it encrypted in ~/.ztfquery. You can also save it ahead of time:

from ztfquery import io
io.set_account("fritz")  # prompts for token, stores in ~/.ztfquery

Alternatively, pass token="YOUR_TOKEN" directly to any download function.

Module Structure

ztfquery.fritz is organised around two patterns:

Pattern	Purpose
`download_{type}(name, ...)`	Fetch data from Fritz (optionally stores locally)
Class methods (`FritzPhotometry.from_name`, etc.)	Load a previously downloaded local copy or download fresh

Each data type (lightcurve, spectra, alerts, source, sample, groups) has a corresponding Python class (FritzPhotometry, FritzSpectrum, FritzAlerts, FritzSource, FritzSample, FritzGroups) returned when you pass get_object=True.

Download Functions

`download_lightcurve`

name

str

required

ZTF source name (e.g. "ZTF20acmzoxo").

get_object

bool

default:"False"

If True, returns a FritzPhotometry instance. Otherwise returns a raw pandas.DataFrame.

token

str

default:"None"

Fritz API token. Uses the stored token if not provided.

store

bool

default:"False"

If True, saves the light curve to $ZTFDATA/fritz/lightcurve/. Set to False to skip storing.

format

str

default:"None"

SkyPortal API option — "flux" or "mag". Default uses the API default.

magsys

str

default:"None"

SkyPortal API option — "ab" or "vega". Default uses the API default.

from ztfquery import fritz

lc = fritz.download_lightcurve("ZTF20acmzoxo", get_object=True)
lc.show()

`download_spectra`

name

str

required

ZTF source name.

get_object

bool

default:"False"

If True, returns a FritzSpectrum (or list of FritzSpectrum if multiple spectra exist).

token

str

default:"None"

Fritz API token.

store

bool

default:"False"

If True, saves spectra under $ZTFDATA/fritz/spectra/{name}/.

verbose

bool

default:"False"

If True, prints the queried URL.

from ztfquery import fritz

spec = fritz.download_spectra("ZTF20acmzoxo", get_object=True, store=True)
spec.show()

`download_alerts`

name

str

required

ZTF source name.

candid

int or str

default:"None"

Specific alert candidate ID to retrieve. Returns all alerts when None.

allfields

bool

default:"None"

Set True to retrieve all alert fields (not just candidate info).

get_object

bool

default:"False"

If True, returns a FritzAlerts instance.

token

str

default:"None"

Fritz API token.

store

bool

default:"False"

If True, saves alerts to $ZTFDATA/fritz/alerts/.

from ztfquery import fritz

alerts = fritz.download_alerts("ZTF20acmzoxo", allfields=True, get_object=True)

`download_source`

name

str

required

ZTF source name.

get_object

bool

default:"False"

If True, returns a FritzSource instance.

token

str

default:"None"

Fritz API token.

store

bool

default:"False"

If True, saves the source JSON to $ZTFDATA/fritz/source/.

source = fritz.download_source("ZTF20acmzoxo", get_object=True)
source.get_redshift()
source.get_coordinates()
source.view_on_fritz()  # opens the Fritz page in your browser

`download_sample`

Downloads all sources belonging to a Fritz group.

groupid

int or str

required

Numeric group ID or "*" / "all" for no group filter.

get_object

bool

default:"False"

Returns a FritzSample when True.

token

str

default:"None"

Fritz API token.

store

bool

default:"False"

If True, saves the sample CSV to $ZTFDATA/fritz/sample/.

sample = fritz.download_sample(groupid=177, get_object=True)

`download_groups`

get_object

bool

default:"False"

Returns a FritzGroups instance when True.

token

str

default:"None"

Fritz API token.

store

bool

default:"True"

If True (default), saves the groups JSON to $ZTFDATA/fritz/groups/.

groups = fritz.download_groups(get_object=True)
print(groups.accessible)

Fritz Object Classes

FritzPhotometry
FritzSpectrum
FritzAccess

FritzPhotometry wraps the photometry DataFrame returned by Fritz and adds filtering, coordinate extraction, and plotting methods.

Accessing the data

from ztfquery import fritz

lc = fritz.download_lightcurve("ZTF20acmzoxo", get_object=True)

print(lc.data.columns)
# Index(['obj_id', 'ra', 'dec', 'filter', 'mjd', 'instrument_id',
#        'instrument_name', 'ra_unc', 'dec_unc', 'origin', 'id', 'groups',
#        'mag', 'magerr', 'magsys', 'limiting_mag'],
#       dtype='object')

Getting coordinates

Retrieve the full set of per-epoch coordinates as a DataFrame:

lc.get_coordinates(full=True)
#            ra         dec
# 0   331.205290  16.856651
# 2   331.205307  16.856643
# ...

Or compute a single best-estimate position using a numpy statistic:

lc.get_coordinates(method="nanmedian")
# array([331.2052937,  16.8566374])

Filtering data

get_data() accepts band, detection flag, and time-range filters:

filtered = lc.get_data(
    filters="ztfi",
    detected=True,
    time_range=["2020-10-22", "2020-11-15"]
)

Plotting

lc.show()

# Plot with inline filtering
lc.show(filtering=dict(
    filters="ztfi",
    detected=True,
    time_range=["2020-10-22", "2020-11-15"]
))

Storing locally

lc.store("my_lightcurve.csv")   # CSV
lc.store("my_lightcurve.hdf5")  # HDF5
lc.store("my_lightcurve.json")  # JSON

The default store() call (no argument) saves to $ZTFDATA/fritz/lightcurve/fritz_lightcurve_{name}.csv.

Smart loading with `from_name`

FritzPhotometry.from_name() first checks for a local copy; if found it loads from disk, otherwise it downloads from Fritz:

# First call: downloads from Fritz and caches
lc = fritz.FritzPhotometry.from_name("ZTF20acmzoxo", force_dl=True)
lc.store()

# Subsequent calls: loads from disk instantly
lc = fritz.FritzPhotometry.from_name("ZTF20acmzoxo")

FritzSpectrum wraps a single Fritz spectrum dictionary and exposes the flux, wavelength, errors, and header as well as I/O helpers.

Key attributes

Attribute	Description
`.lbda`	Wavelength array
`.flux`	Flux array
`.error`	Flux-error array (may be `None`; check `.has_error()`)
`.data`	DataFrame with `lbda`, `flux`, (and `error`) columns
`.header`	Metadata DataFrame (instrument, observer, etc.)
`.fritzdict`	Raw dictionary as returned by the Fritz API

Inspecting the raw Fritz dictionary

from ztfquery import fritz

spec = fritz.download_spectra("ZTF20acmzoxo", get_object=True)
print(spec.fritzdict.keys())
# dict_keys(['created_at', 'followup_request_id', 'modified',
#            'assignment_id', 'wavelengths', 'altdata', 'fluxes',
#            'original_file_string', 'errors', 'original_file_filename',
#            'obj_id', 'owner_id', 'observed_at', 'id', 'origin',
#            'instrument_id', 'groups', 'instrument_name',
#            'reducers', 'observers'])

Plotting

spec.show()

Multiple spectra

If a target has more than one spectrum, download_spectra(..., get_object=True) returns a list of FritzSpectrum objects:

spectra = fritz.download_spectra("ZTF20acrzwvx", get_object=True)
fig = spectra[0].show()
ax  = fig.axes[0]
spectra[1].show(ax=ax, color="C1")

Storing and reloading

spec.store("my_spectrum.ascii")   # plain text
spec.store("my_spectrum.fits")    # FITS
spec.store("my_spectrum.json")    # raw Fritz JSON

# Reload
spec2 = fritz.FritzSpectrum.read_ascii("my_spectrum.ascii")
spec2 = fritz.FritzSpectrum.read_fits("my_spectrum.fits")
spec2 = fritz.FritzSpectrum.read_json("my_spectrum.json")

The default store() (no argument) saves to $ZTFDATA/fritz/spectra/{name}/fritz_spectrum_{instrument}_{key}_{name}.ascii.

FritzAccess provides a user-centric view of Fritz: it aggregates your group memberships and the samples (groups of sources) associated with those groups.

Basic workflow

from ztfquery import fritz

# 1. Instantiate
faccess = fritz.FritzAccess()

# 2. Load your group memberships
faccess.load_groups()

# 3. Inspect accessible groups
print(faccess.groups.accessible)
#   nickname              modified   id                  name  single_user_group                  created_at
# 0    infant  2020-10-21T06:20:...   49      Infant Supernovae              False  2020-10-21T06:20:...
# 4    SNeIa   2020-11-15T09:33:...  177   Type Ia Supernovae              False  2020-11-15T09:33:...

# 4. Load samples for one or more groups by name or id
faccess.load_samples(groupnames_or_id="SNeIa")
# or for multiple groups at once:
# faccess.load_samples(groupnames_or_id=["infant", "SNeIa"])

# 5. Get a FritzSample object for a single group
sample = faccess.get_sample("SNeIa")
print(sample.names)       # array of source name strings
print(sample.data)        # DataFrame with ra, dec, redshift, classification, etc.

Fast loading from local cache

Every call to load_samples() can store results locally. To skip the network entirely on future runs:

from ztfquery import fritz

faccess = fritz.FritzAccess.load_local()

You can still refresh individual groups afterwards:

faccess.load_samples(groupnames_or_id="SNeIa", force_dl=True)

Per-source data via FritzSample

Once a sample is loaded, retrieve individual source information through the FritzSample object:

sample = faccess.get_sample("SNeIa")

# Get a specific FritzSource object by name
src = sample.get_source("ZTF20acmzoxo")
src.get_redshift()
src.get_coordinates()
src.get_classification()
src.view_on_fritz()

# Get the ZTFQuery metadata dict for IRSA queries
meta_kwargs = sample.get_target_metaquery("ZTF20acmzoxo")

Integration with ZTFQuery

FritzSample.get_target_metaquery() returns a dictionary that can be passed directly to ZTFQuery.load_metadata() to pull IRSA data for your Fritz targets:

from ztfquery import query, fritz

faccess = fritz.FritzAccess.load_local()
sample = faccess.get_sample("SNeIa")

meta_kwargs = sample.get_target_metaquery("ZTF20acmzoxo")
# meta_kwargs = {"radec": [...], "size": 0.01, "sql_query": "..."}

zquery = query.ZTFQuery()
zquery.load_metadata(**meta_kwargs)

Other Fritz Classes

The following classes are used internally and returned by download functions with get_object=True. Each exposes a .store() method and format-specific I/O classmethods.

Class	Created by	Key attributes
`FritzAlerts`	`download_alerts(..., get_object=True)`	`.data` (DataFrame indexed by `candid`)
`FritzSource`	`download_source(..., get_object=True)`	`.fritzdict`, `.ra`, `.dec`, `.redshift`, `.classification`, `get_metaquery()`, `view_on_fritz()`
`FritzSample`	`download_sample(..., get_object=True)`	`.data`, `.names`, `.sources`, `get_source(name)`, `get_target_metaquery(name)`
`FritzGroups`	`download_groups(..., get_object=True)`	`.accessible` (DataFrame of user-accessible groups)

Low-Level API Function

The api() function underlies all download functions and can be used directly for any Fritz/SkyPortal endpoint:

fritz.api(method, endpoint, data=None, load=True, token=None)

Parameter	Description
`method`	HTTP method string: `"get"`, `"post"`, `"put"`, `"delete"`
`endpoint`	Full URL of the SkyPortal API endpoint
`data`	Request body (dict), passed as JSON
`load`	If `True` (default), parse and return the JSON response data
`token`	Fritz API token; uses stored token if `None`

# Example: fetch raw photometry for a source
data = fritz.api("get", "https://fritz.science/api/sources/ZTF20acmzoxo/photometry")

Bulk Downloads

For downloading data for many targets in parallel, use fritz.bulk_download():

names = ["ZTF20acmzoxo", "ZTF20acrzwvx", "ZTF20abtmbaz"]

lightcurves = fritz.bulk_download(
    "lightcurve",
    names,
    nprocess=4,       # parallel workers
    store=True,       # cache to $ZTFDATA/fritz/
    as_dict=True      # {name: FritzPhotometry}
)

Supported fobject values: "lightcurve", "photometry", "spectra", "spectrum", "alerts", "source".

Local Storage Layout

All Fritz data stored via store=True or .store() land under $ZTFDATA/fritz/:

$ZTFDATA/fritz/
├── lightcurve/
│   └── fritz_lightcurve_ZTF20acmzoxo.csv
├── spectra/
│   └── ZTF20acmzoxo/
│       └── fritz_spectrum_sedm_<key>_ZTF20acmzoxo.ascii
├── alerts/
│   └── fritz_alerts_ZTF20acmzoxo.csv
├── source/
│   └── fritz_source_ZTF20acmzoxo.json
└── sample/
    └── fritz_sample_<groupid>.csv

Ensure the $ZTFDATA environment variable is set before calling any function with store=True or dirout="default". See the installation guide for details.

Getting Started

Core Modules

Field & Sky Tools

Examples & Tutorials

Access ZTF Source Data from Fritz (SkyPortal)

Requirements

Module Structure

Download Functions

`download_lightcurve`

`download_spectra`

`download_alerts`

`download_source`

`download_sample`

`download_groups`

Fritz Object Classes

Accessing the data

Getting coordinates

Filtering data

Plotting

Storing locally

Smart loading with `from_name`

Key attributes

Inspecting the raw Fritz dictionary

Plotting

Multiple spectra

Storing and reloading

Basic workflow

Fast loading from local cache

Per-source data via FritzSample

Integration with ZTFQuery

Other Fritz Classes

Low-Level API Function

Bulk Downloads

Local Storage Layout

Build docs developers (and LLMs) love

Getting Started

Core Modules

Field & Sky Tools

Examples & Tutorials

Documentation Index

​Requirements

​Module Structure

​Download Functions

​download_lightcurve

​download_spectra

​download_alerts

​download_source

​download_sample

​download_groups

​Fritz Object Classes

​Accessing the data

​Getting coordinates

​Filtering data

​Plotting

​Storing locally

​Smart loading with from_name

​Key attributes

​Inspecting the raw Fritz dictionary

​Plotting

​Multiple spectra

​Storing and reloading

​Basic workflow

​Fast loading from local cache

​Per-source data via FritzSample

​Integration with ZTFQuery

​Other Fritz Classes

​Low-Level API Function

​Bulk Downloads

​Local Storage Layout

Build docs developers (and LLMs) love

Requirements

Module Structure

Download Functions

`download_lightcurve`

`download_spectra`

`download_alerts`

`download_source`

`download_sample`

`download_groups`

Fritz Object Classes

Accessing the data

Getting coordinates

Filtering data

Plotting

Storing locally

Smart loading with `from_name`

Key attributes

Inspecting the raw Fritz dictionary

Plotting

Multiple spectra

Storing and reloading

Basic workflow

Fast loading from local cache

Per-source data via FritzSample

Integration with ZTFQuery

Other Fritz Classes

Low-Level API Function

Bulk Downloads

Local Storage Layout