COBS API help

Observation List API

Version: 1.4 (2024 Jun)

Observation List API provides a method of requesting machine-readable data for a set of comet observations within the COBS database.

HTTP Request

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

Example Queries

https://cobs.si/api/obs_list.api?format=icq&des=C/2020 U4&page=1
https://cobs.si/api/obs_list.api?format=icq&from_date=2022-01-01 00:00&page=2
https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4
https://cobs.si/api/obs_list.api?format=delta&des=C/2022 E3
https://cobs.si/api/obs_list.api?format=json&from_date=2022-01-01 00:00
https://cobs.si/api/obs_list.api?format=json&from_date=2022-02-01 00:00&obs_type=C&country=GB&exclude_faint=true&exclude_not_accurate=true

Query Parameters

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

Parameter Type Default Description
format string icq format type of the output observation file (can be 'icq' or 'json' or 'delta')
id int comet object ID
des string object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or MPC packed designation (e.g., K21S040, 219P) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
uid int observer ID
user string observer ICQ/COBS designation code (e.g., ZAK, WAR01, BUCaa)
from_date date observation from date given in format YYYY-MM-DD hh:mm
to_date date observation to date given in format YYYY-MM-DD hh:mm
obs_type char observation type (e.g., V or C). If not specified all observations are received.
obs_method char observation method key (e.g., V, C, ...). Multiple keys can be used if comma separated.
camera_type string camera type key (e.g., QCM, FM1, ...). Multiple keys can be used if comma separated.
chip_type string chip type key (e.g., CAC, IC2, ...). Multiple keys can be used if comma separated.
sfw_type string photometry software type key (e.g., AIR, A4B, ...). Multiple keys can be used if comma separated.
association string association abbreviation name (e.g., OCV, BAA, SAAF)
country string country ISO 2-letter code (e.g., SI, SE, GB)
exclude_faint bolean false exclude observations marked as fainter then. '[', '>' notes appear in ICQ format column 28
exclude_not_accurate bolean false exclude observations marked as not very accurate or made under poor conditions. ':' note given in ICQ format column 33
exclude_issue bolean false exclude observations with reported potential issues
page int 1 result query page. the number of results is limited to 2500 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

Data Output ICQ format

Data Output Delta format

Data Output JSON format

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.2": "signature":{"version":"1.2","source":"COBS ... API"}

Normal Data Payload

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1
    "pages": 1
    "start": 1
    "end": 4 
    "length": 5000 
    "recordsTotal": 4
  },
  "object": [
    {
      "type": "C",
      "obs_date": "2021-09-10 03:21:36",
      "comet": {
        "type": "C",
        "name": "C/2019 L3",
        "fullname": "C/2019 L3 (ATLAS)",
        "mpc_name": "K19L030",
        "icq_name": "2019L3",
        "component": null
      },
      "observer": {
        "first_name": "Kevin",
        "last_name": "Hills",
        "icq_name": "HILaa",
        "association": "British Astronomical Association",
        "country": "United Kingdom"
      },
      "location": "",
      "extinction": null,
      "obs_method": {
        "key": "Z",
        "name": "CCD Visual equivalent"
      },
      "comet_visibility": null,
      "magnitude": "18.1",
      "conditions": null,
      "ref_catalog": {
        "key": "GG",
        "name": "GAIA DR1, DR2, EDR3 G"
      },
      "instrument_aperture": "50.0",
      "instrument_type": {
        "key": "L",
        "name": "Newtonian"
      },
      "instrument_focal_ratio": 3,
      "instrument_power": 720,
      "coma_visibility": null,
      "coma_diameter": "0.38",
      "coma_notes": null,
      "coma_dc": null,
      "tail_visibility": null,
      "tail_length": null,
      "tail_length_unit": null,
      "tail_pa": null,
      "icq_reference": "ICQ XX",
      "icq_revision": null,
      "comparison_field": "I",
      "integration_time": null,
      "photometry_aperture_shape": "C",
      "photometry_aperture_size": "0.38",
      "photometry_aperture_unit": "m",
      "camera_type": {
        "key": "QHY",
        "name": "QHY-6"
      },
      "chip_type": {
        "key": "IMX",
        "name": "Sony IMX455 back illuminated full frame sensor"
      },
      "software_type": {
        "key": "CMP",
        "name": "Comphot (by Nick James)"
      },
      "image_correction": 5,
      "observation_published": "P",
      "image_number": 5,
      "image_coadded": true,
      "magnitude_error": null,
      "comparison_star_magnitude": null,
      "pixel_size_x": "0.9",
      "pixel_size_y": "0.9",
      "pixel_size_unit": "s",
      "obs_comment": "Comphot version 1.4.1,",
      "obs_sky_quality": null,
      "obs_sky_quality_method": null,
      "reference_star_names": "",
      "date_added": "2021-09-14 14:55:52"
    },
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.4"
	"date": "2024 Jun"
  }
}
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 observation 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 General Info Section

General information about the API query.

The following fields are provided in the general 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 observations from the COBS database.

The following fields are provided in the objects section:

