Skip to content

Solar System objects

Known Solar System objects

API

List of arguments

The list of arguments for retrieving known SSO data can be found at https://fink-portal.org/api/v1/sso

The numbers or designations are taken from the MPC archive. When searching for a particular asteroid or comet, it is best to use the IAU number, as in 8467 for asteroid "8467 Benoitcarry". You can also try for numbered comet (e.g. 10P), or interstellar object (none so far...). If the number does not yet exist, you can search for designation. Here are some examples of valid queries:

  • Asteroids by number (default)
    • Asteroids (Main Belt): 8467, 1922, 33803
    • Asteroids (Hungarians): 18582, 77799
    • Asteroids (Jupiter Trojans): 4501, 1583
    • Asteroids (Mars Crossers): 302530
  • Asteroids by designation (if number does not exist yet)
    • 2010JO69, 2017AD19, 2012XK111
  • Comets by number (default)
    • 10P, 249P, 124P
  • Comets by designation (if number does no exist yet)
    • C/2020V2, C/2020R2

Designation

Note for designation, you can also use space (2010 JO69 or C/2020 V2).

In a unix shell, you would simply use

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

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

In python, you would use

import io
import requests
import pandas as pd

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

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

You can also get a votable using the json output format:

from astropy.table import Table

# get data for asteroid 8467 in JSON format...
r = ...

t = Table(r.json())

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

import requests
import pandas as pd

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

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content)) # (1)!
  1. Output fields: 
    Index(['index', 'Date', 'LAST', 'HA', 'Az', 'H', 'Dobs', 'Dhelio', 'VMag',
       'SDSS:g', 'SDSS:r', 'Phase', 'Elong.', 'AM', 'dRAcosDEC', 'dDEC', 'RV',
       'RA', 'Dec', 'Longitude', 'Latitude', 'd:cdsxmatch', 'd:mulens',
       'd:rf_kn_vs_nonkn', 'd:rf_snia_vs_nonia', 'd:roid', 'd:snn_sn_vs_all',
       'd:snn_snia_vs_nonia', 'i:candid', 'i:chipsf', 'i:classtar', 'i:dec',
       'i:diffmaglim', 'i:distnr', 'i:distpsnr1', 'i:drb', 'i:fid', 'i:field',
       'i:isdiffpos', 'i:jd', 'i:jdendhist', 'i:jdstarthist', 'i:maggaia',
       'i:magnr', 'i:magpsf', 'i:magzpsci', 'i:ndethist', 'i:neargaia',
       'i:nid', 'i:nmtchps', 'i:objectId', 'i:publisher', 'i:ra', 'i:rb',
       'i:rcid', 'i:sgscore1', 'i:sigmagnr', 'i:sigmapsf', 'i:ssdistnr',
       'i:ssmagnr', 'i:ssnamenr', 'i:tooflag', 'i:xpos', 'i:ypos',
       'd:tracklet', 'v:classification', 'v:lastdate', 'v:constellation',
       'i:magpsf_red'],
      dtype='object')

Where first columns are fields returned from Miriade (beware it adds few seconds delay).

Limitations

There are some limitations:

  • Color ephemerides are returned only for asteroids
  • Temporary designations (C/... or YYYY...) do not have ephemerides available

You can also query several objects at the same time:

import io
import requests
import pandas as pd

