Solar system

Search by Solar System object name

List of arguments

The list of arguments for running a search by Solar System name can be found at https://api.lsst.fink-portal.org . The schema of the returned payload can be found on the schema page and you can also retrieve it programmatically.

Every time a new alert is emitted, a new diaSource is created. LSST makes an association (1'' matching radius) with a catalog of known Solar system objects (SSO) from the MPC prior to sending alerts. If the alert is matched to a known SSO, it is associated to an existing ssObject, and a ssObjectId is assigned to it. This page describes how to retrieve all diaSources information associated to the same ssObject. For alerts matched to a static object, see Search by diaObjectId.

Alert data

You can enter any name (e.g. Ukyounodaibu), number (e.g. 734394), or provisonal designation (e.g. 2015 BC557, K15Bt7C) of asteroids. Under the hood, we resolve the name using the quaero service from SsODNet. You can also search for comets (although none has been seen yet by Rubin in the alert stream), but note that we have far less comets than asteroids.

PythoncurlwgetQuery URL

import io
import requests
import pandas as pd

# get data for provisional designation 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "json"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

# Get data for the asteroid 2015 BC557 and save it in a CSV file
curl -H "Content-Type: application/json" -X POST -d '{"n_or_d":"2015 BC557", "output-format":"csv"}' https://api.lsst.fink-portal.org/api/v1/sso -o 2003_UT84.csv

Note that you can replace spaces " " in object name with underscores in queries:

# you can also specify parameters in the URL
wget "https://api.lsst.fink-portal.org/api/v1/sso?n_or_d=2015_BC557&output-format=json" -O 2015_BC557.json

SSO pages are indexed by packed provisional designation. Paste this query on your browser to inspect the object:

https://lsst.fink-portal.org/K15Bt7C

You can also retrieve the data for several objects at once:

Several objects at once

import io
import requests
import pandas as pd

# ID as string
mylist = ["734394", "K15Bt7C", "SchUkyounodaibuwarzschilda"]

# get alert data for many objects
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "n_or_d": ",".join(mylist),
    "columns": "r:midpointMjdTai,r:psfFlux,r:psfFluxErr,r:ra,r:dec",
    "output-format": "json"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

Mixing types

Note that you can mix asteroid and comet names, unless you specify withEphem=True (see below), in which case you must give only a list of asteroid names or list of comet names (schemas for ephemerides are not the same).

Do not abuse!

Although the REST API gives you access to hundreds of millions of alerts without account, it is not designed to massively download data. If you have hundreds of objects to query, you probably want to select only a small subset of columns, or you can use the Data Transfer service.

Note that you can also choose different output format:

jsoncsvParquetvotable

import io
import requests
import pandas as pd

# get data for provisional designation 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "json"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

import io
import requests
import pandas as pd

# get data for provisional designation 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "csv"
  }
)

# Format output in a DataFrame
pd.read_csv(io.BytesIO(r.content))

import io
import requests
import pandas as pd

# get data for provisional designation 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "parquet"
  }
)

# Format output in a DataFrame
pdf = pd.read_parquet(io.BytesIO(r.content))

import io
import requests
from astropy.io import votable

# get data for provisional designation 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "votable"
  }
)

# VO table
vt = votable.parse(io.BytesIO(r.content))

Object data

The endpoint TBD give access to summary information about an object, such as the orbital parameters, the number of alerts for the object, number of oppositions, etc. You would simply use:

Object summary information

import requests

# get summary data for 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/TBD",
  json={
    "n_or_d": "2015 BC557",
    "output-format": "json"
  }
)

if r.status_code == 200:
  # dictionary with object properties
  properties = r.json()[0]

Adding ephemerides from Miriade

Limitations

Beware it adds few seconds delay per API call and color ephemerides are returned only for asteroids

You can also attach the ephemerides provided by the Miriade ephemeride service :

Adding ephemerides

import io
import requests
import pandas as pd

# get data for object 2015 BC557
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "2015 BC557",
    "withEphem": True,
    "output-format": "json"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

Where columns not prefixed by r: or f: are fields returned from Miriade.