Field Name Description
type observation type; V - Visaul observation or C - CCD observation
obs_date observation date formated as YYYY-MM-DD hh:mm:ss
comet comet information: type, name, fullname, component, ...
observer observer information: first name, lastname, ICQ/COBS designation, ...
location observing location
extinction ICQ extinction note
obs_method observerving method information: key, name, ...
comet_visibility ICQ comet visibility note
magnitude total visual magnitude estimate given to 0.1 magnitude
conditions ':' not is used if the magnitude estimate is not very accurate, or made under poor conditions
ref_catalog reference catalog information: key, description
instrument_aperture instrument apertur in centimeters, given to 0.1 cm
instrument_type instrument type information: key, name, ...
instrument_focal_ratio focal ratio (f/-ratio) of the instrument
instrument_power the power (magnification) used in the case of visual observations or the combined duration of the CCD or photographic exposure in seconds
coma_visibility ICQ coma visibility note
coma_diameter estimate of the comet's coma diameter in arc minutes at the time of observation/td>
coma_notes special note describing the physical appearance of the central condensation/td>
coma_dc degree of condensation of the comet as estimated by the observer
tail_visibility ICQ tail visibility note
tail_length estimated tail length at the time of observation
tail_length_unit tail length measurement unit: (d = degrees, m = arcmin, s = arcsec)
tail_pa the position angle at which the center of the tail is directed (0 = north, 90 = east, 180 = south, 270 = west, etc.)
icq_reference the reference for publication
icq_revision a revised observation asterisk
comparison_field estimated distance of comparison-star field from the comet in whole degrees or 'I' if comparison stars are in the same frame as the comet or 'N' if comparison stars are in the next field
integration_time integration time of comparison-star field when the field is outside that of the comet exposure
photometry_aperture_shape the shape of the photometric aperture (S = square, C = circular, O = oval)
photometry_aperture_size numerical dimension of photometric-aperture size
photometry_aperture_unit photometric aperture size unit (d = degrees, m = arcmin, s = arcsec)
camera_type camera type information: key, name, ...
chip_type chip type information: key, name, ...
software_type photometric software information: key, name, ...
image_correction ICQ image correction note: 0-no correction, ..., 5-flat-field corrected and dark-substracted
observation_published 'P' if accurate astrometry was performed and submitted formally to the ICQ/MPC/CBAT for publication, or 'U' for either "unpublished" or "publication status unknown"
image_number number of CCD frames taken of comet on same night
image_coadded note if co-added frames were used for the photometry
magnitude_error estimated error/uncertainty in magnitude
comparison_star_magnitude magnitude of the comparison star closest in brightness to that of the comet
pixel_size_x assumed rectangular shape, with one pixel side given numerically in columns
pixel_size_y assumed rectangular shape, with the other pixel side given numerically in columns
pixel_size_unit pixel size units (d = degrees, m = arcmin, s = arcsec)
obs_comment observation comment
obs_sky_quality measured sky quality
obs_sky_quality_method sky quality measurement method (1 = NELM, 2 = SQM, 3 = SQM-L)
reference_star_names list of reference stars designation used (e.g., TYC 4456-2107-1, TYC 3882-2598-1)
date_added date observation was added to the database formated as YYYY-MM-DD hh:mm:ss
Object subsection: comet

Contain an array of information about the Comet observed. The array contains more key/value pair where the keys are the following:

key description
type comet type
name short comet name
fullname full comet name
fullname full comet name
mpc_name comet MPC packed designation
icq_name comet icq name
component comet component designation if available
Object subsection: observer

Contain an array of information about the observer. The array contains more key/value pair where the keys are the following:

key description
first_name observer first name
last_name observer last name
icq_name observer ICA/COBS designation
association observer association name
country observer country name
Object subsection: obs_method

Contain an array of information about the observing method used for the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ observing method key
name observing method name
source observing method key source (e.g., ICQ or COBS)
Object subsection: ref_catalog

Contain an array of information about the reference or source of comparison stars used for making the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ reference catalog key
name reference catalog name
status reference catalog recommendation status (e.g., recommended, not recommended, not allowed, ...)
source reference catalog key source (e.g., ICQ or COBS)
Object subsection: instrument_type

Contain an array of information about the instrument type. The array contains more key/value pair where the keys are the following:

key description
key ICQ instrument type key
name instrument type name
source instrument type key source (e.g., ICQ or COBS)
Object subsection: camera_type

Contain an array of information about the camera type. The array contains more key/value pair where the keys are the following:

key description
key ICQ camera type key
name camera type name
source camera type key source (e.g., ICQ or COBS)
Object subsection: chip_type

Contain an array of information about the camera chip type. The array contains more key/value pair where the keys are the following:

key description
key ICQ chip type key
name chip type name
source chip type key source (e.g., ICQ or COBS)
Object subsection: software_type

Contain an array of information about the photometric software. The array contains more key/value pair where the keys are the following:

key description
key ICQ photometric software key
name photometric software name
source photometric software key source (e.g., ICQ or COBS)

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.4 (2024 Jun)

Added the option to filter out observations with reported potential issues.

Version 1.3 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.2 (2023 March)

Queries are paginated with max 2500 items.
New delta format export to xlsm.

Version 1.1 (2022 September)

Added query parameters obs_method, camera_type, chip_type and sfw_type to the API. (See Query Parameters section for details).

Version 1.0 (2022 February)

Initial release

Observation List API

Version: 1.4 (2024 Jun)

Observation List API provides a method of requesting machine-readable data for a set of comet observations within the COBS database.

HTTP Request

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

Example Queries

https://cobs.si/api/obs_list.api?format=icq&des=C/2020 U4&page=1
https://cobs.si/api/obs_list.api?format=icq&from_date=2022-01-01 00:00&page=2
https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4
https://cobs.si/api/obs_list.api?format=delta&des=C/2022 E3
https://cobs.si/api/obs_list.api?format=json&from_date=2022-01-01 00:00
https://cobs.si/api/obs_list.api?format=json&from_date=2022-02-01 00:00&obs_type=C&country=GB&exclude_faint=true&exclude_not_accurate=true

Query Parameters

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

Parameter Type Default Description
format string icq format type of the output observation file (can be 'icq' or 'json' or 'delta')
id int comet object ID
des string object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or MPC packed designation (e.g., K21S040, 219P) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
uid int observer ID
user string observer ICQ/COBS designation code (e.g., ZAK, WAR01, BUCaa)
from_date date observation from date given in format YYYY-MM-DD hh:mm
to_date date observation to date given in format YYYY-MM-DD hh:mm
obs_type char observation type (e.g., V or C). If not specified all observations are received.
obs_method char observation method key (e.g., V, C, ...). Multiple keys can be used if comma separated.
camera_type string camera type key (e.g., QCM, FM1, ...). Multiple keys can be used if comma separated.
chip_type string chip type key (e.g., CAC, IC2, ...). Multiple keys can be used if comma separated.
sfw_type string photometry software type key (e.g., AIR, A4B, ...). Multiple keys can be used if comma separated.
association string association abbreviation name (e.g., OCV, BAA, SAAF)
country string country ISO 2-letter code (e.g., SI, SE, GB)
exclude_faint bolean false exclude observations marked as fainter then. '[', '>' notes appear in ICQ format column 28
exclude_not_accurate bolean false exclude observations marked as not very accurate or made under poor conditions. ':' note given in ICQ format column 33
exclude_issue bolean false exclude observations with reported potential issues
page int 1 result query page. the number of results is limited to 2500 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

Data Output ICQ format

Data Output Delta format

Data Output JSON format

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.2": "signature":{"version":"1.2","source":"COBS ... API"}

