asassnV3 Python package

Search V3, download light curves and pass them directly to established science packages.

Install

Install directly from this website:

python -m pip install https://asassn-v3.ifa.hawaii.edu/downloads/asassnV3.tar.gz

Or download asassnV3. For optional table conversions:

python -m pip install pandas astropy pyarrow

Python 3.10 or later and NumPy are required. Lightkurve is optional and installed separately.

Connect

from asassnV3 import Client
c = Client()  # https://asassn-v3.ifa.hawaii.edu
# Reads ASASSNV3_TOKEN if set; small requests need no account.

Create an account and revocable API tokens on the account page. Save the one-time recovery code in your password manager.

Star light curves

lc = c.star_lc(11010359)  # OJ 287
frame = lc.to_pandas()
table = lc.to_astropy()
lc.save("oj287.parquet")
g = lc.select(band="g")  # retains negative fluxes and non-detections
series = g.to_timeseries(time_scale="tdb")

Lean stellar curves carry BJD in TDB; full curves also carry JD in UTC. Conversion preserves values and performs no time correction. Match the explicit time scale to the selected column. Quality and detection filtering are explicit.

Familiar query workflows

near = c.cone_search(133.70365, 20.10851, 60, units="arcsec")
curves = c.query_list([11010359, 26469040], download=True)
print(curves.errors)  # per-target failures are preserved
combined = curves.to_pandas()

V3 star IDs are different from V2 asas_sn_id values. Arbitrary ADQL/SQL and V2 catalogs are not provided.

Gaia IDs

matches = c.gaia("660820614442429056", release="dr3")
ids = c.from_gaia(["660820614442429056"], details=True)

Keep Gaia IDs as integers or decimal strings, never floating point. Single lookups retain all matches and quality flags; batch mapping reports the closest match and its multiplicity.

Asteroids and comets

lc = c.ss_lc("Massalia", rows="recommended")
comet = c.ss_lc("2P", product="conv", aperture=2.0)

Batches and errors

for target_id, result in c.iter_star_lcs([11010359, 26469040]):
    print(target_id, result)

Default batches contain 3 IDs anonymously or 100 with a token. Team-approved users may request up to 1,000 with chunk=1000, subject to response-size limits. Use c.account() to see your tier and allowance. Daily and shared-IP limits also apply. The client honors Retry-After; long waits are returned as APIError.retry_after. Cached responses count toward quotas. Large asynchronous export jobs remain unavailable.

Interoperability

Use to_numpy(), to_pandas(), to_astropy(), to_arrow(), or save() for CSV, ECSV and Parquet. Units and provenance are retained. to_lightkurve(band="g", time_scale="tdb") hands a single filter to Lightkurve. Use Astropy/Lightkurve for periodograms, folding and detrending.

Compatibility

SkyPatrolClient is an alias for Client. The package name and import are asassnV3. The older native rc1 protocol is not enabled on this website. The package does not contain server-side credentials.