The cookbook

The object catalog is HEALPix-partitioned Parquet (HATS) with each star's full light curve in a nested lc column. Open it lazily with LSDB and nothing downloads until you .compute().

import lsdb

# One row per star; light curves nested in the `lc` column.
cat = lsdb.read_hats("https://data.varchive.app/catalogs/latest/object")

# Filter lazily, then compute — only matching partitions are read.
rrl = cat.query("vsx_broad_class == 'RR_LYRAE' and adopted_period < 1.0")
df  = rrl.compute()              # a nested-pandas frame

lc = df.iloc[0]["lc"]            # full light curve: jd, mag, mag_err, phot_filter, ...
g  = lc[lc["phot_filter"] == "g"]   # the live g band (never stitch V <-> g)

This is the bulk path the whole project is built around — no rate limit, no token, no per-user cost. Margin cache and the asas_sn_id/name index tables ship with every catalog version.

Point-reads resolve through the index tables, so a single star comes back without scanning the catalog. Features, folds, and periods run the exact code paths the nightly pipeline uses.

pip install varchive

from varchive import Client

c = Client()
star = c.get_star(421)                       # by asas_sn_id
star = c.get_star("WISE J193632.2-794139")   # or by name (resolved via the name index)

star.adopted_period                # 0.30716 d
g = star.lightcurve.band("g")      # camera-conditioned g band
folded = g.fold(star.adopted_period)
star.next_eclipses(5)              # upcoming eclipse ephemerides

# A VSX type/period change only re-runs the cheap adoption step:
star.readopt_period()

No key required. Single-star JSON, a light-curve table, or a VOTable ready for TOPCAT/Aladin.

# metadata + adopted period, periods, features
curl https://api.varchive.app/star/421

# the light curve as JSON, or as a VOTable / CSV for VO tools
curl     "https://api.varchive.app/star/421/lightcurve"
curl -OJ "https://api.varchive.app/star/421/lightcurve.vot"
curl -OJ "https://api.varchive.app/star/421/lightcurve.csv"

import requests

r = requests.get("https://api.varchive.app/star/421", timeout=30)
r.raise_for_status()
star = r.json()
print(star["adopted_period"], star["period_source"])

Rate-limited (see below). If you hit a 429 it always carries Retry-After — and the answer to "I need more" is recipe 1: read R2 directly.

Facet by class, period, magnitude, and flags; or search a patch of sky. Default queries return only active stars.

# faceted: short-period eclipsing binaries brighter than g = 14, by period
curl "https://api.varchive.app/search?class=ECLIPSING&pmax=1&mmax=14&sort=period"

# cone search (ra, dec, radius in degrees)
curl "https://api.varchive.app/search?ra=294.13&dec=-79.69&radius=0.5"

Or do the cone search locally over the full catalog with LSDB:

hits = cat.cone_search(ra=294.13, dec=-79.69, radius_arcsec=1800).compute()

Every star page has an Export & cite panel: download the full light curve as CSV or VOTable, or copy a ready-to-paste BibTeX block. The VOTable opens in TOPCAT, Aladin, and CASA via File → Load Table (or drag-and-drop).

Please cite the sources you use. For any ASAS-SN light curve obtained through varchive, ASAS-SN (Shappee et al. 2014; Kochanek et al. 2017; Hart et al. 2023, Sky Patrol v2.0), the ASAS-SN variable star catalogue (Jayasinghe et al. 2018), and VSX (Watson et al. 2006) are required; add Gaia DR3 and Bailer-Jones et al. 2021 if you use the crossmatch photometry or distances. The copy-citation button bundles all of these.

Have photometry of your own? The Analyze page runs a generalized Lomb–Scargle search, a Box Least Squares pass, a fold, and the full variability-feature readout entirely client-side — paste a CSV or drop a file, nothing is uploaded.

The API runs on one small ARM VPS, so per-IP limits keep it responsive for everyone:

Send an honest User-Agent, back off on 429 (always with Retry-After), and for anything at scale read R2 directly with LSDB — that path is unlimited on purpose.