Normal Data Payload

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1
    "pages": 1
    "start": 1
    "end": 4 
    "length": 5000 
    "recordsTotal": 4
  },
  "object": [
    {
      "type": "C",
      "obs_date": "2021-09-10 03:21:36",
      "comet": {
        "type": "C",
        "name": "C/2019 L3",
        "fullname": "C/2019 L3 (ATLAS)",
        "mpc_name": "K19L030",
        "icq_name": "2019L3",
        "component": null
      },
      "observer": {
        "first_name": "Kevin",
        "last_name": "Hills",
        "icq_name": "HILaa",
        "association": "British Astronomical Association",
        "country": "United Kingdom"
      },
      "location": "",
      "extinction": null,
      "obs_method": {
        "key": "Z",
        "name": "CCD Visual equivalent"
      },
      "comet_visibility": null,
      "magnitude": "18.1",
      "conditions": null,
      "ref_catalog": {
        "key": "GG",
        "name": "GAIA DR1, DR2, EDR3 G"
      },
      "instrument_aperture": "50.0",
      "instrument_type": {
        "key": "L",
        "name": "Newtonian"
      },
      "instrument_focal_ratio": 3,
      "instrument_power": 720,
      "coma_visibility": null,
      "coma_diameter": "0.38",
      "coma_notes": null,
      "coma_dc": null,
      "tail_visibility": null,
      "tail_length": null,
      "tail_length_unit": null,
      "tail_pa": null,
      "icq_reference": "ICQ XX",
      "icq_revision": null,
      "comparison_field": "I",
      "integration_time": null,
      "photometry_aperture_shape": "C",
      "photometry_aperture_size": "0.38",
      "photometry_aperture_unit": "m",
      "camera_type": {
        "key": "QHY",
        "name": "QHY-6"
      },
      "chip_type": {
        "key": "IMX",
        "name": "Sony IMX455 back illuminated full frame sensor"
      },
      "software_type": {
        "key": "CMP",
        "name": "Comphot (by Nick James)"
      },
      "image_correction": 5,
      "observation_published": "P",
      "image_number": 5,
      "image_coadded": true,
      "magnitude_error": null,
      "comparison_star_magnitude": null,
      "pixel_size_x": "0.9",
      "pixel_size_y": "0.9",
      "pixel_size_unit": "s",
      "obs_comment": "Comphot version 1.4.1,",
      "obs_sky_quality": null,
      "obs_sky_quality_method": null,
      "reference_star_names": "",
      "date_added": "2021-09-14 14:55:52"
    },
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.4"
	"date": "2024 Jun"
  }
}
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 observation 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 General Info Section

General information about the API query.

The following fields are provided in the general 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 observations from the COBS database.

The following fields are provided in the objects section:

Field Name Description
type observation type; V - Visaul observation or C - CCD observation
obs_date observation date formated as YYYY-MM-DD hh:mm:ss
comet comet information: type, name, fullname, component, ...
observer observer information: first name, lastname, ICQ/COBS designation, ...
location observing location
extinction ICQ extinction note
obs_method observerving method information: key, name, ...
comet_visibility ICQ comet visibility note
magnitude total visual magnitude estimate given to 0.1 magnitude
conditions ':' not is used if the magnitude estimate is not very accurate, or made under poor conditions
ref_catalog reference catalog information: key, description
instrument_aperture instrument apertur in centimeters, given to 0.1 cm
instrument_type instrument type information: key, name, ...
instrument_focal_ratio focal ratio (f/-ratio) of the instrument
instrument_power the power (magnification) used in the case of visual observations or the combined duration of the CCD or photographic exposure in seconds
coma_visibility ICQ coma visibility note
coma_diameter estimate of the comet's coma diameter in arc minutes at the time of observation/td>
coma_notes special note describing the physical appearance of the central condensation/td>
coma_dc degree of condensation of the comet as estimated by the observer
tail_visibility ICQ tail visibility note
tail_length estimated tail length at the time of observation
tail_length_unit tail length measurement unit: (d = degrees, m = arcmin, s = arcsec)
tail_pa the position angle at which the center of the tail is directed (0 = north, 90 = east, 180 = south, 270 = west, etc.)
icq_reference the reference for publication
icq_revision a revised observation asterisk
comparison_field estimated distance of comparison-star field from the comet in whole degrees or 'I' if comparison stars are in the same frame as the comet or 'N' if comparison stars are in the next field
integration_time integration time of comparison-star field when the field is outside that of the comet exposure
photometry_aperture_shape the shape of the photometric aperture (S = square, C = circular, O = oval)
photometry_aperture_size numerical dimension of photometric-aperture size
photometry_aperture_unit photometric aperture size unit (d = degrees, m = arcmin, s = arcsec)
camera_type camera type information: key, name, ...
chip_type chip type information: key, name, ...
software_type photometric software information: key, name, ...
image_correction ICQ image correction note: 0-no correction, ..., 5-flat-field corrected and dark-substracted
observation_published 'P' if accurate astrometry was performed and submitted formally to the ICQ/MPC/CBAT for publication, or 'U' for either "unpublished" or "publication status unknown"
image_number number of CCD frames taken of comet on same night
image_coadded note if co-added frames were used for the photometry
magnitude_error estimated error/uncertainty in magnitude
comparison_star_magnitude magnitude of the comparison star closest in brightness to that of the comet
pixel_size_x assumed rectangular shape, with one pixel side given numerically in columns
pixel_size_y assumed rectangular shape, with the other pixel side given numerically in columns
pixel_size_unit pixel size units (d = degrees, m = arcmin, s = arcsec)
obs_comment observation comment
obs_sky_quality measured sky quality
obs_sky_quality_method sky quality measurement method (1 = NELM, 2 = SQM, 3 = SQM-L)
reference_star_names list of reference stars designation used (e.g., TYC 4456-2107-1, TYC 3882-2598-1)
date_added date observation was added to the database formated as YYYY-MM-DD hh:mm:ss
Object subsection: comet

Contain an array of information about the Comet observed. The array contains more key/value pair where the keys are the following:

key description
type comet type
name short comet name
fullname full comet name
fullname full comet name
mpc_name comet MPC packed designation
icq_name comet icq name
component comet component designation if available
Object subsection: observer

Contain an array of information about the observer. The array contains more key/value pair where the keys are the following:

key description
first_name observer first name
last_name observer last name
icq_name observer ICA/COBS designation
association observer association name
country observer country name
Object subsection: obs_method

Contain an array of information about the observing method used for the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ observing method key
name observing method name
source observing method key source (e.g., ICQ or COBS)
Object subsection: ref_catalog

Contain an array of information about the reference or source of comparison stars used for making the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ reference catalog key
name reference catalog name
status reference catalog recommendation status (e.g., recommended, not recommended, not allowed, ...)
source reference catalog key source (e.g., ICQ or COBS)
Object subsection: instrument_type

Contain an array of information about the instrument type. The array contains more key/value pair where the keys are the following:

key description
key ICQ instrument type key
name instrument type name
source instrument type key source (e.g., ICQ or COBS)
Object subsection: camera_type

