Version: 1.0 (2023 November 03)
Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.
GET https://cobs.si/api/planner.api
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?
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. |
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"}
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"
}
}
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” |
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 ...
},
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. |
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 |
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 |
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 |
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 |
Initial release
Version: 1.0 (2023 November 03)
Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.
GET https://cobs.si/api/planner.api
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?
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. |
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"}
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"
}
}
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” |
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 ...
},
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. |
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 |
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 |
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 |
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 |
Initial release
Version: 1.0 (2023 November 03)
Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.
GET https://cobs.si/api/planner.api
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?
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. |
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"}
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"
}
}
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” |
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 ...
},
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. |
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 |
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 |
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 |
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 |
Initial release
Version: 1.0 (2023 November 03)
Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.
GET https://cobs.si/api/planner.api
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?
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. |
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"}
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"
}
}
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” |
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 ...
},
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. |
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 |
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 |
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 |
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 |
Initial release
Version: 1.0 (2023 November 03)
Comet Planner API provides a method of requesting a list of observable comets in a machine-readable data.
GET https://cobs.si/api/planner.api
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?
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. |
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"}
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"
}
}
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” |
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 ...
},
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. |
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 |
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 |
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 |
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 |
Initial release