COBS API help

Comet Planner API

Version: 1.0 (2023 November 03)

Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.

HTTP Request

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

 

Example Queries

https://cobs.si/api/planner.api?loc=106
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?

Query Parameters

Parameters should be used to limit the number of observations returned by the query.

Parameter Type Default Description
loc string   MPC observatory code
lat float   Location latitude in decimal degrees, positive north of equator e.g. 34.984 and NOT 34°59'2"
long float   Location longitude in decimal degrees, positive east of Greenwich e.g. -110.392 and NOT -110°23'31".  
alt float   Location elevation in meters.
date date   Session date for which you want to calculate the observable comet list.
min_alt float   Minimum object altitude above horizon in degrees.
lim_mag float   Limiting object magnitude.
min_sol float   Minimum solar elongation in degrees.
min_moon float   Minimum moon elongation in degrees.

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 MPC observatory code location.
The following example query https://cobs.si/api/planner.api?loc=106 returns the following payload containing data sections objects.

{
  "location": {
    "location_lat": 45.945908,
    "location_long": 14.0711,
    "location_elev": 711.299,
    "tz": "UTC",
    "location_code": "106",
    "location_name": "Crni Vrh"
  },
  "sun events": {
    "Day ends": "2023-11-03 15:47 UTC",
    "Civil twilight ends": "2023-11-03 16:18 UTC",
    "Nautical twilight ends": "2023-11-03 16:54 UTC",
    "Astronomical twilight ends": "2023-11-03 17:28 UTC",
    "Astronomical twilight starts": "2023-11-04 04:06 UTC",
    "Nautical twilight starts": "2023-11-04 04:40 UTC",
    "Civil twilight starts": "2023-11-04 05:16 UTC",
    "Day starts": "2023-11-04 05:47 UTC"
  },
  "moon events": {
    "Rise": "2023-11-03 19:59 UTC",
    "Moon phase": 58.3
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2022A2",
      "comet_fullname": "C/2022 A2 (PANSTARRS)",
      "best_time": "2023-11-03 18:48",
      "orbit_calc_source": 1,
      "magnitude": "14.2",
      "best_ra": "22:36:10.28",
      "best_dec": "-8:16:06.8",
      "best_alt": 35.8,
      "sun_distance": 116,
      "moon_distance": 136,
      "constelation": "Aquarius",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-03 23:12",
      "motion": 0.57,
      "pa": 201,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "2021X1",
      "comet_fullname": "C/2021 X1 (Maury-Attard)",
      "best_time": "2023-11-03 19:23",
      "orbit_calc_source": 1,
      "magnitude": "14.9",
      "best_ra": "23:11:06.20",
      "best_dec": "3:53:05.4",
      "best_alt": 47.9,
      "sun_distance": 129,
      "moon_distance": 123,
      "constelation": "Pisces",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-04 00:40",
      "motion": 1.01,
      "pa": 262,
      "trend": "fade"
    },
    ...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.0"
  }
}
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
location Information about the given location the comet list is calculated for.
sun events Twilight events calculated for the given location.
moon events Moon rise and set times calculated for the given location.
comet_list List of observable comets.
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.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },
Query Location Section

The following fields are provided in the location section:

Field Name Description
location_lat Location latitide in degrees.
location_long Location longitude in degrees.
location_elev Location altitude in meters.
tz Time zone for the calculated output times. Default is UTC.
location_code Location MPC observatory code if given in the query.
location_name Location MPC observatory name if location was given as a MPC code.
Sun Events Section

The following fields are provided in the sun events section:

Field Name Description
Day ends Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Civil twilight ends Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Civil twilight starts Date and time YYYY-MM-DD hh:mm UTC
Day starts IDate and time YYYY-MM-DD hh:mm UTC
Moon Events Section

The following fields are provided in the moon events section:

Field Name Description
Rise Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Set Date and time YYYY-MM-DD hh:mm UTC
Moon phase Date and time YYYY-MM-DD hh:mm UTC
Comet List Section

The following fields are provided in the comet_list section:

Field Name Description
comet_type  
comet_name  
comet_fullname  
best_time Date and time YYYY-MM-DD hh:mm UTC
orbit_calc_source 1 2 3 4
magnitude  
best_ra  
best_dec  
best_alt  
sun_distance  
moon_distance  
constelation  
rise_time  
set_time  
motion  
pa  
trend  

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 (2023 November 03)

Initial release

Comet Planner API

Version: 1.0 (2023 November 03)

Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.