Contain an array of information about the camera type. The array contains more key/value pair where the keys are the following:

key description
key ICQ camera type key
name camera type name
source camera type key source (e.g., ICQ or COBS)
Object subsection: chip_type

Contain an array of information about the camera chip type. The array contains more key/value pair where the keys are the following:

key description
key ICQ chip type key
name chip type name
source chip type key source (e.g., ICQ or COBS)
Object subsection: software_type

Contain an array of information about the photometric software. The array contains more key/value pair where the keys are the following:

key description
key ICQ photometric software key
name photometric software name
source photometric software key source (e.g., ICQ or COBS)

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.4 (2024 Jun)

Added the option to filter out observations with reported potential issues.

Version 1.3 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.2 (2023 March)

Queries are paginated with max 2500 items.
New delta format export to xlsm.

Version 1.1 (2022 September)

Added query parameters obs_method, camera_type, chip_type and sfw_type to the API. (See Query Parameters section for details).

Version 1.0 (2022 February)

Initial release

Observation List API

Version: 1.4 (2024 Jun)

Observation List API provides a method of requesting machine-readable data for a set of comet observations within the COBS database.

HTTP Request

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

Example Queries

https://cobs.si/api/obs_list.api?format=icq&des=C/2020 U4&page=1
https://cobs.si/api/obs_list.api?format=icq&from_date=2022-01-01 00:00&page=2
https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4
https://cobs.si/api/obs_list.api?format=delta&des=C/2022 E3
https://cobs.si/api/obs_list.api?format=json&from_date=2022-01-01 00:00
https://cobs.si/api/obs_list.api?format=json&from_date=2022-02-01 00:00&obs_type=C&country=GB&exclude_faint=true&exclude_not_accurate=true

Query Parameters

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

Parameter Type Default Description
format string icq format type of the output observation file (can be 'icq' or 'json' or 'delta')
id int comet object ID
des string object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or MPC packed designation (e.g., K21S040, 219P) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
uid int observer ID
user string observer ICQ/COBS designation code (e.g., ZAK, WAR01, BUCaa)
from_date date observation from date given in format YYYY-MM-DD hh:mm
to_date date observation to date given in format YYYY-MM-DD hh:mm
obs_type char observation type (e.g., V or C). If not specified all observations are received.
obs_method char observation method key (e.g., V, C, ...). Multiple keys can be used if comma separated.
camera_type string camera type key (e.g., QCM, FM1, ...). Multiple keys can be used if comma separated.
chip_type string chip type key (e.g., CAC, IC2, ...). Multiple keys can be used if comma separated.
sfw_type string photometry software type key (e.g., AIR, A4B, ...). Multiple keys can be used if comma separated.
association string association abbreviation name (e.g., OCV, BAA, SAAF)
country string country ISO 2-letter code (e.g., SI, SE, GB)
exclude_faint bolean false exclude observations marked as fainter then. '[', '>' notes appear in ICQ format column 28
exclude_not_accurate bolean false exclude observations marked as not very accurate or made under poor conditions. ':' note given in ICQ format column 33
exclude_issue bolean false exclude observations with reported potential issues
page int 1 result query page. the number of results is limited to 2500 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

Data Output ICQ format

Data Output Delta format

Data Output JSON format

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.2": "signature":{"version":"1.2","source":"COBS ... API"}

Normal Data Payload

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1
    "pages": 1
    "start": 1
    "end": 4 
    "length": 5000 
    "recordsTotal": 4
  },
  "object": [
    {
      "type": "C",
      "obs_date": "2021-09-10 03:21:36",
      "comet": {
        "type": "C",
        "name": "C/2019 L3",
        "fullname": "C/2019 L3 (ATLAS)",
        "mpc_name": "K19L030",
        "icq_name": "2019L3",
        "component": null
      },
      "observer": {
        "first_name": "Kevin",
        "last_name": "Hills",
        "icq_name": "HILaa",
        "association": "British Astronomical Association",
        "country": "United Kingdom"
      },
      "location": "",
      "extinction": null,
      "obs_method": {
        "key": "Z",
        "name": "CCD Visual equivalent"
      },
      "comet_visibility": null,
      "magnitude": "18.1",
      "conditions": null,
      "ref_catalog": {
        "key": "GG",
        "name": "GAIA DR1, DR2, EDR3 G"
      },
      "instrument_aperture": "50.0",
      "instrument_type": {
        "key": "L",
        "name": "Newtonian"
      },
      "instrument_focal_ratio": 3,
      "instrument_power": 720,
      "coma_visibility": null,
      "coma_diameter": "0.38",
      "coma_notes": null,
      "coma_dc": null,
      "tail_visibility": null,
      "tail_length": null,
      "tail_length_unit": null,
      "tail_pa": null,
      "icq_reference": "ICQ XX",
      "icq_revision": null,
      "comparison_field": "I",
      "integration_time": null,
      "photometry_aperture_shape": "C",
      "photometry_aperture_size": "0.38",
      "photometry_aperture_unit": "m",
      "camera_type": {
        "key": "QHY",
        "name": "QHY-6"
      },
      "chip_type": {
        "key": "IMX",
        "name": "Sony IMX455 back illuminated full frame sensor"
      },
      "software_type": {
        "key": "CMP",
        "name": "Comphot (by Nick James)"
      },
      "image_correction": 5,
      "observation_published": "P",
      "image_number": 5,
      "image_coadded": true,
      "magnitude_error": null,
      "comparison_star_magnitude": null,
      "pixel_size_x": "0.9",
      "pixel_size_y": "0.9",
      "pixel_size_unit": "s",
      "obs_comment": "Comphot version 1.4.1,",
      "obs_sky_quality": null,
      "obs_sky_quality_method": null,
      "reference_star_names": "",
      "date_added": "2021-09-14 14:55:52"
    },
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.4"
	"date": "2024 Jun"
  }
}
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 observation 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 General Info Section

General information about the API query.

The following fields are provided in the general 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 observations from the COBS database.

The following fields are provided in the objects section:

Field Name Description
type observation type; V - Visaul observation or C - CCD observation
obs_date observation date formated as YYYY-MM-DD hh:mm:ss
comet comet information: type, name, fullname, component, ...
observer observer information: first name, lastname, ICQ/COBS designation, ...
location observing location
extinction ICQ extinction note
obs_method observerving method information: key, name, ...
comet_visibility ICQ comet visibility note
magnitude total visual magnitude estimate given to 0.1 magnitude
conditions ':' not is used if the magnitude estimate is not very accurate, or made under poor conditions
ref_catalog reference catalog information: key, description
instrument_aperture instrument apertur in centimeters, given to 0.1 cm
instrument_type instrument type information: key, name, ...
instrument_focal_ratio focal ratio (f/-ratio) of the instrument
instrument_power the power (magnification) used in the case of visual observations or the combined duration of the CCD or photographic exposure in seconds
coma_visibility ICQ coma visibility note
coma_diameter estimate of the comet's coma diameter in arc minutes at the time of observation/td>
coma_notes special note describing the physical appearance of the central condensation/td>
coma_dc degree of condensation of the comet as estimated by the observer
tail_visibility ICQ tail visibility note
tail_length estimated tail length at the time of observation
tail_length_unit tail length measurement unit: (d = degrees, m = arcmin, s = arcsec)
tail_pa the position angle at which the center of the tail is directed (0 = north, 90 = east, 180 = south, 270 = west, etc.)
icq_reference the reference for publication
icq_revision a revised observation asterisk
comparison_field estimated distance of comparison-star field from the comet in whole degrees or 'I' if comparison stars are in the same frame as the comet or 'N' if comparison stars are in the next field
integration_time integration time of comparison-star field when the field is outside that of the comet exposure
photometry_aperture_shape the shape of the photometric aperture (S = square, C = circular, O = oval)
photometry_aperture_size numerical dimension of photometric-aperture size
photometry_aperture_unit photometric aperture size unit (d = degrees, m = arcmin, s = arcsec)
camera_type camera type information: key, name, ...
chip_type chip type information: key, name, ...
software_type photometric software information: key, name, ...
image_correction ICQ image correction note: 0-no correction, ..., 5-flat-field corrected and dark-substracted
observation_published 'P' if accurate astrometry was performed and submitted formally to the ICQ/MPC/CBAT for publication, or 'U' for either "unpublished" or "publication status unknown"
image_number number of CCD frames taken of comet on same night
image_coadded note if co-added frames were used for the photometry
magnitude_error estimated error/uncertainty in magnitude
comparison_star_magnitude magnitude of the comparison star closest in brightness to that of the comet
pixel_size_x assumed rectangular shape, with one pixel side given numerically in columns
pixel_size_y assumed rectangular shape, with the other pixel side given numerically in columns
pixel_size_unit pixel size units (d = degrees, m = arcmin, s = arcsec)
obs_comment observation comment
obs_sky_quality measured sky quality
obs_sky_quality_method sky quality measurement method (1 = NELM, 2 = SQM, 3 = SQM-L)
reference_star_names list of reference stars designation used (e.g., TYC 4456-2107-1, TYC 3882-2598-1)
date_added date observation was added to the database formated as YYYY-MM-DD hh:mm:ss
Object subsection: comet

Contain an array of information about the Comet observed. The array contains more key/value pair where the keys are the following:

key description
type comet type
name short comet name
fullname full comet name
fullname full comet name
mpc_name comet MPC packed designation
icq_name comet icq name
component comet component designation if available
Object subsection: observer

Contain an array of information about the observer. The array contains more key/value pair where the keys are the following:

key description
first_name observer first name
last_name observer last name
icq_name observer ICA/COBS designation
association observer association name
country observer country name
Object subsection: obs_method

Contain an array of information about the observing method used for the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ observing method key
name observing method name
source observing method key source (e.g., ICQ or COBS)
Object subsection: ref_catalog

Contain an array of information about the reference or source of comparison stars used for making the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ reference catalog key
name reference catalog name
status reference catalog recommendation status (e.g., recommended, not recommended, not allowed, ...)
source reference catalog key source (e.g., ICQ or COBS)
Object subsection: instrument_type

Contain an array of information about the instrument type. The array contains more key/value pair where the keys are the following:

key description
key ICQ instrument type key
name instrument type name
source instrument type key source (e.g., ICQ or COBS)
Object subsection: camera_type

Contain an array of information about the camera type. The array contains more key/value pair where the keys are the following:

key description
key ICQ camera type key
name camera type name
source camera type key source (e.g., ICQ or COBS)
Object subsection: chip_type

Contain an array of information about the camera chip type. The array contains more key/value pair where the keys are the following:

key description
key ICQ chip type key
name chip type name
source chip type key source (e.g., ICQ or COBS)
Object subsection: software_type

Contain an array of information about the photometric software. The array contains more key/value pair where the keys are the following:

key description
key ICQ photometric software key
name photometric software name
source photometric software key source (e.g., ICQ or COBS)

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.4 (2024 Jun)

Added the option to filter out observations with reported potential issues.

Version 1.3 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.2 (2023 March)

Queries are paginated with max 2500 items.
New delta format export to xlsm.

Version 1.1 (2022 September)

Added query parameters obs_method, camera_type, chip_type and sfw_type to the API. (See Query Parameters section for details).

Version 1.0 (2022 February)

Initial release

Observation List API

Version: 1.4 (2024 Jun)

Observation List API provides a method of requesting machine-readable data for a set of comet observations within the COBS database.

HTTP Request

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

Example Queries

https://cobs.si/api/obs_list.api?format=icq&des=C/2020 U4&page=1
https://cobs.si/api/obs_list.api?format=icq&from_date=2022-01-01 00:00&page=2
https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4
https://cobs.si/api/obs_list.api?format=delta&des=C/2022 E3
https://cobs.si/api/obs_list.api?format=json&from_date=2022-01-01 00:00
https://cobs.si/api/obs_list.api?format=json&from_date=2022-02-01 00:00&obs_type=C&country=GB&exclude_faint=true&exclude_not_accurate=true

Query Parameters

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

Parameter Type Default Description
format string icq format type of the output observation file (can be 'icq' or 'json' or 'delta')
id int comet object ID
des string object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or MPC packed designation (e.g., K21S040, 219P) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
uid int observer ID
user string observer ICQ/COBS designation code (e.g., ZAK, WAR01, BUCaa)
from_date date observation from date given in format YYYY-MM-DD hh:mm
to_date date observation to date given in format YYYY-MM-DD hh:mm
obs_type char observation type (e.g., V or C). If not specified all observations are received.
obs_method char observation method key (e.g., V, C, ...). Multiple keys can be used if comma separated.
camera_type string camera type key (e.g., QCM, FM1, ...). Multiple keys can be used if comma separated.
chip_type string chip type key (e.g., CAC, IC2, ...). Multiple keys can be used if comma separated.
sfw_type string photometry software type key (e.g., AIR, A4B, ...). Multiple keys can be used if comma separated.
association string association abbreviation name (e.g., OCV, BAA, SAAF)
country string country ISO 2-letter code (e.g., SI, SE, GB)
exclude_faint bolean false exclude observations marked as fainter then. '[', '>' notes appear in ICQ format column 28
exclude_not_accurate bolean false exclude observations marked as not very accurate or made under poor conditions. ':' note given in ICQ format column 33
exclude_issue bolean false exclude observations with reported potential issues
page int 1 result query page. the number of results is limited to 2500 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

