Comet Planner API

Version: 1.1 (2024 May)

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=2014-05-10&loc=106
https://cobs.si/api/planner.api?date=2024-05-10&lat=46.234&long=16.543&alt=520
https://cobs.si/api/planner.api?date=2014-05-10&loc=106&lim_mag=14&min_alt=0&min_sol=0&min_moon=0

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.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": {
    "name": "Crni Vrh",
    "lat": 45.945908,
    "long": 14.0711,
    "tz": "Europe/Ljubljana"
  },
  "sun events": {
    "Day ends": "2024-05-08 20:20 CEST",
    "Civil twilight ends": "2024-05-08 20:55 CEST",
    "Nautical twilight ends": "2024-05-08 21:38 CEST",
    "Astronomical twilight ends": "2024-05-08 22:28 CEST",
    "Astronomical twilight starts": "2024-05-09 03:31 CEST",
    "Nautical twilight starts": "2024-05-09 04:21 CEST",
    "Civil twilight starts": "2024-05-09 05:04 CEST",
    "Day starts": "2024-05-09 05:38 CEST"
  },
  "moon events": {
    "Set": "2024-05-08 21:14 CEST",
    "Rise": "2024-05-09 06:04 CEST",
    "Moon phase": 13.1
  },
  "session events": {
    "start_at": "Nautical twilight end (Sun elevation -12 deg)",
    "start_time": "2024-05-09 21:42:06 CEST",
    "end_time": "2024-05-10 04:17:40 CEST"
  },
  "limits": {
    "mag": 15,
    "alt": 10,
    "sun_elong": 10,
    "moon_elong": 10
  },
  "comet_list": [
    {
      "comet_type": "C",
      "comet_name": "2023V4",
      "comet_fullname": "C/2023 V4 (Camarasa-Duszanowicz)",
      "best_time": "2024-05-09 21:42:06",
      "orbit_calc_source": 3,
      "magnitude": 14.3,
      "best_ra": "3:56:28.86",
      "best_dec": "34:36:32.1",
      "best_alt": 56.5,
      "sun_elongation": 20,
      "moon_elongation": 13,
      "constelation": "Perseus",
      "rise_time": "2024-05-09 21:42:06",
      "set_time": "2024-05-09 22:55:36",
      "motion": 2,
      "pa": 39,
      "trend": "bright"
    },
    {
      "comet_type": "C",
      "comet_name": "2017K2",
      "comet_fullname": "C/2017 K2 (PANSTARRS)",
      "best_time": "2024-05-09 21:42:06",
      "orbit_calc_source": 1,
      "magnitude": 14.5,
      "best_ra": "5:29:35.11",
      "best_dec": "12:49:43.7",
      "best_alt": 34.7,
      "sun_elongation": 34,
      "moon_elongation": 18,
      "constelation": "Orion",
      "rise_time": "2024-05-09 21:42:06",
      "set_time": "2024-05-09 22:18:38",
      "motion": 0.37,
      "pa": 62,
      "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.

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.1 (2024 May)

Version 1.0 (2023 November)

Initial release