# get data for object 8467 and 1922
r = requests.post(
  "https://fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "8467,1922",
    "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, in which case you must give only a list of asteroid names or list of comet names (schemas for ephemerides are not the same).

Optimisation: selecting only a subset of fields

By default, we transfer all available data fields (original ZTF fields and Fink science module outputs). But you can also choose to transfer only a subset of the fields:

# select only jd, and magpsf
r = requests.post(
    "https://fink-portal.org/api/v1/sso",
    json={
        "n_or_d": "8467",
        "columns": "i:jd,i:magpsf"
    }
)

Note that the fields should be comma-separated. Unknown field names are ignored.

Finally you can query stamps for all alerts using the argument withcutouts:

import requests

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

# print one cutout
array = r.json()[0]["b:cutoutScience_stampData"] # (1)!
  1. Output: 
    [[123.70613861, 125.00068665, 129.01676941, ..., 123.77194214,
  130.44299316, 106.22817993],
 [121.61331177, 128.18247986, 124.99162292, ..., 115.30529785,
  129.93824768, 100.24826813],
 [124.31635284, 134.16503906, 125.13191223, ..., 131.05186462,
  116.30375671, 102.97401428],
 ...,
 [133.20661926, 123.14172363, 121.78632355, ..., 132.95498657,
  131.95939636, 111.22276306],
 [129.26271057, 127.34268188, 123.1470108 , ..., 126.02961731,
  128.23413086, 107.28420258],
 [126.06323242, 122.42414093, 121.47638702, ..., 129.28106689,
  131.03790283, 109.95378876]]

sso_example

Note that by default, the Science cutouts are downloaded (see also Image data). You can also ask for the Template or the Difference stamps:

# get data for object 8467
r = requests.post(
  "https://fink-portal.org/api/v1/sso",
  json={
    "n_or_d": "8467",
    "withcutouts": True,
    "cutout-kind": "Template",
    "output-format": "json"
  }
)

Performances

Downloading cutouts for SSO is time-consuming, and heavy for the server because (a) data is indexed against objectId and not ssnamenr and (b) decoding each binary gzipped FITS file has a cost. On average, it takes 0.5 second per alert.

For more information about the ZTF stamps, see https://irsa.ipac.caltech.edu/data/ZTF/docs/ztf_explanatory_supplement.pdf

Science Portal

On the portal, you can easily access to SSO data by name:

screenshot

or by number:

screenshot

Partial search

Because we run a partial number search, the query can return data for the wrong number. E.g. if you search for 8467, it will propose closest matches, but return data for 84673... We are working on it, but in the meantime, if you know exactly the number, prefix your query with sso=. In this case it will perform an exact search

screenshot

selecting the Solar System tab on any alert associated to a known SSO objects in the MPC gives you access to its lightcurve with ephemerides:

screenshot

You can inspect its astrometry, as well as phase curve modeling including the latest model including spin parameters from Carry et al 2024:

screenshot

SSoFT: Solar System object Fink Table

List of arguments

The list of arguments for retrieving alert data can be found at https://fink-portal.org/api/v1/ssoft, and the schema of the table (json) can be found at https://fink-portal.org/api/v1/ssoft?schema

This service lets you query the table containing aggregated parameters for known Solar System objects in Fink. This table is updated once a month, with all data in Fink.

Basic usage

In python, you would use

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "output-format": "parquet"
  }
)

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

or e.g. with curl:

curl -H "Content-Type: application/json" -X POST \
    -d '{"output-format":"parquet"}' \
    https://fink-portal.org/api/v1/ssoft -o ssoft.parquet

This table contains basic statistics (e.g. coverage in time for each object, name, number, ...), fitted parameters (absolute magnitude, phase parameters, spin parameters, ...), quality statuses, and version numbers. You can retrieve the schema of the table using using the schema argument:

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "schema": True
  }
)

schema = r.json()["args"]

or view it in your browser at https://fink-portal.org/api/v1/ssoft?schema.

Single object

You can also retrieve information about a single object, using its name or IAU number:

# using name
curl -H "Content-Type: application/json" -X POST -d '{"output-format":"json", "sso_name": "Autonoma"}' https://fink-portal.org/api/v1/ssoft

# using number
curl -H "Content-Type: application/json" -X POST -d '{"output-format":"json", "sso_number": "1465"}' https://fink-portal.org/api/v1/ssoft

or in Python:

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "sso_name": "Autonoma",
    "output-format": "parquet"
  }
)

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

Performance