Data Output ICQ format

Data Output Delta format

Data Output JSON format

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.2": "signature":{"version":"1.2","source":"COBS ... API"}

Normal Data Payload

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1
    "pages": 1
    "start": 1
    "end": 4 
    "length": 5000 
    "recordsTotal": 4
  },
  "object": [
    {
      "type": "C",
      "obs_date": "2021-09-10 03:21:36",
      "comet": {
        "type": "C",
        "name": "C/2019 L3",
        "fullname": "C/2019 L3 (ATLAS)",
        "mpc_name": "K19L030",
        "icq_name": "2019L3",
        "component": null
      },
      "observer": {
        "first_name": "Kevin",
        "last_name": "Hills",
        "icq_name": "HILaa",
        "association": "British Astronomical Association",
        "country": "United Kingdom"
      },
      "location": "",
      "extinction": null,
      "obs_method": {
        "key": "Z",
        "name": "CCD Visual equivalent"
      },
      "comet_visibility": null,
      "magnitude": "18.1",
      "conditions": null,
      "ref_catalog": {
        "key": "GG",
        "name": "GAIA DR1, DR2, EDR3 G"
      },
      "instrument_aperture": "50.0",
      "instrument_type": {
        "key": "L",
        "name": "Newtonian"
      },
      "instrument_focal_ratio": 3,
      "instrument_power": 720,
      "coma_visibility": null,
      "coma_diameter": "0.38",
      "coma_notes": null,
      "coma_dc": null,
      "tail_visibility": null,
      "tail_length": null,
      "tail_length_unit": null,
      "tail_pa": null,
      "icq_reference": "ICQ XX",
      "icq_revision": null,
      "comparison_field": "I",
      "integration_time": null,
      "photometry_aperture_shape": "C",
      "photometry_aperture_size": "0.38",
      "photometry_aperture_unit": "m",
      "camera_type": {
        "key": "QHY",
        "name": "QHY-6"
      },
      "chip_type": {
        "key": "IMX",
        "name": "Sony IMX455 back illuminated full frame sensor"
      },
      "software_type": {
        "key": "CMP",
        "name": "Comphot (by Nick James)"
      },
      "image_correction": 5,
      "observation_published": "P",
      "image_number": 5,
      "image_coadded": true,
      "magnitude_error": null,
      "comparison_star_magnitude": null,
      "pixel_size_x": "0.9",
      "pixel_size_y": "0.9",
      "pixel_size_unit": "s",
      "obs_comment": "Comphot version 1.4.1,",
      "obs_sky_quality": null,
      "obs_sky_quality_method": null,
      "reference_star_names": "",
      "date_added": "2021-09-14 14:55:52"
    },
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.4"
	"date": "2024 Jun"
  }
}
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 observation 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 General Info Section

General information about the API query.

The following fields are provided in the general 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 observations from the COBS database.

The following fields are provided in the objects section:

Field Name Description
type observation type; V - Visaul observation or C - CCD observation
obs_date observation date formated as YYYY-MM-DD hh:mm:ss
comet comet information: type, name, fullname, component, ...
observer observer information: first name, lastname, ICQ/COBS designation, ...
location observing location
extinction ICQ extinction note
obs_method observerving method information: key, name, ...
comet_visibility ICQ comet visibility note
magnitude total visual magnitude estimate given to 0.1 magnitude
conditions ':' not is used if the magnitude estimate is not very accurate, or made under poor conditions
ref_catalog reference catalog information: key, description
instrument_aperture instrument apertur in centimeters, given to 0.1 cm
instrument_type instrument type information: key, name, ...
instrument_focal_ratio focal ratio (f/-ratio) of the instrument
instrument_power the power (magnification) used in the case of visual observations or the combined duration of the CCD or photographic exposure in seconds
coma_visibility ICQ coma visibility note
coma_diameter estimate of the comet's coma diameter in arc minutes at the time of observation/td>
coma_notes special note describing the physical appearance of the central condensation/td>
coma_dc degree of condensation of the comet as estimated by the observer
tail_visibility ICQ tail visibility note
tail_length estimated tail length at the time of observation
tail_length_unit tail length measurement unit: (d = degrees, m = arcmin, s = arcsec)
tail_pa the position angle at which the center of the tail is directed (0 = north, 90 = east, 180 = south, 270 = west, etc.)
icq_reference the reference for publication
icq_revision a revised observation asterisk
comparison_field estimated distance of comparison-star field from the comet in whole degrees or 'I' if comparison stars are in the same frame as the comet or 'N' if comparison stars are in the next field
integration_time integration time of comparison-star field when the field is outside that of the comet exposure
photometry_aperture_shape the shape of the photometric aperture (S = square, C = circular, O = oval)
photometry_aperture_size numerical dimension of photometric-aperture size
photometry_aperture_unit photometric aperture size unit (d = degrees, m = arcmin, s = arcsec)
camera_type camera type information: key, name, ...
chip_type chip type information: key, name, ...
software_type photometric software information: key, name, ...
image_correction ICQ image correction note: 0-no correction, ..., 5-flat-field corrected and dark-substracted
observation_published 'P' if accurate astrometry was performed and submitted formally to the ICQ/MPC/CBAT for publication, or 'U' for either "unpublished" or "publication status unknown"
image_number number of CCD frames taken of comet on same night
image_coadded note if co-added frames were used for the photometry
magnitude_error estimated error/uncertainty in magnitude
comparison_star_magnitude magnitude of the comparison star closest in brightness to that of the comet
pixel_size_x assumed rectangular shape, with one pixel side given numerically in columns
pixel_size_y assumed rectangular shape, with the other pixel side given numerically in columns
pixel_size_unit pixel size units (d = degrees, m = arcmin, s = arcsec)
obs_comment observation comment
obs_sky_quality measured sky quality
obs_sky_quality_method sky quality measurement method (1 = NELM, 2 = SQM, 3 = SQM-L)
reference_star_names list of reference stars designation used (e.g., TYC 4456-2107-1, TYC 3882-2598-1)
date_added date observation was added to the database formated as YYYY-MM-DD hh:mm:ss
Object subsection: comet

Contain an array of information about the Comet observed. The array contains more key/value pair where the keys are the following:

