Comet Planner API

Version: 1.3 (2024 Sep)

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

HTTP Request

Example Queries

https://cobs.si/api/planner.api?date=2024-09-24&loc=106
https://cobs.si/api/planner.api?date=2024-09-24&lat=46.234&long=16.543&alt=520
https://cobs.si/api/planner.api?date=2024-09-24&loc=106&lim_mag=14&min_alt=0&min_sol=0&min_moon=0
https://cobs.si/api/planner.api?date=2024-09-24&loc=106&filter=1

Query Parameters

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

Data Output

Please always check the JSON payload “signature” object for the API “version”. If the version does not match the version in this document (at the top), there is no guarantee that the format has not changed.
Example "signature" object with "version" value "1.1": "signature":{"version":"1.3","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": {
    "name": "Crni Vrh",
    "lat": 45.945908,
    "long": 14.0711,
    "tz": "Europe/Ljubljana"
  },
  "sun events": {
    "Day ends": "2024-09-06 19:31 CEST",
    "Civil twilight ends": "2024-09-06 20:02 CEST",
    "Nautical twilight ends": "2024-09-06 20:38 CEST",
    "Astronomical twilight ends": "2024-09-06 21:16 CEST",
    "Astronomical twilight starts": "2024-09-07 04:47 CEST",
    "Nautical twilight starts": "2024-09-07 05:25 CEST",
    "Civil twilight starts": "2024-09-07 06:01 CEST",
    "Day starts": "2024-09-07 06:32 CEST"
  },
  "moon events": {
    "Set": "2024-09-06 20:38 CEST",
    "Rise": "2024-09-07 10:53 CEST",
    "Moon phase": 23.6
  },
  "session events": {
    "start_at": -12,
    "start_time": "2024-09-06 20:40 CEST",
    "end_time": "2024-09-07 05:23 CEST"
  },
  "limits": {
    "mag": 15,
    "alt": 10,
    "sun_elong": 10,
    "moon_elong": 10
  },
  "comet_list": [
    {
      "comet_type": "P",
      "comet_name": "13P",
      "comet_fullname": "13P/Olbers",
      "mpc_name": "13P",
      "best_time": "2024-09-06 20:40",
      "orbit_calc_source": 0,
      "magnitude": 8.2,
      "best_ra": "13:37:06.00",
      "best_dec": "15:44:30.4",
      "best_alt": 20.8,
      "sun_elongation": 39,
      "moon_elongation": 28,
      "constelation": "Coma Berenices",
      "rise_time": "2024-09-06 20:40",
      "set_time": "2024-09-06 22:46",
      "motion": 2.19,
      "pa": 125,
      "trend": "fade"
    },
    {
      "comet_type": "C",
      "comet_name": "C/2021 S3",
      "comet_fullname": "C/2021 S3 (PANSTARRS)",
      "mpc_name": "K21S030",
      "best_time": "2024-09-06 21:19",
      "orbit_calc_source": 0,
      "magnitude": 14.2,
      "best_ra": "19:21:39.20",
      "best_dec": "52:53:29.4",
      "best_alt": 83.1,
      "sun_elongation": 105,
      "moon_elongation": 99,
      "constelation": "Cygnus",
      "rise_time": "2024-09-06 20:40",
      "set_time": "2024-09-07 05:23",
      "motion": 0.69,
      "pa": 172,
      "trend": "fade"
    },
	...
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.3",
    "date": "2024 Sep"
  }
}

Sections Output

The following sections are available for output. The detailed structure of the contents within each section are described in corresponding document sections below.

Structure of Sections

The following shows the JSON structure of a normal data payload containing all possible sections. The detailed structure of the contents within each section are described in corresponding document sections below.

{
  "location": {
    location info fields ...
  },
  "sun events": {
    twilight events fields ...
  },
  "moon events": {
    moon events fields ...
  },  
  "session events": {
    session events fields ...
  },  
    "limits": {
    limits fields ...
  },  
  "comet_list": {
    comet list fields ...
  },  
  "signature": {
    signature fields ...
  },

Query Location Section

The following fields are provided in the location section:

Sun Events Section

The following fields are provided in the sun events section:

Moon Events Section

The following fields are provided in the moon events section:

Session Events Section

The following fields are provided in the session events section:

Limits Section

The following fields are provided in the limits section:

Comet List Section

The following fields are provided in the comet_list section:

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

Change Log

Version 1.3 (2024 Sep)

Added filter parameter to the query to enable filtering of the comets

Version 1.2 (2024 Sep)

Added mpc_name to the api response

Version 1.1 (2024 May)

Version 1.0 (2023 November)

Initial release