Specifying the name or number does not reduce the querying time as we have to download the entire table (stored as a single file) under the hood.

Flavors

By default, we expose the parameters from the sHG1G2 model, that is HG1G2 augmented with shape and spin parameters (see Carry et al 2024). You can also choose standard HG or HG1G2 models:

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "flavor": "HG",
    "output-format": "parquet"
  }
)

Idem for the schema of the table: https://fink-portal.org/api/v1/ssoft?flavor=HG&schema.

Version

The table is versioned (YYYY.MM), and you can access previous versions (starts at 2023.07):

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "version": "2023.07",
    "output-format": "parquet"
  }
)

By default (that is version unspecified), the service will return the latest one.

Candidate Solar System objects

List of arguments

The list of arguments for retrieving SSO candidate data can be found at https://fink-portal.org/api/v1/ssocand

This service lets you query the information about candidate Solar System objects found by fink-fat (see Enabling discoveries of Solar System objects in large alert data streams). In python, you would use

import io
import requests
import pandas as pd

r = requests.post(
  "https://fink-portal.org/api/v1/ssocand",
  json={
    "kind": str, # (1)!
    "ssoCandId": int, # (2)!
    "start_date": str, # (3)!
    "stop_date": str, # (4)!
    "maxnumber": int, # (5)!
    "output-format": str
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))
  1. Mandatory, orbParams or lightcurves
  2. optional, if you know a trajectory ID. Otherwise returns all.
  3. optional. Only for lightcurves. Default is 2019-11-01
  4. optional. Only for lightcurves. Default is today.
  5. optional. Max number of entries to retrieve. Default is 10,000.

Depending on kind, you would get information on:

  • lightcurves: photometry of objects related to candidate orbits
  • orbParams: orbital parameters for orbit candidates

Adding more parameters from the BFT

The SSOFT of Fink contains only the parameters from the phase curve modeling. However you can easily join this table with the BFT table provided by IMCCE. This table contains physical and dynamical parameters for all known objects. Here is an example on joining the two tables:

import io
import requests
import pandas as pd

# Get the SSOFT
r0 = requests.post(
  "https://fink-portal.org/api/v1/ssoft",
  json={
    "output-format": "parquet"
  }
)

ssoft = pd.read_parquet(io.BytesIO(r0.content))

# Get the BFT
r1 = requests.get("https://ssp.imcce.fr/data/ssoBFT-latest_Asteroid.parquet")
bft = pd.read_parquet(io.BytesIO(r1.content))

# Join the two
combined = ssoft.merge(bft, left_on="name", right_on="sso_name", how="left")

Each row of the combined table will contain all information from Fink and all information from the BFT for an object! Beware though that the tables are quite big each, and you will need a lot of RAM to hold it in memory. In practice, choose only the columns you need before the merge. For example:

cols = [
    "sso_number",
    "sso_name",
    "sso_class",
    "orbital_elements.semi_major_axis.value",
    "orbital_elements.eccentricity.value",
    "orbital_elements.inclination.value",
    "orbital_elements.node_longitude.value",
    "orbital_elements.perihelion_argument.value",
    "orbital_elements.mean_anomaly.value",
    "orbital_elements.mean_motion.value",
    "family.family_number",
    "family.family_name",
    "proper_elements.proper_semi_major_axis.value",
    "proper_elements.proper_eccentricity.value",
    "proper_elements.proper_inclination.value",
    "proper_elements.proper_sine_inclination.value",
    "tisserand_parameters.Jupiter.value",
    "albedo.value",
    "absolute_magnitude.value",
    "diameter.value",
    "taxonomy.class",
    "taxonomy.complex",
    "taxonomy.waverange",
    "taxonomy.scheme",
    "taxonomy.technique",
]
bft = pd.read_parquet(io.BytesIO(r1.content), columns=cols)

combined = ssoft.merge(bft, left_on="name", right_on="sso_name", how="left")