Comet API

Version: 1.1 (2023 February 27)

Comet API provides a method of requesting machine-readable data for a single comet object within the COBS database.

HTTP Request

---

GET https://cobs.si/api/comet.api

Example Queries

https://cobs.si/api/comet.api?des=249P
https://cobs.si/api/comet.api?id=421&alt-des=true&orbit=true&phys-par=true
https://cobs.si/api/comet.api?des=1995O1&full-prec=true

Query Parameters

---

One, and only one, of the following query parameters is required: id or des. All other parameters are optional.

Parameter	Type	Default	Description
id	int		object ID
des	string		object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
alt-des	boolean	false	include alternate designations (if any) in objects fields section output
orbit	boolean	false	output of output orbital elements (see Orbital Data Section below for details)
phys-par	boolean	false	output of output physical parameters (e.g., absolute magnitude: H; see Physical Parameters Section below for details)
full-prec	boolean	false	output data in full precision (normally, data are returned in reduced precision for display purposes)

Data Output

---

Please always check the JSON payload “signature” object for the API “version”. If the version does not match the version in this document (at the top), there is no guarantee that the format has not changed.
Example "signature" object with "version" value "1.0": "signature":{"version":"1.0","source":"COBS ... API"}

Normal Data Payload

---

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/comet.api?des=249P&alt-des=true&orbit=true&phys-par=true returns the following payload containing data sections objects.

{
  "object": {
    "id": 421,
    "type": "P",
    "name": "249P",
    "fullname": "249P/LINEAR",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "id": 413,
        "name": "P/2006 U1",
        "fullname": "P/2006 U1 (LINEAR)"
      },
      {
        "id": 416,
        "name": "P/2011 A4",
        "fullname": "P/2011 A4 (LINEAR)"
      }
    ]
  },
  "orbit": {
    "e": 0.82,
    "a": 2.76,
    "q": 0.5,
    "ad": 5.03,
    "i": 8.4,
    "om": 239,
    "w": 66,
    "ma": 127,
    "tp": 2459029.993,
    "tp_cd": "2020-06-29 11:48:20",
    "per": 4.593,
    "epoch": "2022-01-09",
    "reference": "MPEC 2021-S45"
  },
  "phys-par: {
    "H0": 17.5,
    "n": 3.9,
    "source": "MPC orbital elements"
  }
  "signature": {
    "source": "COBS Query API",
    "version": "1.1",
    "date": "2022 February 10"
  }
}

Sections Output

The following sections are available for output. The detailed structure of the contents within each section are described in corresponding document sections below.

Section	Description
objects	the objects field is an array of data for a specific comet from the database
orbit	the orbit field is an array of data with comets orbital elements
signature	JSON payload “signature” object with the API “version”

Structure of Sections

The following shows the JSON structure of a normal data payload containing all possible sections. The detailed structure of the contents within each section are described in corresponding document sections below.

{
  "object": {
    object fields ...
  },
  "orbit": {
    orbital elements fields ...
  },
  "signature": {
    signature fields ...
  },
}

Objects Data Section

The objects data section contains an array of comets from the COBS database.

The following fields are provided in the objects section:

Field Name	Description
id	primary object ID
type	comet type
name	short comet name
fullname	full comet name
component	component degination if available
icq_name	comet designation used in the ICQ observation format
is_observed	true if observations of the comet are available in COBS database
alias	list of alternate designations (included if alt-des=true)

Object subsection: alias

If alternate designations are requested (alt-des=true), the field “alias” will contain an array of alternate designations, or an emtpy array if no alternates are available. Each element in the array contains more key/value pair where the keys are the following:

key	description
id	alternate object ID
name	short comet name
fullname	full comet name

For example, here is the “alias” content for numbered comet 249P/LINEAR:

[
  {"id": 413, "name": "P/2006 U1", "fullname": "P/2006 U1 (LINEAR)"},
  {"id": 416, "name": "P/2011 A4", "fullname": "P/2011 A4 (LINEAR)"}
]

Orbit Data Section

The orbit data section contains an array of comets orbital elements calculated with SkyField.

The following fields are provided in the orbit section:

Short-name	Label	Description
e	e	eccentricity
a	a	semi-major axis (au)
q	q	perihelion distance (au)
ad	Q	aphelion distance (au)
i	i	inclination (deg)
om	node	longitude of the ascending node (deg)
w	peri	argument of perihelion (deg)
ma	M	mean anomaly (deg)
tp	tp	time of perihelion passage (TDB) formatted as Julian day
cd_tp	tp	time of perihelion passage (TDB) formatted as calendar date/time
per	period	orbital period (years)
epoch	epoch	epoch of the elements
ref	reference	orbital elements MPC reference

By default, the API returns data values in reduced precision, generally 3 significant digits (or 3 decimal digits for tp). If the full-prec parameter is specified in the API request, all data values are returned in full precision.

Physical Parameters Section

The physical parameters data section contains information about the physical parameters of the comet, such as the absolute magnitude parameters and slope parameter (H0 and n):

Short-name	Label	Description
H0	Comet absolute magnitude	Absolute magnitude of comet and coma (i.e. total)
n	Comet total magnitude slope	Comet total magnitude slope parameter
source	Calculation source	Source of the H0 and n parameters

HTTP Response Codes

---

All errors are returned via appropriate HTTP response codes.

HTTP Code	Description	Typical Usage
200	OK	normal successful result for a query: object data returned (an error message is returned if the object was not found)
300	Multiple Choices	the specified parameters matched more than one object
400	Bad Request	the request contained invalid keywords and/or content: details returned
500	Internal Server Error	the database is not available at the time of the request

Change Log

---

Version 1.1 (2023 February)

Output of Physical parameters was enabled.

---

Version 1.0 (2022 February)

