COBS API help

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


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

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.

Parameter Type Default Description
type char comet type (e.g. P, N, C, I, A or M)
alt-des boolean false include alternate designations (if any) in objects fields section output
cur-mag int current comet magniturde limit
is-observed boolean false include only comets that have observations stored in COBS database
is-active boolean true include only comets that are active in the COBS database
page int 1 result query page. the number of results is limited to 5000 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

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.

Section Description
info general information about the API query
objects the objects field is an array of data, one for each comet from the database
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.

{
  "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:

Field Name Description
page current query page number
pages number of all query pages
start first item in the query page
end last item in the query page
length number of items on query page
recordsTotal total number of items in the query
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 (e.g. P, N, C, I, A or M)
name comet short name
fullname comet fullname
mpc_name comet mpc packed designation
icq_name comet designation used in the ICQ observation format
component comet component degination if available
current_mag comet current magnitude
perihelion_date comet perihelion date and time YYYY-MM-DD hh:mm
perihelion_mag comet magnitude calculated for the perihelion date
peak_mag comet peak magnitude
peak_mag_date date and time YYYY-MM-DD when the comet reaches the peak magnitude
is_observed true if observations of the comet are available in COBS database
is_observed true if comet is set as active in COBS database and new observations can be submitted
alias list of alternate designations (included if alt-des=true)
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
id alternate object ID
name short comet name
fullname full comet name
mpc_name comet 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)", "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.

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)
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 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

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


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

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.

Parameter Type Default Description
type char comet type (e.g. P, N, C, I, A or M)
alt-des boolean false include alternate designations (if any) in objects fields section output
cur-mag int current comet magniturde limit
is-observed boolean false include only comets that have observations stored in COBS database
is-active boolean true include only comets that are active in the COBS database
page int 1 result query page. the number of results is limited to 5000 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

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.

Section Description
info general information about the API query
objects the objects field is an array of data, one for each comet from the database
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.

{
  "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:

Field Name Description
page current query page number
pages number of all query pages
start first item in the query page
end last item in the query page
length number of items on query page
recordsTotal total number of items in the query
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 (e.g. P, N, C, I, A or M)
name comet short name
fullname comet fullname
mpc_name comet mpc packed designation
icq_name comet designation used in the ICQ observation format
component comet component degination if available
current_mag comet current magnitude
perihelion_date comet perihelion date and time YYYY-MM-DD hh:mm
perihelion_mag comet magnitude calculated for the perihelion date
peak_mag comet peak magnitude
peak_mag_date date and time YYYY-MM-DD when the comet reaches the peak magnitude
is_observed true if observations of the comet are available in COBS database
is_observed true if comet is set as active in COBS database and new observations can be submitted
alias list of alternate designations (included if alt-des=true)
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
id alternate object ID
name short comet name
fullname full comet name
mpc_name comet 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)", "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.

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)
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 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

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


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

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.

Parameter Type Default Description
type char comet type (e.g. P, N, C, I, A or M)
alt-des boolean false include alternate designations (if any) in objects fields section output
cur-mag int current comet magniturde limit
is-observed boolean false include only comets that have observations stored in COBS database
is-active boolean true include only comets that are active in the COBS database
page int 1 result query page. the number of results is limited to 5000 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

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.

Section Description
info general information about the API query
objects the objects field is an array of data, one for each comet from the database
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.

{
  "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:

Field Name Description
page current query page number
pages number of all query pages
start first item in the query page
end last item in the query page
length number of items on query page
recordsTotal total number of items in the query
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 (e.g. P, N, C, I, A or M)
name comet short name
fullname comet fullname
mpc_name comet mpc packed designation
icq_name comet designation used in the ICQ observation format
component comet component degination if available
current_mag comet current magnitude
perihelion_date comet perihelion date and time YYYY-MM-DD hh:mm
perihelion_mag comet magnitude calculated for the perihelion date
peak_mag comet peak magnitude
peak_mag_date date and time YYYY-MM-DD when the comet reaches the peak magnitude
is_observed true if observations of the comet are available in COBS database
is_observed true if comet is set as active in COBS database and new observations can be submitted
alias list of alternate designations (included if alt-des=true)
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
id alternate object ID
name short comet name
fullname full comet name
mpc_name comet 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)", "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.

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)
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 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

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


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

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.

Parameter Type Default Description
type char comet type (e.g. P, N, C, I, A or M)
alt-des boolean false include alternate designations (if any) in objects fields section output
cur-mag int current comet magniturde limit
is-observed boolean false include only comets that have observations stored in COBS database
is-active boolean true include only comets that are active in the COBS database
page int 1 result query page. the number of results is limited to 5000 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

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.

Section Description
info general information about the API query
objects the objects field is an array of data, one for each comet from the database
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.

{
  "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:

Field Name Description
page current query page number
pages number of all query pages
start first item in the query page
end last item in the query page
length number of items on query page
recordsTotal total number of items in the query
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 (e.g. P, N, C, I, A or M)
name comet short name
fullname comet fullname
mpc_name comet mpc packed designation
icq_name comet designation used in the ICQ observation format
component comet component degination if available
current_mag comet current magnitude
perihelion_date comet perihelion date and time YYYY-MM-DD hh:mm
perihelion_mag comet magnitude calculated for the perihelion date
peak_mag comet peak magnitude
peak_mag_date date and time YYYY-MM-DD when the comet reaches the peak magnitude
is_observed true if observations of the comet are available in COBS database
is_observed true if comet is set as active in COBS database and new observations can be submitted
alias list of alternate designations (included if alt-des=true)
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
id alternate object ID
name short comet name
fullname full comet name
mpc_name comet 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)", "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.

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)
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 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

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


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

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.

Parameter Type Default Description
type char comet type (e.g. P, N, C, I, A or M)
alt-des boolean false include alternate designations (if any) in objects fields section output
cur-mag int current comet magniturde limit
is-observed boolean false include only comets that have observations stored in COBS database
is-active boolean true include only comets that are active in the COBS database
page int 1 result query page. the number of results is limited to 5000 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

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.

Section Description
info general information about the API query
objects the objects field is an array of data, one for each comet from the database
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.

{
  "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:

Field Name Description
page current query page number
pages number of all query pages
start first item in the query page
end last item in the query page
length number of items on query page
recordsTotal total number of items in the query
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 (e.g. P, N, C, I, A or M)
name comet short name
fullname comet fullname
mpc_name comet mpc packed designation
icq_name comet designation used in the ICQ observation format
component comet component degination if available
current_mag comet current magnitude
perihelion_date comet perihelion date and time YYYY-MM-DD hh:mm
perihelion_mag comet magnitude calculated for the perihelion date
peak_mag comet peak magnitude
peak_mag_date date and time YYYY-MM-DD when the comet reaches the peak magnitude
is_observed true if observations of the comet are available in COBS database
is_observed true if comet is set as active in COBS database and new observations can be submitted
alias list of alternate designations (included if alt-des=true)
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
id alternate object ID
name short comet name
fullname full comet name
mpc_name comet 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)", "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.

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)
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 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