DISCOSweb Operations API Howto

The DISCOSweb Operations API is currently being phased out in favor of the DISCOSweb API. It is provides more data, is publicly available, and is more reliable. If you would like to receive service outage notifications, please contact us at space.debris.support_at_esa.int.

This is the documentation of the deprecated DISCOSweb Operations API, not to be confused with the DISCOSweb API.

Object API

The API is available at /api/objects/ and can be queried with the HTTP GET method. To authenticate, use Basic HTTP authentication.

Querying single objects

Single objects can be queried by DISCOS ID, the identifier used by the DISCOS catalogue, as follows:

/api/objects/36505

To query single objects by COSPAR ID or NORAD ID (SATNO) use multiple object queries with one object only.

Querying multiple objects

To query multiple objects by DISCOS ID use:

/api/objects?discosId=36505,30440,39631

To query by COSPAR ID use:

/api/objects?cosparId=2010-013A,2013-067B,2014-016A

To query by NORAD ID (SATNO) use:

/api/objects?satno=36508,39452,39634

Single objects can also be queried with this syntax. For example:

/api/objects?satno=36508

The returned results are paginated and can be controlled with the options

size the number of returned objects per page (maximum 2000)
page the page number (starting at 0)
sort column to sort for (ascending)

For example:

/api/objects?satno=36508,39452,39451,39453,39634,27386,26463,26411,26410,26464,41335,41456,42063,40697,25544&size=10&page=1&sort=satno

Returned data

Single objects

A single object query on DISCOS ID (/api/objects/36505) returns an object in the form

{
    "discosId": 36505,
    "cosparId": "2010-013A",
    "satno": 36508,
    "name": "CRYOSAT 2",
    "objectClass": "Payload",
    "mass": 720,
    "shape": "Hex Cyl",
    "length": 2.3,
    "height": 2.3,
    "depth": 5.1,
    "xSectMax": 6.31,
    "xSectMin": 3.44,
    "xSectAvg": 5.69,
    "country": "European Space Agency",
    "launchDate": "2010-04-08",
    "reentryEpoch": null
}

where

discosId is the ID used by the DISCOS catalogue
cosparId is the international designator
satno is the NORAD ID assigned by USSTRATCOM
name is the object name
objectClass is one of the following
- Payload
- Payload Debris
- Payload Fragmentation Debris
- Payload Mission Related Object
- Rocket Body
- Rocket Debris
- Rocket Fragmentation Debris
- Rocket Mission Related Object
- Other Debris
- Other Fragmentation Debris
- Other Mission Related Object
- Unknown
mass is the object mass in kg
shape is a coarse description of the object shape
length, height, depth are the object dimensions in m
xSectMax is the computed maximum cross section of the object in m²
xSectMin is the computed minimum cross section of the object in m²
xSectAvg is the computed average cross section of the object in m²
country is the launching state
launchDate is the date the object was launched or released into space
reentryEpoch is the date the object re-entered into the earth atmosphere (null if still on orbit)

Multiple objects

A multiple object query (/api/objects?satno=36508,39634) and also queries on single COSPAR IDs and NORAD IDs (SATNOs) return paginated results in the form

{
    "content": [
        {
            "discosId": 36505,
            "cosparId": "2010-013A",
            "satno": 36508,
            "name": "CRYOSAT 2",
            "objectClass": "Payload",
            "mass": 720,
            "shape": "Hex Cyl",
            "length": 2.3,
            "height": 2.3,
            "depth": 5.1,
            "xSectMax": 6.31,
            "xSectMin": 3.44,
            "xSectAvg": 5.69,
            "country": "European Space Agency",
            "launchDate": "2010-04-08",
            "reentryEpoch": null
        },
        {
            "discosId": 39631,
            "cosparId": "2014-016A",
            "satno": 39634,
            "name": "Sentinel-1A",
            "objectClass": "Payload",
            "mass": 2157,
            "shape": "Box + 4 Pan",
            "length": 1.6,
            "height": 3.42,
            "depth": 21,
            "xSectMax": 57.92,
            "xSectMin": 2.56,
            "xSectAvg": 23.49,
            "country": "European Space Agency",
            "launchDate": "2014-04-03",
            "reentryEpoch": null
        }
    ],
    "size": 20,
    "number": 0,
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "last": true
}

where

content is a list of objects as described above
size is the number or returned objects per page
number is the page number
totalPages is the number of total pages returned by your query
totalElements is the number of total objects returned by your query
first indicated if this page is the first one
last indicates if this page is the last one

Errors

When querying a non-existent object with a single object query, a 404 with no content is returned. With a multiple object query, the non-existent object is just missing in the results. For example, the query

/api/objects?satno=99999

does return

{
    "content": [],
    "size": 20,
    "number": 0,
    "totalPages": 0,
    "totalElements": 0,
    "first": true,
    "last": true
}

If you receive a 404 with no content for a multiple object query, you most likely try to sort for an invalid column.

Usage examples

curl

curl --fail --user "username:password" https://discosweb-api.sdo.esoc.esa.int/api/objects/36505

Python3 single object

import requests

url = 'https://discosweb-api.sdo.esoc.esa.int/api/objects/36505'
r = requests.get(url, auth=('username', 'password'))
if r.status_code == 200:
    object_dict = r.json()
    print(object_dict['name'])
elif r.status_code == 404:
    print("Object not found")
else:
    r.raise_for_status()

Python3 multiple objects and pages

import requests

api_url = 'https://discosweb-api.sdo.esoc.esa.int/api/objects'
satnos = [
        8062, 9931, 10423, 10489, 10855, 10981, 11645, 12544,
        12546, 13010, 13011, 14095, 14128, 15386, 15875, 20122,
        20169, 21574, 22065, 23560, 23715, 23726, 25023, 25989,
        26410, 26411, 26463, 26464, 26958, 27386, 27540, 27816,
        27949, 28169, 28544, 28894, 28901, 28922, 32686, 32781,
        34602, 34937, 34938, 36036, 36037, 36508, 37368, 37846,
        37847, 38096, 38857, 38858, 39159, 39175, 39451, 39452,
        39453, 39479, 39634, 40103, 40697, 41043, 41335, 41388,
        41456, 42063, 42969, 43196, 43437
]

# get objects
objects = []
current_page = 0
while True:
    params = {'satno': satnos, 'page': current_page, 'sort': 'name'}
    result = requests.get(api_url, auth=('username', 'password'),
            params=params)
    if result.status_code == 200:
        result_dict = result.json()
        for object_ in result_dict['content']:
            objects.append(object_)
        if current_page < result_dict['totalPages']:
            current_page += 1
        else:
            break
    else:
        result.raise_for_status()

# print object data
print('SATNO  COSPAR ID    DISCOS ID  Name                       '
        'Object class  Mass     Shape                     Length  '
        'Height  Depth   Min Xsect  Avg Xsect  Max Xsect  '
        'Launch Date  Re-entry Date  Country')
for object_ in objects:
    if object_['reentryEpoch'] is None:
        object_['reentryEpoch'] = '-'
    print('{satno:5d}  {cosparId:11s}  {discosId:9d}  {name:25s}  '
            '{objectClass:12s}  {mass:7.1f}  {shape:24s}  '
            '{length:6.1f}  {height:6.1f}  {depth:6.1f}  '
            '{xSectMin:9.1f}  {xSectAvg:9.1f}  {xSectMax:9.1f}  '
            '{launchDate:11s}  {reentryEpoch:13s}  {country}'
            .format(**object_))