Skip to content

Publish Generic badge Generic badge

Warning

This endpoint is only available to registered supplier users and organisations.

Description

The Publish endpoint is the main method of adding new data to Data Sphere. It is intended for near real-time data. So, as you generate new Earth Observation data, you can publish it directly to Data Sphere using WebSockets.

WebSockets is a versatile protocol with implementations available in many languages. The Publish endpoint is intended as a uni-directional endpoint. The only message you will receive from us is a heartbeat every 25 seconds to keep the connection alive.

You must use an API Token to Authenticate the connection. Not all implementations of websockets allow for additional Headers, so we have two options: Header and Message Authentication. The Header method is preferred as it is more secure. For Message authentication, your first message must be the Authorization Token, otherwise the connection will be rejected.

Here are some WebSocket implementations we recommend:

Language Package
Python websockets
Node.js ws, Socket.IO
Javascript Socket.IO

URL

wss://ws.datasphere.astrodynamic.space/publish/v1/
Authentication Required

Generate API Token.

Header Value
Authorization Token {Your Token} 
{
    "Authorization": "Token {token}"
}

Please ensure the trailing " / " is included in the uri. Exclusion will result in a 403 error.

Send

Message

Value

Serialised Object

Parameter Type Required Default Description
active_parent string Required STAC Collection/Catalog ID that sub-collections and items are being added to.
data object Required STAC Catalog or Collection or Item, being published to Data Sphere.
provider string Optional Organisation supplying the data. This can be your organisation or an organisation you may be publishing data on behalf of. If not included, the organisation linked with the Authorization Token is used.
subscribable boolean Optional True Specifies whether catalog/collection/item is recent data, therefore able to be used in the Data Sphere real time data. If the STAC catalogs/collections/items is archival data, you must include this field and set it as False. 
{
    "active_parent": "cool-sat-collection",
    "provider": "Astro Dynamic",
    "subscribable": True,
    "data":{

    }
}

{
    "active_parent": "cool-sat-collection",
    "data":{
        <STAC Item>
    }
}

Receive

Heartbeat

Parameter Type Value Description
hearbeat string heartbeat Every 25 seconds, we send a heartbeat to you to keep the websocket connection alive.

Usage

Basic Example

import websockets
import asyncio
import orjson

uri = "wss://ws.datasphere.astrodynamic.space/publish/v1/"
api_token = <api_token>

async def main():

    async with websockets.connect(uri=uri, extra_headers={"Authorization":f"Token {api_token}"}) as websocket:

        for stac_item in stac_items:
            message = orjson.dumps(
                {
                    "active_parent": "cool-sat",
                    "provider": "astro_dynamic",
                    "subscribable": false,
                    "data": <stac_item : dict>
                }
            )

        await websocket.send(message)

if __name__ == "__main__":
    asyncio.run(main)

Message Order

When publishing data via Publish, order matters.

STAC Catalog -> STAC Collection -> STAC Item

  1. Catalogs sent first.
  2. Collections belonging to previously sent Catalogs, next.
  3. Items belonging to previously sent Collections, last.

If you are adding data to existing Catalogs or Collections, you do not need to resend the Catalog/Collection again. This ordering is only needed for new data.

This is a best practice instead of a requirement (we have fallbacks in place) but to maintain the best outcomes, we heavily suggest using this ordering.

You can find an example here.

Active Parent

An active parent is the most stable branch the catalog where STAC Collections and STAC Items are being added to. This can be the root of the catalog or another collection. For example:

We have a catalog called Astro Dynamic with the collections for our platforms cool-sat and not-so-cool-sat. cool-sat has collections for the years 2023 and 2024, and within those contains collections for each month, containing the STAC Items. The path for adding our latest Items, starting from the catalog, is

Astro Dynamic -> cool-sat -> 2024 -> December -> STAC Item

This is very human readable and a logical way of structuring a STAC Catalog, but when we need to add a 2025 collection, our system will have difficulty tracking that change and sending the necessary items to your customers. Instead, we track from the most stable path. In this example, that would be cool-sat as we add all our sub collections and items to it. So the message we would send via the publish API with our STAC Item would be:

    {
        "active_parent": "cool-sat",
        "data": "{STAC Item}"
    }

Likewise, if we had instrument collections for cool-sat so that path became

Astro Dynamic -> cool sat -> cool-instrument-A -> 2024 -> December -> STAC Item

Our active parent would be cool-instrument-A as all the sub-collections and items will only be related to cool-instrument-A.

In cases where there is no active parent or the data being added via publish is archive data, you can set the active parent to None or the root catalog. However, we would not recommend using the root catalog unless it is the active parent.