key description
type comet type
name short comet name
fullname full comet name
fullname full comet name
mpc_name comet MPC packed designation
icq_name comet icq name
component comet component designation if available
Object subsection: observer

Contain an array of information about the observer. The array contains more key/value pair where the keys are the following:

key description
first_name observer first name
last_name observer last name
icq_name observer ICA/COBS designation
association observer association name
country observer country name
Object subsection: obs_method

Contain an array of information about the observing method used for the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ observing method key
name observing method name
source observing method key source (e.g., ICQ or COBS)
Object subsection: ref_catalog

Contain an array of information about the reference or source of comparison stars used for making the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ reference catalog key
name reference catalog name
status reference catalog recommendation status (e.g., recommended, not recommended, not allowed, ...)
source reference catalog key source (e.g., ICQ or COBS)
Object subsection: instrument_type

Contain an array of information about the instrument type. The array contains more key/value pair where the keys are the following:

key description
key ICQ instrument type key
name instrument type name
source instrument type key source (e.g., ICQ or COBS)
Object subsection: camera_type

Contain an array of information about the camera type. The array contains more key/value pair where the keys are the following:

key description
key ICQ camera type key
name camera type name
source camera type key source (e.g., ICQ or COBS)
Object subsection: chip_type

Contain an array of information about the camera chip type. The array contains more key/value pair where the keys are the following:

key description
key ICQ chip type key
name chip type name
source chip type key source (e.g., ICQ or COBS)
Object subsection: software_type

Contain an array of information about the photometric software. The array contains more key/value pair where the keys are the following:

key description
key ICQ photometric software key
name photometric software name
source photometric software key source (e.g., ICQ or COBS)

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.4 (2024 Jun)

Added the option to filter out observations with reported potential issues.

Version 1.3 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.2 (2023 March)

Queries are paginated with max 2500 items.
New delta format export to xlsm.

Version 1.1 (2022 September)

Added query parameters obs_method, camera_type, chip_type and sfw_type to the API. (See Query Parameters section for details).

Version 1.0 (2022 February)

Initial release

Observation List API

Version: 1.4 (2024 Jun)

Observation List API provides a method of requesting machine-readable data for a set of comet observations within the COBS database.

HTTP Request

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

Example Queries

https://cobs.si/api/obs_list.api?format=icq&des=C/2020 U4&page=1
https://cobs.si/api/obs_list.api?format=icq&from_date=2022-01-01 00:00&page=2
https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4
https://cobs.si/api/obs_list.api?format=delta&des=C/2022 E3
https://cobs.si/api/obs_list.api?format=json&from_date=2022-01-01 00:00
https://cobs.si/api/obs_list.api?format=json&from_date=2022-02-01 00:00&obs_type=C&country=GB&exclude_faint=true&exclude_not_accurate=true

Query Parameters

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

Parameter Type Default Description
format string icq format type of the output observation file (can be 'icq' or 'json' or 'delta')
id int comet object ID
des string object designation (e.g., 141P, 73P-C, C/1995 O1); comet designations can be entered as a short MPC comet name (e.g., 141P, 73P/C, C/1995 O1) or MPC packed designation (e.g., K21S040, 219P) or as ICQ comet name (e.g., 0141, 0073a, 1995O1)
uid int observer ID
user string observer ICQ/COBS designation code (e.g., ZAK, WAR01, BUCaa)
from_date date observation from date given in format YYYY-MM-DD hh:mm
to_date date observation to date given in format YYYY-MM-DD hh:mm
obs_type char observation type (e.g., V or C). If not specified all observations are received.
obs_method char observation method key (e.g., V, C, ...). Multiple keys can be used if comma separated.
camera_type string camera type key (e.g., QCM, FM1, ...). Multiple keys can be used if comma separated.
chip_type string chip type key (e.g., CAC, IC2, ...). Multiple keys can be used if comma separated.
sfw_type string photometry software type key (e.g., AIR, A4B, ...). Multiple keys can be used if comma separated.
association string association abbreviation name (e.g., OCV, BAA, SAAF)
country string country ISO 2-letter code (e.g., SI, SE, GB)
exclude_faint bolean false exclude observations marked as fainter then. '[', '>' notes appear in ICQ format column 28
exclude_not_accurate bolean false exclude observations marked as not very accurate or made under poor conditions. ':' note given in ICQ format column 33
exclude_issue bolean false exclude observations with reported potential issues
page int 1 result query page. the number of results is limited to 2500 items; therefore the query is paginated and different slices can be accessed by specifying the query page.

Data Output ICQ format

Data Output Delta format

Data Output JSON format

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.2": "signature":{"version":"1.2","source":"COBS ... API"}

Normal Data Payload

This output is the result of specifying a unique object.
The following example query https://cobs.si/api/obs_list.api?format=json&des=C/2020 U4&page=1 returns the following payload containing data sections objects.

{
  "info": {
    "page": 1
    "pages": 1
    "start": 1
    "end": 4 
    "length": 5000 
    "recordsTotal": 4
  },
  "object": [
    {
      "type": "C",
      "obs_date": "2021-09-10 03:21:36",
      "comet": {
        "type": "C",
        "name": "C/2019 L3",
        "fullname": "C/2019 L3 (ATLAS)",
        "mpc_name": "K19L030",
        "icq_name": "2019L3",
        "component": null
      },
      "observer": {
        "first_name": "Kevin",
        "last_name": "Hills",
        "icq_name": "HILaa",
        "association": "British Astronomical Association",
        "country": "United Kingdom"
      },
      "location": "",
      "extinction": null,
      "obs_method": {
        "key": "Z",
        "name": "CCD Visual equivalent"
      },
      "comet_visibility": null,
      "magnitude": "18.1",
      "conditions": null,
      "ref_catalog": {
        "key": "GG",
        "name": "GAIA DR1, DR2, EDR3 G"
      },
      "instrument_aperture": "50.0",
      "instrument_type": {
        "key": "L",
        "name": "Newtonian"
      },
      "instrument_focal_ratio": 3,
      "instrument_power": 720,
      "coma_visibility": null,
      "coma_diameter": "0.38",
      "coma_notes": null,
      "coma_dc": null,
      "tail_visibility": null,
      "tail_length": null,
      "tail_length_unit": null,
      "tail_pa": null,
      "icq_reference": "ICQ XX",
      "icq_revision": null,
      "comparison_field": "I",
      "integration_time": null,
      "photometry_aperture_shape": "C",
      "photometry_aperture_size": "0.38",
      "photometry_aperture_unit": "m",
      "camera_type": {
        "key": "QHY",
        "name": "QHY-6"
      },
      "chip_type": {
        "key": "IMX",
        "name": "Sony IMX455 back illuminated full frame sensor"
      },
      "software_type": {
        "key": "CMP",
        "name": "Comphot (by Nick James)"
      },
      "image_correction": 5,
      "observation_published": "P",
      "image_number": 5,
      "image_coadded": true,
      "magnitude_error": null,
      "comparison_star_magnitude": null,
      "pixel_size_x": "0.9",
      "pixel_size_y": "0.9",
      "pixel_size_unit": "s",
      "obs_comment": "Comphot version 1.4.1,",
      "obs_sky_quality": null,
      "obs_sky_quality_method": null,
      "reference_star_names": "",
      "date_added": "2021-09-14 14:55:52"
    },
  ],
  "signature": {
    "source": "COBS Query API",
    "version": "1.4"
	"date": "2024 Jun"
  }
}
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 observation 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 General Info Section

