COBS API help

Comet API

Version: 1.0 (2022 February 10)

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?dec=249P
https://cobs.si/api/comet.api?pk=421&alt-des=1&no-orbit=1
https://cobs.si/api/comet.api?des=1995O1&full-prec=1

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, C/1995 O1) or as ICQ comet name (e.g., 0141, 1995O1)
alt-des boolean false include alternate designations (if any) in objects fields section output
no-orbit boolean false suppress output of the orbital elements
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=1 returns the following payload containing data sections objects.

{
  "object": {
    "pk": 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"
  },
  "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
pk 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=1)
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:

key description
pk 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.

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.0 (2022 February)

Initial release

Comet API

Version: 1.0 (2022 February 10)

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?dec=249P
https://cobs.si/api/comet.api?pk=421&alt-des=1&no-orbit=1
https://cobs.si/api/comet.api?des=1995O1&full-prec=1

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, C/1995 O1) or as ICQ comet name (e.g., 0141, 1995O1)
alt-des boolean false include alternate designations (if any) in objects fields section output
no-orbit boolean false suppress output of the orbital elements
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=1 returns the following payload containing data sections objects.

{
  "object": {
    "pk": 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"
  },
  "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
pk 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=1)
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:

key description
pk 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.

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.0 (2022 February)

Initial release

Comet API

Version: 1.0 (2022 February 10)

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?dec=249P
https://cobs.si/api/comet.api?pk=421&alt-des=1&no-orbit=1
https://cobs.si/api/comet.api?des=1995O1&full-prec=1

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, C/1995 O1) or as ICQ comet name (e.g., 0141, 1995O1)
alt-des boolean false include alternate designations (if any) in objects fields section output
no-orbit boolean false suppress output of the orbital elements
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=1 returns the following payload containing data sections objects.

{
  "object": {
    "pk": 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"
  },
  "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
pk 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=1)
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:

key description
pk 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.

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.0 (2022 February)

Initial release