Comet List API

Version: 1.3 (2024 May)

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

HTTP Request

Example Queries

https://cobs.si/api/comet_list.api?type=C&page=1
https://cobs.si/api/comet_list.api?type=P&is-observed=1&page=1 https://cobs.si/api/comet_list.api?is-observed=1&cur-mag=15&page=1

Query Parameters

All parameters are optional. If non are specified the list of all comets will be returned by the query.

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_list.api?type=C&alt-des=true&cur-mag=15&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1,
    "pages": 1,
    "start": 1,
    "end": 10,
    "length": 5000,
    "recordsTotal": 10
  },
  "objects": [
    {
      "id": 1670,
      "type": "C",
      "name": "C/2017 K2",
      "fullname": "C/2017 K2 (PANSTARRS)",
      "mpc_name": "K17K020",
      "icq_name": "2017K2",
      "component": null,
      "current_mag": "14.7",
      "perihelion_date": "2022-12-19 13:29",
      "perihelion_mag": "9.9",
      "peak_mag": "9.8",
      "peak_mag_date": "2023-01-25",
      "is_observed": true,
      "is_active": true,
      "alias": []
    },
    {
      "id": 1805,
      "type": "C",
      "name": "C/2019 L3",
      "fullname": "C/2019 L3 (ATLAS)",
      "mpc_name": "K19L030",
      "icq_name": "2019L3",
      "component": null,
      "current_mag": "14.7",
      "perihelion_date": "2022-01-09 20:33",
      "perihelion_mag": "9.4",
      "peak_mag": "9.4",
      "peak_mag_date": "2022-01-07",
      "is_observed": true,
      "is_active": true,
      "alias": []
    },
	...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.2",
    "date": "2024 May"
  }
}

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.

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.

{
  "info": {
    query info fields ...
  },
  "object": {
    object fields ...
  },
  "signature": {
    signature fields ...
  },
}

Query Info Section

General information about the API query.

The following fields are provided in the general information section:

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:

Object subsection: alias

If alternate designations are requested (alt-des=1), 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:

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

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

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

Change Log

Version 1.3 (2024 May)

MPC packed designation added to the response.

Version 1.2 (2024 May)

Parameter cur_mag added as an option to filter comets by current magnitude.
Values for current_mag, perihelion_date, perihelion_mag, peak_mag and peak_mag_date added to the JSON resposnes.

Version 1.1 (2023 March)

Queries are paginated with max 5000 items.

Version 1.0 (2022 February)

Initial release