General information about the API query.

The following fields are provided in the general 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 observations from the COBS database.

The following fields are provided in the objects section:

Field Name Description
type observation type; V - Visaul observation or C - CCD observation
obs_date observation date formated as YYYY-MM-DD hh:mm:ss
comet comet information: type, name, fullname, component, ...
observer observer information: first name, lastname, ICQ/COBS designation, ...
location observing location
extinction ICQ extinction note
obs_method observerving method information: key, name, ...
comet_visibility ICQ comet visibility note
magnitude total visual magnitude estimate given to 0.1 magnitude
conditions ':' not is used if the magnitude estimate is not very accurate, or made under poor conditions
ref_catalog reference catalog information: key, description
instrument_aperture instrument apertur in centimeters, given to 0.1 cm
instrument_type instrument type information: key, name, ...
instrument_focal_ratio focal ratio (f/-ratio) of the instrument
instrument_power the power (magnification) used in the case of visual observations or the combined duration of the CCD or photographic exposure in seconds
coma_visibility ICQ coma visibility note
coma_diameter estimate of the comet's coma diameter in arc minutes at the time of observation/td>
coma_notes special note describing the physical appearance of the central condensation/td>
coma_dc degree of condensation of the comet as estimated by the observer
tail_visibility ICQ tail visibility note
tail_length estimated tail length at the time of observation
tail_length_unit tail length measurement unit: (d = degrees, m = arcmin, s = arcsec)
tail_pa the position angle at which the center of the tail is directed (0 = north, 90 = east, 180 = south, 270 = west, etc.)
icq_reference the reference for publication
icq_revision a revised observation asterisk
comparison_field estimated distance of comparison-star field from the comet in whole degrees or 'I' if comparison stars are in the same frame as the comet or 'N' if comparison stars are in the next field
integration_time integration time of comparison-star field when the field is outside that of the comet exposure
photometry_aperture_shape the shape of the photometric aperture (S = square, C = circular, O = oval)
photometry_aperture_size numerical dimension of photometric-aperture size
photometry_aperture_unit photometric aperture size unit (d = degrees, m = arcmin, s = arcsec)
camera_type camera type information: key, name, ...
chip_type chip type information: key, name, ...
software_type photometric software information: key, name, ...
image_correction ICQ image correction note: 0-no correction, ..., 5-flat-field corrected and dark-substracted
observation_published 'P' if accurate astrometry was performed and submitted formally to the ICQ/MPC/CBAT for publication, or 'U' for either "unpublished" or "publication status unknown"
image_number number of CCD frames taken of comet on same night
image_coadded note if co-added frames were used for the photometry
magnitude_error estimated error/uncertainty in magnitude
comparison_star_magnitude magnitude of the comparison star closest in brightness to that of the comet
pixel_size_x assumed rectangular shape, with one pixel side given numerically in columns
pixel_size_y assumed rectangular shape, with the other pixel side given numerically in columns
pixel_size_unit pixel size units (d = degrees, m = arcmin, s = arcsec)
obs_comment observation comment
obs_sky_quality measured sky quality
obs_sky_quality_method sky quality measurement method (1 = NELM, 2 = SQM, 3 = SQM-L)
reference_star_names list of reference stars designation used (e.g., TYC 4456-2107-1, TYC 3882-2598-1)
date_added date observation was added to the database formated as YYYY-MM-DD hh:mm:ss
Object subsection: comet

Contain an array of information about the Comet observed. The array contains more key/value pair where the keys are the following:

key description
type comet type
name short comet name
fullname full comet name
fullname full comet name
mpc_name comet MPC packed designation
icq_name comet icq name
component comet component designation if available
Object subsection: observer

Contain an array of information about the observer. The array contains more key/value pair where the keys are the following:

key description
first_name observer first name
last_name observer last name
icq_name observer ICA/COBS designation
association observer association name
country observer country name
Object subsection: obs_method

Contain an array of information about the observing method used for the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ observing method key
name observing method name
source observing method key source (e.g., ICQ or COBS)
Object subsection: ref_catalog

Contain an array of information about the reference or source of comparison stars used for making the magnitude estimate. The array contains more key/value pair where the keys are the following:

key description
key ICQ reference catalog key
name reference catalog name
status reference catalog recommendation status (e.g., recommended, not recommended, not allowed, ...)
source reference catalog key source (e.g., ICQ or COBS)
Object subsection: instrument_type

Contain an array of information about the instrument type. The array contains more key/value pair where the keys are the following:

key description
key ICQ instrument type key
name instrument type name
source instrument type key source (e.g., ICQ or COBS)
Object subsection: camera_type

Contain an array of information about the camera type. The array contains more key/value pair where the keys are the following:

key description
key ICQ camera type key
name camera type name
source camera type key source (e.g., ICQ or COBS)
Object subsection: chip_type

Contain an array of information about the camera chip type. The array contains more key/value pair where the keys are the following:

key description
key ICQ chip type key
name chip type name
source chip type key source (e.g., ICQ or COBS)
Object subsection: software_type

Contain an array of information about the photometric software. The array contains more key/value pair where the keys are the following:

key description
key ICQ photometric software key
name photometric software name
source photometric software key source (e.g., ICQ or COBS)

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.4 (2024 Jun)

Added the option to filter out observations with reported potential issues.

Version 1.3 (2024 May)

Added the option to filter the observations according to comet MPC packed designation.

Version 1.2 (2023 March)

Queries are paginated with max 2500 items.
New delta format export to xlsm.

Version 1.1 (2022 September)

Added query parameters obs_method, camera_type, chip_type and sfw_type to the API. (See Query Parameters section for details).

Version 1.0 (2022 February)

Initial release