Sky Patrol V3 documentation

A working V3 preview with 19 real stars and 54 Solar System objects. Search, plot and download the available light curves; full-survey coverage awaits BeeGFS on the serving host.

API 3.1 · source stars release 55c97bc0c218a6c5 · source SS release ef7caf53a399bc1f

Public sample

Public HTTPS serves both real sample datasets. Accounts, tokens and small batch downloads work now. Full-survey coverage awaits BeeGFS; large asynchronous jobs are unavailable. See current limits.

Stars19 in preview

Star photometry rows1.21 trillion

ASAS-SN images15,164,380

Asteroids and comets54 in preview

Solar-system measurements12.6 billion

Quick start in 60 seconds#

You need only curl or Python 3 with pandas. Interactive use is anonymous: no sign-up and no key. Each example is complete, so you can paste it into a terminal or a Python session as it stands.

1. One star#

Ask for a star by its V3 id or its AV3 name and get its light curve as CSV. OJ 287 is V3 star 11010359:

Shell

curl -s "https://asassn-v3.ifa.hawaii.edu/v3/stars/11010359/lc?format=csv" -o oj287.csv
grep -v '^#' oj287.csv | head -n 4

Python

import pandas as pd

url = "https://asassn-v3.ifa.hawaii.edu/v3/stars/11010359/lc?format=csv"
lc = pd.read_csv(url, comment="#")
clean = (lc.quality & 0x17) == 0   # drop the flags the website hides by default
det = lc[clean & (lc.detected == 1)] # the other rows are 5-sigma upper limits
print(len(lc), "epochs,", len(det), "clean detections, median g =",
      det[det.band == "g"].mag.median())

The CSV holds every row, flagged or not. The Python lines keep the rows the website plots by default: detections without the quality bits 0x17 (bad pixel, saturation, image not good, negative pixel). To have the server drop those rows, add &exclude_quality=0x17 to the URL. Quality flags lists every bit.

Recorded response GET /v3/stars/11010359/lc?format=csv · HTTP 200 · content-type: text/csv; charset=utf-8 · x-sp3-rows: 10176

# format: SP3-CSV 1
# kind: star_lc
# dataset: stars
# release_id: 55c97bc0c218a6c52fa9345281389dd39a8c4bd139d55c14ca87bd209a760d09
# serve_id: 4b8c08cfa8db7f77
# n: 10176
# object: {"star_id":11010359,"name":"AV3_085448.87+200630.6","ra":133.7036455,"dec":20.1085113,"pmra":0.0,"pmdec":-0.14,"pm_missing":false,"reference_epoch":2015.5,"mag":15.415035059,"mag_err":0.0275620086823,"n_fields":3,"default_aperture":1.5,"apertures":[1.5]}
# selection: {"aperture":"default","band":"all","fields":null,"cols":"lean","rows":"all","exclude_quality":0,"error_model":"legacy"}
# curves: [{"entry_id":44041437,"field":"F0845+18_0428","band":"g","aperture":1.5,"start":0,"count":55,"n_total":55,"contributions":["F0845+18_0428_g_draupadi_9c3d62d3d97bfd92795217e2","F0845+18_0428_g_sahadeva_08f3f144740f04230b94ea18"]},{"entry_id":44041437,"field":"F0845+18_0428","band":"V","aperture":1.5,"start":55,"count":48,"n_total":48,"contributions":["F0845+18_0428_V_draupadi_b1370215a06874d21d1394e2","F0845+18_0428_V_sahadeva_a8d70000b3586265d5c86909"]},{"entry_id":44041437,"field":"F0853+22_0430","band":"g","aperture":1.5,"start":103,"count":4121,"n_total":4121,"contributions":["F0853+22_0430_g_draupadi_8d43ed99356c0e3f5536419e","F0853+22_0430_g_sahadeva_76efb35a9b9117643f901bd8"]},{"entry_id":44041437,"field":"F0853+22_0430","band":"V","aperture":1.5,"start":4224,"count":867,"n_total":867,"contributions":["F0853+22_0430_V_draupadi_88cbce1647eb2fe617731a67","F0853+22_0430_V_sahadeva_23508e4b58593492016a10c4"]},{"entry_id":44041437,"field":"F0902+18_0429","band":"g","aperture":1.5,"start":5091,"count":4152,"n_total":4152,"contributions":["F0902+18_0429_g_sahadeva_ba8669c67eb0fc10c0070331"]},{"entry_id":44041437,"field":"F0902+18_0429","band":"V","aperture":1.5,"start":9243,"count":933,"n_total":933,"contributions":["F0902+18_0429_V_sahadeva_d398b00de0fe57a89843e9f8"]}]
# summary: {"n_decoded":10176,"n_returned":10176,"n_excluded":0,"n_detected":8687}
# provenance: {"decoder":["5dabebbe6d8aca5f7136ff97d187ec48a26fa7c7826077f0a8f380231e2fc0bc"],"quality_version":"Q5","error_model":"legacy","error_floor":false,"edge_pixels":25.0,"corner_pixels":50.0,"sidecars_sha256":"95f019b21473cbbc572856f5d5c3326e2e02dc5105903c7879c7da92fc70d8a5","server_version":"sp3web/1.0.0","store_version":"sp3web.stars/1.0.0"}
# citation: Shappee et al. 2014; Kochanek et al. 2017; Hart et al. 2023 (ASAS-SN Sky Patrol V3); see /docs/citation.html
# units: {"bjd":"d","mag":"mag","mag_err":"mag","limit":"mag","flux":"mJy","flux_err":"mJy","aperture":"pix"}
bjd,mag,mag_err,limit,flux,flux_err,quality,detected,camera,image_num,curve,field,band,aperture
2458194.5005378984,14.954751,99.999,14.954751,3.1174467,0.7571105,64,0,bj,58881,0,F0845+18_0428,g,1.5
2458494.0542701944,15.137592,0.049194325,16.749756,3.1988153,0.1449372,64,1,bB,12673,0,F0845+18_0428,g,1.5
# … 10175 more lines