Initial release

{
  "object": {
    "id": 421,
    "type": "P",
    "name": "249P",
    "fullname": "249P/LINEAR",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "id": 413,
        "name": "P/2006 U1",
        "fullname": "P/2006 U1 (LINEAR)"
      },
      {
        "id": 416,
        "name": "P/2011 A4",
        "fullname": "P/2011 A4 (LINEAR)"
      }
    ]
  },
  "orbit": {
    "e": 0.82,
    "a": 2.76,
    "q": 0.5,
    "ad": 5.03,
    "i": 8.4,
    "om": 239,
    "w": 66,
    "ma": 127,
    "tp": 2459029.993,
    "tp_cd": "2020-06-29 11:48:20",
    "per": 4.593,
    "epoch": "2022-01-09",
    "reference": "MPEC 2021-S45"
  },
  "phys-par: {
    "H0": 17.5,
    "n": 3.9,
    "source": "MPC orbital elements"
  }
  "signature": {
    "source": "COBS Query API",
    "version": "1.1",
    "date": "2022 February 10"
  }
}

{
  "object": {
    object fields ...
  },
  "orbit": {
    orbital elements fields ...
  },
  "signature": {
    signature fields ...
  },
}

[
  {"id": 413, "name": "P/2006 U1", "fullname": "P/2006 U1 (LINEAR)"},
  {"id": 416, "name": "P/2011 A4", "fullname": "P/2011 A4 (LINEAR)"}
]

{
  "object": {
    "id": 421,
    "type": "P",
    "name": "249P",
    "fullname": "249P/LINEAR",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "id": 413,
        "name": "P/2006 U1",
        "fullname": "P/2006 U1 (LINEAR)"
      },
      {
        "id": 416,
        "name": "P/2011 A4",
        "fullname": "P/2011 A4 (LINEAR)"
      }
    ]
  },
  "orbit": {
    "e": 0.82,
    "a": 2.76,
    "q": 0.5,
    "ad": 5.03,
    "i": 8.4,
    "om": 239,
    "w": 66,
    "ma": 127,
    "tp": 2459029.993,
    "tp_cd": "2020-06-29 11:48:20",
    "per": 4.593,
    "epoch": "2022-01-09",
    "reference": "MPEC 2021-S45"
  },
  "phys-par: {
    "H0": 17.5,
    "n": 3.9,
    "source": "MPC orbital elements"
  }
  "signature": {
    "source": "COBS Query API",
    "version": "1.1",
    "date": "2022 February 10"
  }
}

{
  "object": {
    object fields ...
  },
  "orbit": {
    orbital elements fields ...
  },
  "signature": {
    signature fields ...
  },
}

[
  {"id": 413, "name": "P/2006 U1", "fullname": "P/2006 U1 (LINEAR)"},
  {"id": 416, "name": "P/2011 A4", "fullname": "P/2011 A4 (LINEAR)"}
]

{
  "object": {
    "id": 421,
    "type": "P",
    "name": "249P",
    "fullname": "249P/LINEAR",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "id": 413,
        "name": "P/2006 U1",
        "fullname": "P/2006 U1 (LINEAR)"
      },
      {
        "id": 416,
        "name": "P/2011 A4",
        "fullname": "P/2011 A4 (LINEAR)"
      }
    ]
  },
  "orbit": {
    "e": 0.82,
    "a": 2.76,
    "q": 0.5,
    "ad": 5.03,
    "i": 8.4,
    "om": 239,
    "w": 66,
    "ma": 127,
    "tp": 2459029.993,
    "tp_cd": "2020-06-29 11:48:20",
    "per": 4.593,
    "epoch": "2022-01-09",
    "reference": "MPEC 2021-S45"
  },
  "phys-par: {
    "H0": 17.5,
    "n": 3.9,
    "source": "MPC orbital elements"
  }
  "signature": {
    "source": "COBS Query API",
    "version": "1.1",
    "date": "2022 February 10"
  }
}

{
  "object": {
    object fields ...
  },
  "orbit": {
    orbital elements fields ...
  },
  "signature": {
    signature fields ...
  },
}

[
  {"id": 413, "name": "P/2006 U1", "fullname": "P/2006 U1 (LINEAR)"},
  {"id": 416, "name": "P/2011 A4", "fullname": "P/2011 A4 (LINEAR)"}
]

{
  "object": {
    "id": 421,
    "type": "P",
    "name": "249P",
    "fullname": "249P/LINEAR",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "id": 413,
        "name": "P/2006 U1",
        "fullname": "P/2006 U1 (LINEAR)"
      },
      {
        "id": 416,
        "name": "P/2011 A4",
        "fullname": "P/2011 A4 (LINEAR)"
      }
    ]
  },
  "orbit": {
    "e": 0.82,
    "a": 2.76,
    "q": 0.5,
    "ad": 5.03,
    "i": 8.4,
    "om": 239,
    "w": 66,
    "ma": 127,
    "tp": 2459029.993,
    "tp_cd": "2020-06-29 11:48:20",
    "per": 4.593,
    "epoch": "2022-01-09",
    "reference": "MPEC 2021-S45"
  },
  "phys-par: {
    "H0": 17.5,
    "n": 3.9,
    "source": "MPC orbital elements"
  }
  "signature": {
    "source": "COBS Query API",
    "version": "1.1",
    "date": "2022 February 10"
  }
}

{
  "object": {
    object fields ...
  },
  "orbit": {
    orbital elements fields ...
  },
  "signature": {
    signature fields ...
  },
}

[
  {"id": 413, "name": "P/2006 U1", "fullname": "P/2006 U1 (LINEAR)"},
  {"id": 416, "name": "P/2011 A4", "fullname": "P/2011 A4 (LINEAR)"}
]