Pricing API

Before placing an order you can retrieve the price for one or more catalogue items. Prices are contract-specific — the rate per km², currency, and any applicable discounts are all determined by your contract terms. This is why a contract_id is required on every pricing request.

There are two ways to get pricing information:

Dedicated pricing endpoints (this page) — call /price or /price/batch directly with a contract_id.
Inline with STAC search — pass contract_id (or project) as a query parameter on any STAC search or item request and prices will be embedded directly in the returned items as opencosmos:price and opencosmos:price_currency properties. See A Note on Pricing for details.

Both approaches return the same contract-specific prices.

NOTE

All endpoints require a valid bearer token. See the Authentication page for details.

Get Price for a Single Item

Returns the computed price for a single catalogue item.

Endpoint

GET https://app.open-cosmos.com/api/data/v0/order/price

Query Parameters

Parameter	Type	Required	Description
`collection`	string	Yes	The STAC collection ID.
`item`	string	Yes	The STAC item ID.
`contract_id`	integer	Yes	The contract ID under which the purchase is made. See how to retrieve your contract ID.
`geometry`	string	No	JSON-encoded GeoJSON Polygon for sub-area pricing. Must be a closed polygon with at least 4 points.
`satellite`	string	No	Satellite name (e.g. `Sentinel-2A`). Avoids an extra STAC lookup when provided.
`level`	string	No	Processing level (e.g. `L2A`). Avoids an extra STAC lookup when provided.
`area`	number	No	Area in km². Avoids an extra STAC lookup when provided.
`origin`	string	No	Origin identifier passed through to the pricing engine.

NOTE

The satellite, level, and area parameters are all optional optimisations. When provided together they allow the service to skip a STAC item lookup, reducing latency. If any of the three is missing the service fetches the details from STAC automatically.

Response

{
  "data": {
    "value": "150.00",
    "discount": "0.00",
    "final": "150.00",
    "currency": "USD"
  }
}

Field	Type	Description
`value`	string	Base price before discount.
`discount`	string	Discount amount applied.
`final`	string	Final price after discount (`value` minus `discount`).
`currency`	string	Currency code (currently always `USD`).

Examples

Bash

curl --request GET \
  "https://app.open-cosmos.com/api/data/v0/order/price?collection=sentinel-2-l2a&item=S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959&contract_id=456" \
  --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}"

Python

import requests

# Get bearer token and add to session (see Authentication docs)

response = session.get(
    "https://app.open-cosmos.com/api/data/v0/order/price",
    params={
        "collection": "sentinel-2-l2a",
        "item": "S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959",
        "contract_id": 456,
    },
)

price = response.json()["data"]
print(f"Price: {price['final']} {price['currency']}")

Sub-Area Pricing

To price a custom polygon within an item's footprint, pass a JSON-encoded GeoJSON Polygon as the geometry parameter:

import json

geometry = {
    "type": "Polygon",
    "coordinates": [
        [
            [-70.5, -27.3],
            [-70.2, -27.3],
            [-70.2, -27.1],
            [-70.5, -27.1],
            [-70.5, -27.3],
        ]
    ],
}

response = session.get(
    "https://app.open-cosmos.com/api/data/v0/order/price",
    params={
        "collection": "sentinel-2-l2a",
        "item": "S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959",
        "contract_id": 456,
        "geometry": json.dumps(geometry),
    },
)

price = response.json()["data"]
print(f"Sub-area price: {price['final']} {price['currency']}")

NOTE

The geometry must be a Polygon (not MultiPolygon or any other type) with at least 4 coordinate pairs where the first and last points are identical (closed ring).

Get Prices for Multiple Items

Calculates prices for a batch of catalogue items in a single request.

Endpoint

POST https://app.open-cosmos.com/api/data/v0/order/price/batch

Query Parameters

Parameter	Type	Required	Description
`contract_id`	integer	Yes	The contract ID under which the purchases are made. See how to retrieve your contract ID.
`origin`	string	No	Origin identifier passed through to the pricing engine.

Request Body

An array of item objects. Each object identifies the STAC item and optionally carries pre-fetched STAC item details to avoid additional lookups.

Field	Type	Required	Description
`collection`	string	Yes	The STAC collection ID.
`item`	string	Yes	The STAC item ID.
`satellite`	string	No	Satellite name. Avoids an extra STAC lookup when provided with `level` and `area`.
`level`	string	No	Processing level.
`area`	number	No	Area in km².
`geometry`	object	No	GeoJSON Polygon for sub-area pricing.
`project_id`	string	No	Project ID to associate with the item.

Response

An array of price objects, one per input item, in the same order as the request.

{
  "data": [
    {
      "collection": "sentinel-2-l2a",
      "item": "S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959",
      "value": "150.00",
      "discount": "0.00",
      "final": "150.00",
      "currency": "USD"
    },
    {
      "collection": "sentinel-2-l2a",
      "item": "S2A_MSIL2A_20230620T101021_N0509_R022_T33UUP_20230620T140000",
      "value": "120.00",
      "discount": "0.00",
      "final": "120.00",
      "currency": "USD"
    }
  ]
}

Examples

Bash

curl --request POST \
  "https://app.open-cosmos.com/api/data/v0/order/price/batch?contract_id=456" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${DATACOSMOS_ACCESS_TOKEN}" \
  --data-raw '[
    {
      "collection": "sentinel-2-l2a",
      "item": "S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959"
    },
    {
      "collection": "sentinel-2-l2a",
      "item": "S2A_MSIL2A_20230620T101021_N0509_R022_T33UUP_20230620T140000"
    }
  ]'

Python

import requests

# Get bearer token and add to session (see Authentication docs)

items = [
    {
        "collection": "sentinel-2-l2a",
        "item": "S2A_MSIL2A_20230615T100559_N0509_R022_T33UUP_20230615T135959",
    },
    {
        "collection": "sentinel-2-l2a",
        "item": "S2A_MSIL2A_20230620T101021_N0509_R022_T33UUP_20230620T140000",
    },
]

response = session.post(
    "https://app.open-cosmos.com/api/data/v0/order/price/batch",
    params={"contract_id": 456},
    json=items,
)

prices = response.json()["data"]
for p in prices:
    print(f"{p['item']}: {p['final']} {p['currency']}")

Where to Next

← End-to-End Quickstart | Purchasing Catalog Images →