Get an account

If you are a satellite operator and would like to use DISCOS object data for operational purposes, e.g. automated collision avoidance implementations, you can apply for a DISCOSweb API account. To do so, please write an email to space.debris.support_at_esa.int including your background and intended use of the DISCOSweb API.

If you do not qualify for a DISCOSweb API account, you can still register for the web interface.

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 m2
  • xSectMin is the computed minimum cross section of the object in m2
  • xSectAvg is the computed average cross section of the object in m2
  • 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_))