Skip to content

Search by diaObjectId

List of arguments

The list of arguments for running a search by diaObjectId 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 not matched to a known SSO, it is associated to an existing diaObject pointing to this direction on the sky, and a diaObjectId is assigned to it. This page describes how to retrieve all diaSources information associated to the same diaObjectId. For alerts matched to a Solar System objects, see Search by Solar System object name.

/api/v1/sources vs /api/v1/objects

The endpoint /api/v1/sources gives access to alert data for an object (diaSources, incl. object lightcurves), while /api/v1/objects gives access to summary information for an object (diaObject). If you are coming from the ZTF API, see ZTF to LSST migration.

Alert data

Alerts emitted by the same astronomical object share the same diaObjectId identifier. This identifier is a long integer (64-bit integer). The main table for static objects in Fink database is indexed against this identifier, and you can efficiently query all alerts from the same diaObjectId:

import io
import requests
import pandas as pd

# get alert data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": "313761043604045880",
    "columns": "r:diaSourceId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr",
    "output-format": "json"
  }
)

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

# Get alert data for 313761043604045880 and save it in a CSV file
curl -H "Content-Type: application/json" -X POST \
    -d '{"diaObjectId":"313761043604045880", "output-format":"csv"}' \
    https://api.lsst.fink-portal.org/api/v1/sources -o 169830579938263176.csv

# you can also specify parameters in the URL, e.g. with wget:
wget "https://api.lsst.fink-portal.org/api/v1/sources?diaObjectId=313761043604045880&output-format=json" -O 313761043604045880.json

Paste this query on your browser to inspect the results: 

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

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

import io
import requests
import pandas as pd

# ID as string
mylist = ["313761043604045880", "313699514821640259"]

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

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

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.

You can also choose different output format:

import io
import requests
import pandas as pd

# get alert data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": "313761043604045880",
    "columns": "r:diaSourceId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr",
    "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 alert data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": "313761043604045880",
    "columns": "r:diaSourceId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr",
    "output-format": "csv"
  }
)

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

import io
import requests
import pandas as pd

# get alert data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": "313761043604045880",
    "columns": "r:diaSourceId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr",
    "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 alert data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": "313761043604045880",
    "columns": "r:diaSourceId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr",
    "output-format": "votable"
  }
)

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

Object data

The endpoint /api/v1/objects give access to summary information about an object, such as the number of alerts for the object, the mean flux per band, etc. You would simply use:

import requests

# get summary data for 313761043604045880
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/objects",
  json={
    "diaObjectId": "313761043604045880",
    "output-format": "json"
  }
)

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