HTTP Request

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

 

Example Queries

https://cobs.si/api/planner.api?loc=106
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?

Query Parameters

Parameters should be used to limit the number of observations returned by the query.

Parameter Type Default Description
loc string   MPC observatory code
lat float   Location latitude in decimal degrees, positive north of equator e.g. 34.984 and NOT 34°59'2"
long float   Location longitude in decimal degrees, positive east of Greenwich e.g. -110.392 and NOT -110°23'31".  
alt float   Location elevation in meters.
date date   Session date for which you want to calculate the observable comet list.
min_alt float   Minimum object altitude above horizon in degrees.
lim_mag float   Limiting object magnitude.
min_sol float   Minimum solar elongation in degrees.
min_moon float   Minimum moon elongation in degrees.

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 MPC observatory code location.
The following example query https://cobs.si/api/planner.api?loc=106 returns the following payload containing data sections objects.

{
  "location": {
    "location_lat": 45.945908,
    "location_long": 14.0711,
    "location_elev": 711.299,
    "tz": "UTC",
    "location_code": "106",
    "location_name": "Crni Vrh"
  },
  "sun events": {
    "Day ends": "2023-11-03 15:47 UTC",
    "Civil twilight ends": "2023-11-03 16:18 UTC",
    "Nautical twilight ends": "2023-11-03 16:54 UTC",
    "Astronomical twilight ends": "2023-11-03 17:28 UTC",
    "Astronomical twilight starts": "2023-11-04 04:06 UTC",
    "Nautical twilight starts": "2023-11-04 04:40 UTC",
    "Civil twilight starts": "2023-11-04 05:16 UTC",
    "Day starts": "2023-11-04 05:47 UTC"
  },
  "moon events": {
    "Rise": "2023-11-03 19:59 UTC",
    "Moon phase": 58.3
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2022A2",
      "comet_fullname": "C/2022 A2 (PANSTARRS)",
      "best_time": "2023-11-03 18:48",
      "orbit_calc_source": 1,
      "magnitude": "14.2",
      "best_ra": "22:36:10.28",
      "best_dec": "-8:16:06.8",
      "best_alt": 35.8,
      "sun_distance": 116,
      "moon_distance": 136,
      "constelation": "Aquarius",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-03 23:12",
      "motion": 0.57,
      "pa": 201,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "2021X1",
      "comet_fullname": "C/2021 X1 (Maury-Attard)",
      "best_time": "2023-11-03 19:23",
      "orbit_calc_source": 1,
      "magnitude": "14.9",
      "best_ra": "23:11:06.20",
      "best_dec": "3:53:05.4",
      "best_alt": 47.9,
      "sun_distance": 129,
      "moon_distance": 123,
      "constelation": "Pisces",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-04 00:40",
      "motion": 1.01,
      "pa": 262,
      "trend": "fade"
    },
    ...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.0"
  }
}
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
location Information about the given location the comet list is calculated for.
sun events Twilight events calculated for the given location.
moon events Moon rise and set times calculated for the given location.
comet_list List of observable comets.
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.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },
Query Location Section

The following fields are provided in the location section:

Field Name Description
location_lat Location latitide in degrees.
location_long Location longitude in degrees.
location_elev Location altitude in meters.
tz Time zone for the calculated output times. Default is UTC.
location_code Location MPC observatory code if given in the query.
location_name Location MPC observatory name if location was given as a MPC code.
Sun Events Section

The following fields are provided in the sun events section:

Field Name Description
Day ends Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Civil twilight ends Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Civil twilight starts Date and time YYYY-MM-DD hh:mm UTC
Day starts IDate and time YYYY-MM-DD hh:mm UTC
Moon Events Section

The following fields are provided in the moon events section:

Field Name Description
Rise Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Set Date and time YYYY-MM-DD hh:mm UTC
Moon phase Date and time YYYY-MM-DD hh:mm UTC
Comet List Section

The following fields are provided in the comet_list section:

Field Name Description
comet_type  
comet_name  
comet_fullname  
best_time Date and time YYYY-MM-DD hh:mm UTC
orbit_calc_source 1 2 3 4
magnitude  
best_ra  
best_dec  
best_alt  
sun_distance  
moon_distance  
constelation  
rise_time  
set_time  
motion  
pa  
trend  

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 (2023 November 03)

Initial release

Comet Planner API

Version: 1.0 (2023 November 03)

Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.

HTTP Request

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

 

Example Queries