Each row is one image. detected is 1 for a 5σ detection. Otherwise mag holds the 5σ limit and mag_err is 99.999. The star data page explains every column.

2. A cone search#

Find every V3 star within 60 arcsec of a position (degrees, ICRS), nearest first:

Shell

curl -s "https://asassn-v3.ifa.hawaii.edu/v3/stars/cone?ra=133.7036&dec=20.1085&r=60"

Python

import json, urllib.request

url = "https://asassn-v3.ifa.hawaii.edu/v3/stars/cone?ra=133.7036&dec=20.1085&r=60"
cone = json.load(urllib.request.urlopen(url))
for s in cone["rows"]:
    print(s["star_id"], s["name"], round(s["sep_arcsec"], 1), s["mag"])

Recorded response GET /v3/stars/cone?ra=133.7036&dec=20.1085&r=60 · HTTP 200 · content-type: application/json; charset=utf-8 · x-sp3-rows: 2

{
  "serve_id": "4b8c08cfa8db7f77",
  "ra": 133.7036,
  "dec": 20.1085,
  "r": 60.0,
  "truncated": false,
  "rows": [
    {
      "star_id": 11010359,
      "name": "AV3_085448.87+200630.6",
      "ra": 133.7036455,
      "dec": 20.1085113,
      "pmra": 0.0,
      "pmdec": -0.14,
      "mag": 15.415035059,
      "mag_err": 0.0275620086823,
      "n_fields": 3,
      "sep_arcsec": 0.15910374871725178,
/* … 19 more lines */

Add &format=csv to get a table instead. Catalog positions are at epoch 2015.5. When you search the website by name, it moves the star to that epoch with its proper motion before it searches.

3. An asteroid or comet by name#

Solar-system objects accept a name, number, designation or slug (Massalia, 20, 2P, C_2020_F3). The recommended column marks the clean detections; add &rows=recommended to get only those rows:

Shell

curl -s "https://asassn-v3.ifa.hawaii.edu/v3/ss/objects/Massalia/lc?format=csv" -o massalia.csv
grep -v '^#' massalia.csv | head -n 4

Python

import pandas as pd

url = "https://asassn-v3.ifa.hawaii.edu/v3/ss/objects/Massalia/lc?format=csv"
lc = pd.read_csv(url, comment="#")
good = lc[lc.recommended == 1]       # clean detections (see the solar-system page)
print(len(lc), "rows,", len(good), "recommended, bands", sorted(good.band.unique()))
cols = ["jd", "band", "mag", "mag_err", "phase_angle_deg"]
print(good[cols].head().to_string(float_format="{:.5f}".format))  # full jd precision

The comment lines at the top record the product (reduced or difference image), aperture and error floor that the server chose. jd is the observed UTC time of mid-exposure. The solar-system page explains these choices and the time columns.

4. A thousand stars#

Loop over the ids and save one table. The loop waits and retries when the server asks it to slow down. Anonymous access is limited to 500 source requests/day; use an account for this 1,000-source example and respect Retry-After:

Python

import io, time, urllib.error, urllib.request
import pandas as pd

BASE = "https://asassn-v3.ifa.hawaii.edu"
star_ids = [11010359, 58978847, 6495609]   # OJ 287, CC Com, V523 Cas: put your 1,000 ids here

def get_lc(sid):
    url = f"{BASE}/v3/stars/{sid}/lc?format=csv"
    for attempt in range(6):
        try:
            with urllib.request.urlopen(url, timeout=60) as r:
                return pd.read_csv(io.BytesIO(r.read()), comment="#")
        except urllib.error.HTTPError as e:
            if e.code not in (429, 503):        # 429 rate limited, 503 busy: wait and retry
                raise
            time.sleep(float(e.headers.get("Retry-After") or 2 ** attempt))
    raise RuntimeError(f"star {sid}: still rate limited")

lcs = pd.concat([get_lc(sid).assign(star_id=sid) for sid in star_ids], ignore_index=True)
lcs.to_csv("my_stars.csv", index=False)
print(lcs.groupby(["star_id", "band"]).size())

Use the Python batch client for bounded requests. Large asynchronous exports are unavailable, and daily quotas still apply.

5. From Gaia ids#

Every V3 star knows its Gaia DR3 and DR2 source_id. Use a Gaia id wherever a star is named, or ask which V3 star it is. OJ 287 is Gaia DR3 660820614442429056:

Shell

curl -s "https://asassn-v3.ifa.hawaii.edu/v3/stars/gaia/dr3/660820614442429056"
curl -s "https://asassn-v3.ifa.hawaii.edu/v3/stars/Gaia%20DR3%20660820614442429056/lc?format=csv" -o oj287.csv
grep -v '^#' oj287.csv | head -n 3

Python

import io, json, urllib.request
import pandas as pd

BASE = "https://asassn-v3.ifa.hawaii.edu"
gaia_dr3 = ["660820614442429056", "1972957892448494592", "674214551557961984"]   # OJ 287, SS Cyg, U Gem

# one POST maps up to 3 anonymous or 100 authenticated Gaia ids; results retain request order
req = urllib.request.Request(f"{BASE}/v3/stars/gaia/dr3", data=json.dumps({"ids": gaia_dr3}).encode(),
                             headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
    found = {x["source_id"]: x["star_id"] for x in json.load(r)["results"]}
print(found)                                  # star_id is None when Gaia has no V3 counterpart

for gid, sid in found.items():
    if sid is not None:
        lc = pd.read_csv(f"{BASE}/v3/stars/{sid}/lc?format=csv", comment="#")
        print(gid, "->", sid, len(lc), "rows")

A Gaia id without a V3 star returns 404 with a suggestion. Ids are strings in JSON because they need 63 bits. How the match was made explains the separations and the quality codes; the Python client has from_gaia.

In the browser#

Type into the search box on the home page. It understands star names (resolved through Sesame), coordinates, Sky Patrol identifiers and solar-system names:

You type	You get
`OJ 287`	The page of the V3 star at the Sesame position
`08:54:48.9 +20:06:30.6 r=30"`	Every V3 star within 30 arcsec, nearest first
`AV3_085448.87+200630.6` or `sp3:11010359`	That V3 star directly
`Gaia DR3 660820614442429056`, `DR2 …` or a bare Gaia id	The matched V3 star directly
`Massalia`, `(433) Eros`, `2P`, `C/2020 F3`	The object's page with its light curve and orbit

Every page keeps its state in the URL, so a link reproduces the same view: try /star/11010359 or /ss/20. The website guide lists the URL parameters and keyboard shortcuts.

Five things to know#

Identifiers: A star is a V3 star_id (an integer), its AV3 name, or its Gaia DR3 or DR2 id. V2 and V3 ids differ. A solar-system object is an object_id, always written as a decimal string because it needs 63 bits, or any unique name, number, designation or slug.
Detections and limits: Every image is a row. When a source is not detected at 5σ, mag holds the 5σ limiting magnitude and mag_err is 99.999. Select rows with the detected column, never with the magnitude (details).
Flags are warnings, not cuts: The API returns every row by default and reports problems in the 13-bit quality column. The website hides the Recommended set (0x17) and always says how many points it hid. Choose your own mask with exclude_quality (quality flags).
Releases do not change: Each dataset has a release_id and a shorter serve_id. URLs under /v3/r/{serve_id}/ always return the same bytes, so they can be cached forever. Cite the release ids you used (citation).
Solar-system choices matter: An SS light curve depends on the product (reduced or difference image), aperture, error floor and a blend cut. The defaults come with their reasons, and every response records the selection it used.

Documentation map#

Using the website

Search syntax, pages, URL parameters, plots, phase folding and keyboard shortcuts.

HTTP API reference

Every endpoint, parameter, default, error, rate limit and cache rule.

Formats

CSV, ECSV, JSON, Arrow, Parquet, and the binary SP3C format with 20-line readers.

Python client

Light curves as NumPy, pandas or astropy tables, and large samples.

Star light curves

Columns, units, time systems, apertures, uncertainties and sentinels.

Solar-system light curves

Reduced and difference photometry, blends, comets, geometry and times.

Quality flags

The 13 quality bits, presets, moving-object bits and the recommended rules.

Citing Sky Patrol

Papers to cite, BibTeX, acknowledgement text and release ids.