COBS API help

Comet API

Version: 1.3 (2024 Jun)

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",
	"mpc_name": "0249P",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "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
      }
    ]
  },
  "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
mpc_name comet MPC packed designation
icq_name comet designation used in the ICQ observation format
component component degination if available
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
mpc_name MPC packed designation

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.3 (2024 Jun)

Fix of comet alternative designation display bug.

Version 1.2 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.1 (2023 Feb)

Output of Physical parameters was enabled.

Version 1.0 (2022 Feb)

Initial release

Comet API

Version: 1.3 (2024 Jun)

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",
	"mpc_name": "0249P",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "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
      }
    ]
  },
  "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
mpc_name comet MPC packed designation
icq_name comet designation used in the ICQ observation format
component component degination if available
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
mpc_name MPC packed designation

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.3 (2024 Jun)

Fix of comet alternative designation display bug.

Version 1.2 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.1 (2023 Feb)

Output of Physical parameters was enabled.

Version 1.0 (2022 Feb)

Initial release

Comet API

Version: 1.3 (2024 Jun)

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",
	"mpc_name": "0249P",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "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
      }
    ]
  },
  "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
mpc_name comet MPC packed designation
icq_name comet designation used in the ICQ observation format
component component degination if available
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
mpc_name MPC packed designation

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.3 (2024 Jun)

Fix of comet alternative designation display bug.

Version 1.2 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.1 (2023 Feb)

Output of Physical parameters was enabled.

Version 1.0 (2022 Feb)

Initial release

Comet API

Version: 1.3 (2024 Jun)

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",
	"mpc_name": "0249P",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "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
      }
    ]
  },
  "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
mpc_name comet MPC packed designation
icq_name comet designation used in the ICQ observation format
component component degination if available
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
mpc_name MPC packed designation

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.3 (2024 Jun)

Fix of comet alternative designation display bug.

Version 1.2 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.1 (2023 Feb)

Output of Physical parameters was enabled.

Version 1.0 (2022 Feb)

Initial release

Comet API

Version: 1.3 (2024 Jun)

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",
	"mpc_name": "0249P",
    "icq_name": "0249",
    "component": null,
    "is_observed": true,
    "is_active": true,
    "alias": [
      {
        "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
      }
    ]
  },
  "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
mpc_name comet MPC packed designation
icq_name comet designation used in the ICQ observation format
component component degination if available
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
mpc_name MPC packed designation

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.3 (2024 Jun)

Fix of comet alternative designation display bug.

Version 1.2 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.1 (2023 Feb)

Output of Physical parameters was enabled.

Version 1.0 (2022 Feb)

Initial release