https://cobs.si/api/planner.api?loc=106
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?

Query Parameters

Parameters should be used to limit the number of observations returned by the query.

Parameter Type Default Description
loc string   MPC observatory code
lat float   Location latitude in decimal degrees, positive north of equator e.g. 34.984 and NOT 34°59'2"
long float   Location longitude in decimal degrees, positive east of Greenwich e.g. -110.392 and NOT -110°23'31".  
alt float   Location elevation in meters.
date date   Session date for which you want to calculate the observable comet list.
min_alt float   Minimum object altitude above horizon in degrees.
lim_mag float   Limiting object magnitude.
min_sol float   Minimum solar elongation in degrees.
min_moon float   Minimum moon elongation in degrees.

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 MPC observatory code location.
The following example query https://cobs.si/api/planner.api?loc=106 returns the following payload containing data sections objects.

{
  "location": {
    "location_lat": 45.945908,
    "location_long": 14.0711,
    "location_elev": 711.299,
    "tz": "UTC",
    "location_code": "106",
    "location_name": "Crni Vrh"
  },
  "sun events": {
    "Day ends": "2023-11-03 15:47 UTC",
    "Civil twilight ends": "2023-11-03 16:18 UTC",
    "Nautical twilight ends": "2023-11-03 16:54 UTC",
    "Astronomical twilight ends": "2023-11-03 17:28 UTC",
    "Astronomical twilight starts": "2023-11-04 04:06 UTC",
    "Nautical twilight starts": "2023-11-04 04:40 UTC",
    "Civil twilight starts": "2023-11-04 05:16 UTC",
    "Day starts": "2023-11-04 05:47 UTC"
  },
  "moon events": {
    "Rise": "2023-11-03 19:59 UTC",
    "Moon phase": 58.3
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2022A2",
      "comet_fullname": "C/2022 A2 (PANSTARRS)",
      "best_time": "2023-11-03 18:48",
      "orbit_calc_source": 1,
      "magnitude": "14.2",
      "best_ra": "22:36:10.28",
      "best_dec": "-8:16:06.8",
      "best_alt": 35.8,
      "sun_distance": 116,
      "moon_distance": 136,
      "constelation": "Aquarius",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-03 23:12",
      "motion": 0.57,
      "pa": 201,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "2021X1",
      "comet_fullname": "C/2021 X1 (Maury-Attard)",
      "best_time": "2023-11-03 19:23",
      "orbit_calc_source": 1,
      "magnitude": "14.9",
      "best_ra": "23:11:06.20",
      "best_dec": "3:53:05.4",
      "best_alt": 47.9,
      "sun_distance": 129,
      "moon_distance": 123,
      "constelation": "Pisces",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-04 00:40",
      "motion": 1.01,
      "pa": 262,
      "trend": "fade"
    },
    ...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.0"
  }
}
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
location Information about the given location the comet list is calculated for.
sun events Twilight events calculated for the given location.
moon events Moon rise and set times calculated for the given location.
comet_list List of observable comets.
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.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },
Query Location Section

The following fields are provided in the location section:

Field Name Description
location_lat Location latitide in degrees.
location_long Location longitude in degrees.
location_elev Location altitude in meters.
tz Time zone for the calculated output times. Default is UTC.
location_code Location MPC observatory code if given in the query.
location_name Location MPC observatory name if location was given as a MPC code.
Sun Events Section

The following fields are provided in the sun events section:

Field Name Description
Day ends Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Civil twilight ends Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Civil twilight starts Date and time YYYY-MM-DD hh:mm UTC
Day starts IDate and time YYYY-MM-DD hh:mm UTC
Moon Events Section

The following fields are provided in the moon events section:

Field Name Description
Rise Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Set Date and time YYYY-MM-DD hh:mm UTC
Moon phase Date and time YYYY-MM-DD hh:mm UTC
Comet List Section

The following fields are provided in the comet_list section:

Field Name Description
comet_type  
comet_name  
comet_fullname  
best_time Date and time YYYY-MM-DD hh:mm UTC
orbit_calc_source 1 2 3 4
magnitude  
best_ra  
best_dec  
best_alt  
sun_distance  
moon_distance  
constelation  
rise_time  
set_time  
motion  
pa  
trend  

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 (2023 November 03)

Initial release

Comet Planner API

Version: 1.0 (2023 November 03)

Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.

HTTP Request

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

 

Example Queries

https://cobs.si/api/planner.api?loc=106
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?

Query Parameters

Parameters should be used to limit the number of observations returned by the query.

