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 accesses several independent ZTF data services, each with its own authentication requirements. To avoid asking for credentials on every call, ztfquery stores them in an encrypted file at ~/.ztfquery using the cryptography package and retrieves them automatically whenever a service is contacted. You only need to supply credentials once per service — or whenever you want to update them.
How Credential Storage Works
When ztfquery needs to authenticate with a service for the first time, it checks ~/.ztfquery for a stored credential. If none is found, it prompts you interactively. The entered value is base64-encoded and written back to ~/.ztfquery under the service’s section name. On every subsequent call the credential is read and decoded transparently.
To reset or update a stored credential at any time, call:
from ztfquery import io
io.set_account("irsa") # prompts for a new IRSA username and password
io.set_account("fritz") # prompts for a new Fritz token
io.set_account("marshal") # prompts for a new Marshal username and password
io.set_account("pharos") # prompts for a new Pharos username and password
set_account accepts optional keyword arguments so you can supply values programmatically instead of being prompted:
# Supply credentials directly (useful in scripts)
io.set_account("irsa", username="myuser", password="mypassword")
# Supply a Fritz token directly
io.set_account("fritz", token="my_fritz_api_token")
The ~/.ztfquery file contains your encoded credentials. It is written with your default umask permissions. Ensure the file is not readable by other users on shared systems (chmod 600 ~/.ztfquery).
Initial Setup Flow
Attempt to use a service
Simply import and call any ztfquery function that requires a service. On the first call, ztfquery detects that no credential exists for that service and triggers the setup prompt automatically.from ztfquery.query import ZTFQuery
zq = ZTFQuery()
zq.load_metadata(kind="sci", radec=[245.0, 30.0], size=0.01)
# → "No irsa account setup, please provide it"
# → "Enter your irsa login: "
# → Password: (hidden input)
Enter your credentials
Type your username and password (or token, for Fritz) when prompted. For IRSA, ztfquery immediately tests the credentials against the IRSA login endpoint and warns you if they appear incorrect.
Credentials are saved
After a successful login, ztfquery writes the encoded credential to ~/.ztfquery. All future calls to that service are authenticated automatically with no further prompts.
Reset credentials if needed
If your password changes or you want to switch accounts, call io.set_account(servicename) to overwrite the stored credential.from ztfquery import io
io.set_account("irsa")
Service-by-Service Authentication
IRSA
Fritz
Marshal
Pharos (SEDM)
SkyVision
IRSA (NASA/IPAC Infrared Science Archive) hosts ZTF images and light curves and is accessed by query.py and lightcurve.py. Authentication uses a standard username and password registered at https://irsa.ipac.caltech.edu.from ztfquery import io
# Set or reset your IRSA credentials
io.set_account("irsa")
# → Enter your irsa login: youruser
# → Password: (hidden)
from ztfquery.query import ZTFQuery
zq = ZTFQuery()
zq.load_metadata(
kind="sci",
radec=[245.0, 30.0],
size=0.01,
auth=["youruser", "yourpassword"],
)
Private vs public data: ZTF public data (proprietary period expired) can be downloaded with any valid IRSA account. Accessing data still within its proprietary period requires an IRSA account that has been explicitly linked to the ZTF collaboration. If you only need public data, a free IRSA registration is sufficient.
from ztfquery import io
print(io.test_irsa_account()) # True if credentials are valid
Fritz (the ZTF-II SkyPortal broker at https://fritz.science) uses token-based authentication rather than a username and password. You generate a token in your Fritz user profile and supply it to ztfquery.from ztfquery import io
# Store your Fritz token
io.set_account("fritz")
# → Enter your fritz token: (paste token here)
from ztfquery import fritz
# Pass token inline — no stored credential needed
spectra = fritz.download_spectra("ZTF21abcdefg", token="your_fritz_token")
To generate a Fritz API token, log in to fritz.science, navigate to your user profile, and create a new token under API Tokens. Tokens can be scoped to specific permissions (read, write, manage groups, etc.). The ZTF-I Growth Marshal (http://skipper.caltech.edu:8080/cgi-bin/growth/marshal.cgi) uses standard username/password authentication and is accessed by marshal.py.from ztfquery import io
# Set or reset Marshal credentials
io.set_account("marshal")
# → Enter your marshal login: youruser
# → Password: (hidden)
marshal.py functions retrieve and use the credential automatically:from ztfquery import marshal
ms = marshal.MarshalAccess()
ms.load_target_sources("Cosmology")
SEDM spectrograph data is served through Pharos at http://pharos.caltech.edu. The sedm.py module uses your Pharos username and password.from ztfquery import io
# Set or reset Pharos credentials
io.set_account("pharos")
# → Enter your pharos login: youruser
# → Password: (hidden)
from ztfquery import sedm
sd = sedm.SEDMQuery()
sd.download_target_spectra("ZTF21abcdefg")
SkyVision provides ZTF observing logs and is accessed by skyvision.py. It requires the ZTF collaboration SkyVision password, stored under the logs service name (no username is needed).from ztfquery import io
# Set the SkyVision password
io.set_account("logs")
# → Password: (hidden — no username prompt)
from ztfquery import skyvision
# Downloads and returns the pre-built ZTF observing summary log as a DataFrame
logs = skyvision.get_summary_logs()
Inline Authentication Reference
All ztfquery download functions that contact IRSA accept an auth parameter so you can supply credentials at call time without touching the stored credential:
from ztfquery.query import ZTFQuery
zq = ZTFQuery()
# Query metadata with inline credentials
zq.load_metadata(
kind="sci",
radec=[245.0, 30.0],
size=0.01,
auth=["your_irsa_username", "your_irsa_password"],
)
# Download files with inline credentials
zq.download_data(
"sciimg.fits",
auth=["your_irsa_username", "your_irsa_password"],
)
auth:
from ztfquery import fritz
fritz.download_lightcurve("ZTF21abcdefg", token="your_fritz_token")
Inline credentials are never written to ~/.ztfquery. Use them when you want to keep credentials out of files entirely (for example, reading them from environment variables in a pipeline), or when running as a different user than the one whose ~/.ztfquery file holds the credentials.
