Getting Started

Data Cosmos provides access to the data catalogue through an API. This section provides a guide to the key API tools (incluing code snippets in both Bash and Python languages) to get you started with the DataCosmos API.

SpatioTemporal Asset Catalogs - STAC

The Data Cosmos catalogue archive maintains SpatioTemporal Asset Catalog (STAC) standards. This allows users to search all of Data Cosmos collections using a set of key query parameters. Click here for more information on our STAC configuration.

Search Collections

Requesting all available Collections is very simple, this can be useful when initially exploring via the API in order to see what kind of data is available to you.

Bash

curl --request GET "https://app.open-cosmos.com/api/data/v0/stac/collections" \
--header "Content-Type: application/json"
--header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

  Python

import requests

# Get bearer token and add to session

response = session.get("https://app.open-cosmos.com/api/data/v0/stac/collections")

print(response.json())

Search Items in a Collection

Once you have found a Collection that you are interested in, you can search through all the Items contained within the Collection.

The search endpoint allows a user to specify a Collection in the collections query parameter. Search parameters as query parameters are usually in the URL after a question mark.

This example will return a list of items from the specified Collection contained within a bounding box. If there are more results then the limit then the results will be paginated.

The different query parameter options can be found in the Search API documentation.

Bash

curl --request GET "https://app.open-cosmos.com/api/data/v0/stac/search?collections=mantis-l1d-cogs&bbox=160.6,-55.95,-170,-25.89&limit=100/2021-03-18T12:31:12Z" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

  Python

import requests

# Get bearer token and add to session

params = {
    "collections": "mantis-l1d-cogs",
    "bbox": [160.6, -55.95, -170, -25.89],
    "limit": 100,
}

response = session.get("https://app.open-cosmos.com/api/data/v0/stac/search", params=params)

print(response.json())

Advanced Search Items in a Collection

The search endpoint also allows the user to perform an advanced search. This request uses the same endpoint but, allows the user to specify search parameters in the body of a HTTP POST request rather than the URL.

The body of the request supports all the same parameters defined in the URL of the GET request, and their definitions can be found in the Search API documentation.

In addition the body also allows the user to specify an advanced query within the query field of the body. The query syntax follows the STAC Query Extension, which defines a set of comparison operators (eq, neq, lt, lte, gt, gte, startsWith, endsWith, contains, in) that can be applied to item properties.

In this example the search is looking for all Items within a given bounding box that has a cloud coverage of less than 20%.

Bash

curl --request POST "https://app.open-cosmos.com/api/data/v0/stac/search" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}" \
--data-raw '{
    "bbox": [
        -71.71875,-27.683528083787767,-71.015625,-27.05912578437406
    ],
    "query":{
        "eo:cloudcover":{
            "lte": 20
        }
    }
}'

  Python

import requests

# Get bearer token and add to session

body = {
    "bbox": [-71.71875,-27.683528083787767,-71.015625,-27.05912578437406],
    "query": {
        "eo:cloudcover": {
            "lte": 20,
        },
    },
}

response = session.post("http://app.open-cosmos.com/api/data/v0/stac/", json=body)

print(response.json())

Working with Project Items

If you have access to a specific project, you can retrieve and search for items within that project using dedicated endpoints. These endpoints behave similarly to the regular STAC collection endpoints but are specific to project data.

Get all Items from a Project

To obtain a complete list of items from a project, you can use the project-specific items endpoint. This endpoint supports pagination just like the standard collection endpoint.

Bash

curl --request GET "https://app.open-cosmos.com/api/data/v0/scenario/scenario/YOUR-PROJECT-ID/items" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

  Python

import requests

# Get bearer token and add to session

project_id = "YOUR-PROJECT-ID"
response = session.get(f"https://app.open-cosmos.com/api/data/v0/scenario/scenario/{project_id}/items")

print(response.json())

Search for Items in a Project

To find specific items within a project, such as the newest items, you can use the project search endpoint. Currently, this endpoint only accepts the POST method and allows you to filter by various parameters including dates.

Bash

curl --request POST "https://app.open-cosmos.com/api/data/v0/scenario/scenario/YOUR-PROJECT-ID/search" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}" \
--data-raw '{
    "datetime": "2023-01-01T00:00:00Z/2023-12-31T23:59:59Z"
}'

  Python

import requests

# Get bearer token and add to session

project_id = "YOUR-PROJECT-ID"
body = {
    "datetime": "2023-01-01T00:00:00Z/2023-12-31T23:59:59Z"
}

response = session.post(f"https://app.open-cosmos.com/api/data/v0/scenario/scenario/{project_id}/search", json=body)

print(response.json())

Get an Item