Parameter Type Default Description
loc string   MPC observatory code
lat float   Location latitude in decimal degrees, positive north of equator e.g. 34.984 and NOT 34°59'2"
long float   Location longitude in decimal degrees, positive east of Greenwich e.g. -110.392 and NOT -110°23'31".  
alt float   Location elevation in meters.
date date   Session date for which you want to calculate the observable comet list.
min_alt float   Minimum object altitude above horizon in degrees.
lim_mag float   Limiting object magnitude.
min_sol float   Minimum solar elongation in degrees.
min_moon float   Minimum moon elongation in degrees.

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 MPC observatory code location.
The following example query https://cobs.si/api/planner.api?loc=106 returns the following payload containing data sections objects.

{
  "location": {
    "location_lat": 45.945908,
    "location_long": 14.0711,
    "location_elev": 711.299,
    "tz": "UTC",
    "location_code": "106",
    "location_name": "Crni Vrh"
  },
  "sun events": {
    "Day ends": "2023-11-03 15:47 UTC",
    "Civil twilight ends": "2023-11-03 16:18 UTC",
    "Nautical twilight ends": "2023-11-03 16:54 UTC",
    "Astronomical twilight ends": "2023-11-03 17:28 UTC",
    "Astronomical twilight starts": "2023-11-04 04:06 UTC",
    "Nautical twilight starts": "2023-11-04 04:40 UTC",
    "Civil twilight starts": "2023-11-04 05:16 UTC",
    "Day starts": "2023-11-04 05:47 UTC"
  },
  "moon events": {
    "Rise": "2023-11-03 19:59 UTC",
    "Moon phase": 58.3
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2022A2",
      "comet_fullname": "C/2022 A2 (PANSTARRS)",
      "best_time": "2023-11-03 18:48",
      "orbit_calc_source": 1,
      "magnitude": "14.2",
      "best_ra": "22:36:10.28",
      "best_dec": "-8:16:06.8",
      "best_alt": 35.8,
      "sun_distance": 116,
      "moon_distance": 136,
      "constelation": "Aquarius",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-03 23:12",
      "motion": 0.57,
      "pa": 201,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "2021X1",
      "comet_fullname": "C/2021 X1 (Maury-Attard)",
      "best_time": "2023-11-03 19:23",
      "orbit_calc_source": 1,
      "magnitude": "14.9",
      "best_ra": "23:11:06.20",
      "best_dec": "3:53:05.4",
      "best_alt": 47.9,
      "sun_distance": 129,
      "moon_distance": 123,
      "constelation": "Pisces",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-04 00:40",
      "motion": 1.01,
      "pa": 262,
      "trend": "fade"
    },
    ...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.0"
  }
}
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
location Information about the given location the comet list is calculated for.
sun events Twilight events calculated for the given location.
moon events Moon rise and set times calculated for the given location.
comet_list List of observable comets.
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.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },
Query Location Section

The following fields are provided in the location section:

Field Name Description
location_lat Location latitide in degrees.
location_long Location longitude in degrees.
location_elev Location altitude in meters.
tz Time zone for the calculated output times. Default is UTC.
location_code Location MPC observatory code if given in the query.
location_name Location MPC observatory name if location was given as a MPC code.
Sun Events Section

The following fields are provided in the sun events section:

Field Name Description
Day ends Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Civil twilight ends Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Civil twilight starts Date and time YYYY-MM-DD hh:mm UTC
Day starts IDate and time YYYY-MM-DD hh:mm UTC
Moon Events Section

The following fields are provided in the moon events section:

Field Name Description
Rise Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Set Date and time YYYY-MM-DD hh:mm UTC
Moon phase Date and time YYYY-MM-DD hh:mm UTC
Comet List Section

The following fields are provided in the comet_list section:

Field Name Description
comet_type  
comet_name  
comet_fullname  
best_time Date and time YYYY-MM-DD hh:mm UTC
orbit_calc_source 1 2 3 4
magnitude  
best_ra  
best_dec  
best_alt  
sun_distance  
moon_distance  
constelation  
rise_time  
set_time  
motion  
pa  
trend  

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 (2023 November 03)

Initial release

Comet Planner API

Version: 1.0 (2023 November 03)

Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.

HTTP Request

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

 

Example Queries

https://cobs.si/api/planner.api?loc=106
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?
https://cobs.si/api/planner.api?

Query Parameters

Parameters should be used to limit the number of observations returned by the query.