A single Item can be returned from the API when the ID of the Item is provided. This is useful for when you want to store a reference to the Item and query it again later.

Bash

curl --request POST "https://app.open-cosmos.com/api/data/v0/stac/collections/mantis-l1d-cogs/items/MANTIS_L1D_000000_20211001000000_20211001101010_E274" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

  Python

import requests

# Get bearer token and add to session

collection = "mantis-l1d-cogs"
item = "MANTIS_L1D_000000_20211001000000_20211001101010_E274"
response = session.get(f"https://app.open-cosmos.com/api/data/v0/stac/collections/{collection}/items/{item}")

print(response.json())

Checking Item Access Permissions

When retrieving items from either the catalog or a project (whether through search or listing), each item contains a property that indicates whether you have full access to its high-resolution assets:

• opencosmos:high_resolution_read_permission: A boolean value where true indicates that the user or API key making the request has full access to all assets, while false indicates limited access.

To check this property in an item response:

import requests

# Get bearer token and add to session

collection = "mantis-l1d-cogs"
item = "MANTIS_L1D_000000_20211001000000_20211001101010_E274"
response = session.get(f"https://app.open-cosmos.com/api/data/v0/stac/collections/{collection}/items/{item}")
item = item_response.json()

has_full_access = item.get("properties", {}).get("opencosmos:high_resolution_read_permission", False)
print(f"Has full access to high-resolution assets: {has_full_access}")

Understanding Item Pricing

Every Item returned by the catalog API includes pricing information specific to your account. The following properties are included in each Item's properties:

• opencosmos:price: The price of the data product for your account.
• opencosmos:price_currency: The currency of the quoted price (e.g. GBP, USD).

These pricing properties are available across all read operations: whether you are searching for items, listing items in a collection, or fetching a single item by ID.

Reading the Price of an Item

Python

import requests

# Get bearer token and add to session

collection = "mantis-l1d-cogs"
item_id = "MANTIS_L1D_000000_20211001000000_20211001101010_E274"
response = session.get(f"https://app.open-cosmos.com/api/data/v0/stac/collections/{collection}/items/{item_id}")
item = response.json()

price = item.get("properties", {}).get("opencosmos:price")
currency = item.get("properties", {}).get("opencosmos:price_currency")
print(f"Price: {price} {currency}")

Prices in Search Results

When searching for items, each result in the features array includes the same pricing properties. This allows you to compare prices across multiple items before making a decision.

Python

import requests

# Get bearer token and add to session

body = {
    "bbox": [-71.71875, -27.68, -71.01, -27.05],
    "collections": ["mantis-l1d-cogs"],
}

response = session.post("https://app.open-cosmos.com/api/data/v0/stac/search", json=body)
results = response.json()

for feature in results.get("features", []):
    item_id = feature["id"]
    price = feature.get("properties", {}).get("opencosmos:price")
    currency = feature.get("properties", {}).get("opencosmos:price_currency")
    print(f"Item: {item_id} - Price: {price} {currency}")

Download Assets from an Item

The assets field of the Item contains links to all the source data contained within the asset. Each Asset object contains a set of standard fields to describe the data it contains.

The most relevant field here is the href field that provides a link to the source data to be downloaded.

This example gets a specific item and downloads all the assets to local storage with the same name as the title of the asset.

Bash

curl --request POST "https://app.open-cosmos.com/api/data/v0/stac/collections/mantis-l1d-cogs/items/MANTIS_L1D_000000_20211001000000_20211001101010_E274" \
--header "Content-Type: application/json" --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

  Python

import requests

# Get bearer token and add to session

collection = "mantis-l1d-cogs"
item = "MANTIS_L1D_000000_20211001000000_20211001101010_E274"
response = session.get(f"https://app.open-cosmos.com/api/data/v0/stac/collections/{collection}/items/{item}")

item = response.json()

for _, asset in item["assets"].items():
    asset_content = session.get(asset["href"])
    with open(asset["title"], "wb") as fp:
        fp.write(asset_content.content)

Ordering and Purchasing

Users can retrieve pricing information for catalog data products and complete purchases programmatically through the Ordering API. This includes retrieving individual or batch pricing, creating orders, and completing payment via Stripe. Click here to learn about pricing retrieval and purchasing workflows.

Tasking

Users can utilise the OpenApp Satellite tasking API to query scheduled tasking requests and future tasking opportunities over a given geographic area. Click here to find out more about OpenApp Satellite tasking API.

Creating applications for DataCosmos

Developers can get in touck with Open Cosmos at datacosmos-help@open-cosmos.com if they wish to make their applications available through DataCosmos. Once that is done, the developer will have to prepare the application as described in the Dockerising an Application for DataCosmos guide.

Where to Next