Parameter Type Default Description
loc string   MPC observatory code
lat float   Location latitude in decimal degrees, positive north of equator e.g. 34.984 and NOT 34°59'2"
long float   Location longitude in decimal degrees, positive east of Greenwich e.g. -110.392 and NOT -110°23'31".  
alt float   Location elevation in meters.
date date   Session date for which you want to calculate the observable comet list.
min_alt float   Minimum object altitude above horizon in degrees.
lim_mag float   Limiting object magnitude.
min_sol float   Minimum solar elongation in degrees.
min_moon float   Minimum moon elongation in degrees.

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 MPC observatory code location.
The following example query https://cobs.si/api/planner.api?loc=106 returns the following payload containing data sections objects.

{
  "location": {
    "location_lat": 45.945908,
    "location_long": 14.0711,
    "location_elev": 711.299,
    "tz": "UTC",
    "location_code": "106",
    "location_name": "Crni Vrh"
  },
  "sun events": {
    "Day ends": "2023-11-03 15:47 UTC",
    "Civil twilight ends": "2023-11-03 16:18 UTC",
    "Nautical twilight ends": "2023-11-03 16:54 UTC",
    "Astronomical twilight ends": "2023-11-03 17:28 UTC",
    "Astronomical twilight starts": "2023-11-04 04:06 UTC",
    "Nautical twilight starts": "2023-11-04 04:40 UTC",
    "Civil twilight starts": "2023-11-04 05:16 UTC",
    "Day starts": "2023-11-04 05:47 UTC"
  },
  "moon events": {
    "Rise": "2023-11-03 19:59 UTC",
    "Moon phase": 58.3
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2022A2",
      "comet_fullname": "C/2022 A2 (PANSTARRS)",
      "best_time": "2023-11-03 18:48",
      "orbit_calc_source": 1,
      "magnitude": "14.2",
      "best_ra": "22:36:10.28",
      "best_dec": "-8:16:06.8",
      "best_alt": 35.8,
      "sun_distance": 116,
      "moon_distance": 136,
      "constelation": "Aquarius",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-03 23:12",
      "motion": 0.57,
      "pa": 201,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "2021X1",
      "comet_fullname": "C/2021 X1 (Maury-Attard)",
      "best_time": "2023-11-03 19:23",
      "orbit_calc_source": 1,
      "magnitude": "14.9",
      "best_ra": "23:11:06.20",
      "best_dec": "3:53:05.4",
      "best_alt": 47.9,
      "sun_distance": 129,
      "moon_distance": 123,
      "constelation": "Pisces",
      "rise_time": "2023-11-03 16:55",
      "set_time": "2023-11-04 00:40",
      "motion": 1.01,
      "pa": 262,
      "trend": "fade"
    },
    ...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.0"
  }
}
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
location Information about the given location the comet list is calculated for.
sun events Twilight events calculated for the given location.
moon events Moon rise and set times calculated for the given location.
comet_list List of observable comets.
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.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },
Query Location Section

The following fields are provided in the location section:

Field Name Description
location_lat Location latitide in degrees.
location_long Location longitude in degrees.
location_elev Location altitude in meters.
tz Time zone for the calculated output times. Default is UTC.
location_code Location MPC observatory code if given in the query.
location_name Location MPC observatory name if location was given as a MPC code.
Sun Events Section

The following fields are provided in the sun events section:

Field Name Description
Day ends Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Civil twilight ends Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight ends Date and time YYYY-MM-DD hh:mm UTC
Astronomical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Nautical twilight starts Date and time YYYY-MM-DD hh:mm UTC
Civil twilight starts Date and time YYYY-MM-DD hh:mm UTC
Day starts IDate and time YYYY-MM-DD hh:mm UTC
Moon Events Section

The following fields are provided in the moon events section:

Field Name Description
Rise Date and time YYYY-MM-DD hh:mm UTC when sun sets (0 degrees altitude)
Set Date and time YYYY-MM-DD hh:mm UTC
Moon phase Date and time YYYY-MM-DD hh:mm UTC
Comet List Section

The following fields are provided in the comet_list section:

Field Name Description
comet_type  
comet_name  
comet_fullname  
best_time Date and time YYYY-MM-DD hh:mm UTC
orbit_calc_source 1 2 3 4
magnitude  
best_ra  
best_dec  
best_alt  
sun_distance  
moon_distance  
constelation  
rise_time  
set_time  
motion  
pa  
trend  

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 (2023 November 03)

Initial release