Getting Started with the Feasibility and Tasking API

This guide will walk you through the full process of acquiring satellite imagery and derived products on demand via API endpoints.

About the Feasibility and Tasking API

Ursa Space's Feasibility and Tasking API offers direct access to a powerful network of commercial satellite image providers. Through a single interface, decision makers can capture high resolution imagery and tap into Ursa Space's suite of advanced image processing capabilities.

Process Overview

Before diving into the details of each endpoint, it is important to first provide an overview of the end to end process for acquiring geospatial products via the Feasibility and Tasking API. Below is a diagram that highlights the three main steps involved: Feasibility Study, Satellite Tasking, and Product Delivery.

Step 1. Conduct a Feasibility Study

A feasibility study provides decision makers with upcoming opportunities to capture images over their area of interest. Additional constraints may also be specified such as satellite provider, azimuth angle, incidence angle, squint angle, and datetime. Behind the scenes, the Feasibility and Tasking API identifies optimal tasking opportunities by applying specialized algorithms that analyze a range of public and commercial data sources.

Step 2. Request a Satellite Tasking

Decision-makers can leverage feasibility insights to precisely craft tasking requests with a strong liklihood of being scheduled. Additional requirements, derived image products, and analytics may also be specified. Upon each request, the Feasibility and Tasking API tasks the associated satellite accordingly.

Step 3. Products Delivered to a Cloud Storage Bucket

Upon a successful image capture, Ursa Space rapidly processes the image and delivers a product bundle to your desired cloud storage location. Customized notifications and alerts can also be provided if desired.

Accessing the API

The Feasibility and Tasking API can be found at the following URL, and it consists of six endpoints in total.

https://platform.ursaspace.com/api/v1/tfs

• Submit a New Feasibility Request (POST /feasibility)
• Get the Status of a Feasibility Request (GET /feasibility/{id})
• Submit a New Tasking Request (POST /tasking)
• Get the Status of a Tasking Request (GET /tasking/{id})
• List All Tasking Requests (GET /tasking)
• Cancel a Tasking Request (POST /tasking/{id}/cancel)

Authorization: Bearer <token>

Submit a New Feasibility Request 

POST /feasibility

Request Body

Response Body

An instance of Feasibility Request Status as defined in the Schema Reference section.

Get the Status of a Feasibility Request

GET /feasibility/{id}

Response Body

An instance of Feasibility Request Status as defined in the Schema Reference section.

Submit a New Tasking Request

POST /tasking

Request Body

Response Body

An instance of Tasking Request Status as defined in the Schema Reference section.

Get the Status of a Tasking Request

GET /tasking/{id}

Response Body

An instance of Tasking Request Status as defined in the Schema Reference section.

List All Tasking Requests

GET /tasking

Query Parameters

Response Body

Cancel a Tasking Request

POST /tasking/{id}/cancel

Response Body

An instance of Tasking Request Status as defined in the Schema Reference section

Schema Reference

Feasibility Request Status

Tasking Request Status

Tasking Opportunity

Mode

Postman Collection

If you are familiar with Postman, a preconfigured collection for the Feasibility and Tasking API is available to download: 

• Feasibility and Tasking API Postman Collection
• Ursa Space Postman Environment

Examples

The following examples assume you have curl installed and available via your command line terminal. If you are new to curl or need help installing it on your machine, we recommend following an online guide such as https://developer.zendesk.com/documentation/api-basics/getting-started/installing-and-using-curl/ to get started.

curl --location --request POST 'https://platform.ursaspace.com/api/pas/login' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode 'username=<Your Ursa Space username/email>' --data-urlencode 'password=<Your Ursa Space password>'

If the login was successful, copy the access_token text out of the response and run the final command:

export TOKEN=<TOKEN>

This will create an environment variable $TOKEN that can be used in command line queries like those shown in examples below.

Submit a New Feasibility Request

curl --location 'https://platform.ursaspace.com/api/v1/tfs/feasibility' --header 'Content-Type: application/json' --header "Authorization: Bearer $TOKEN" --data '{
    "target_lat": 42.0,
    "target_lon": -76.0,
    "start_datetime": "2024-10-10T00:00:00.000",
    "end_datetime": "2024-10-12T00:00:00.000" 
}'

{
    "owner": "alexander.mcelroy@ursaspace.com",
    "status": "CREATED",
    "id": "c6a1980e-4cb4-426c-959a-b7a9016fe74c",
    "feasibility_request": {
        "target_lat": 42.0,
        "target_lon": -76.0,
        "start_datetime": "2024-10-10T00:00:00.000",
        "end_datetime": "2024-10-12T00:00:00.000"
    },
    "created_at": "2024-10-06T18:37:56.243"
}

Get the Status of a Feasibility Request

curl --location 'https://platform.ursaspace.com/api/v1/tfs/feasibility/c6a1980e-4cb4-426c-959a-b7a9016fe74c' --header "Authorization: Bearer $TOKEN"

{
    "owner": "alexander.mcelroy@ursaspace.com",
    "status": "SUCCEEDED",
    "id": "c6a1980e-4cb4-426c-959a-b7a9016fe74c",
    "feasibility_request": {
        "target_lat": 42.0,
        "target_lon": -76.0,
        "start_datetime": "2024-10-10T00:00:00.000",
        "end_datetime": "2024-10-12T00:00:00.000"
    },
    "created_at": "2024-10-06T18:37:56.243",
    "completed_at": "2024-10-06T18:39:20.000",
    "tasking_opportunities": [
        {
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -76.0,
                    42.0
                ]
            },
            "vendor": "UMBRA",
            "satellite_id": "UMBRA-07",
            "available_modes": [
                "UMBRA_SPOTLIGHT_1M",
                "UMBRA_SPOTLIGHT_50CM",
                "UMBRA_SPOTLIGHT_35CM",
                "UMBRA_SPOTLIGHT_25CM",
                "UMBRA_SPOTLIGHT_1M_2_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_2_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_2_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_2_LOOKS",
                "UMBRA_SPOTLIGHT_1M_3_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_3_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_3_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_3_LOOKS",
                "UMBRA_SPOTLIGHT_1M_4_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_4_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_4_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_4_LOOKS",
                "UMBRA_SPOTLIGHT_1M_5_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_5_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_5_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_5_LOOKS",
                "UMBRA_SPOTLIGHT_1M_8_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_8_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_8_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_8_LOOKS",
                "UMBRA_SPOTLIGHT_1M_10_LOOKS",
                "UMBRA_SPOTLIGHT_50CM_10_LOOKS",
                "UMBRA_SPOTLIGHT_35CM_10_LOOKS",
                "UMBRA_SPOTLIGHT_25CM_10_LOOKS"
            ],
            "window_open": "2024-10-10T03:03:15.000",
            "window_close": "2024-10-10T03:13:30.000",
            "look_direction": "RIGHT",
            "grazing_min": 54.918,
            "grazing_max": 69.872,
            "incidence_min": 20.128,
            "incidence_max": 35.082,
            "azimuth_min": 198.517,
            "azimuth_max": 318.212,
            "squint_min": -59.514,
            "squint_max": 59.744
        },
        {
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -76.0,
                    42.0
                ]
            },
            "vendor": "CAPELLA",
            "satellite_id": "CAP-10",
            "available_modes": [
                "CAPELLA_SPOTLIGHT_ULTRA",
                "CAPELLA_SPOTLIGHT",
                "CAPELLA_SPOTLIGHT_WIDE",
                "CAPELLA_STRIPMAP_20KM",
                "CAPELLA_STRIPMAP_50KM",
                "CAPELLA_STRIPMAP_100KM"
            ],
            "window_open": "2024-10-10T20:36:14.459",
            "window_close": "2024-10-10T20:38:57.158",
            "look_direction": "RIGHT",
            "grazing_min": 52.325,
            "grazing_max": 58.847,
            "incidence_min": 31.153,
            "incidence_max": 37.675,
            "azimuth_min": 83.777,
            "azimuth_max": 87.868,
            "squint_min": -74.875,
            "squint_max": -70.791
        }
    ]
}

Submit a New Tasking Request

curl --location 'https://platform.ursaspace.com/api/v1/tfs/tasking' --header 'Content-Type: application/json' --header "Authorization: Bearer $TOKEN" --data '{
    "target_lat": 42.0,
    "target_lon": -76.0,
    "target_datetime": "2024-10-30T00:00:00.000",
    "mode": "CAPELLA_SPOTLIGHT" 
}'

{
    "owner": "alexander.mcelroy@ursaspace.com",
    "status": "RECEIVED",
    "id": "7502f737-0f06-4085-b6df-9f8da9cb0c27",
    "tasking_request": {
        "mode": "CAPELLA_SPOTLIGHT",
        "target_lat": 42.0,
        "target_lon": -76.0,
        "target_datetime": "2024-10-30T00:00:00.000"
    },
    "created_at": "2024-10-06T18:46:43.552"
}

Get the Status of a Tasking Request

curl --location 'https://platform.ursaspace.com/api/v1/tfs/tasking/7502f737-0f06-4085-b6df-9f8da9cb0c27' --header "Authorization: Bearer $TOKEN"

{
    "owner": "alexander.mcelroy@ursaspace.com",
    "status": "RECEIVED",
    "id": "7502f737-0f06-4085-b6df-9f8da9cb0c27",
    "tasking_request": {
        "mode": "CAPELLA_SPOTLIGHT",
        "target_lat": 42.0,
        "target_lon": -76.0,
        "target_datetime": "2024-10-30T00:00:00.000"
    },
    "created_at": "2024-10-06T18:46:43.552"
}

List All Tasking Requests

curl --location 'https://platform.ursaspace.com/api/v1/tfs/tasking' --header "Authorization: Bearer $TOKEN"

{
    "tasking_requests": [
        {
            "owner": "alexander.mcelroy@ursaspace.com",
            "status": "RECEIVED",
            "id": "7502f737-0f06-4085-b6df-9f8da9cb0c27",
            "tasking_request": {
                "mode": "CAPELLA_SPOTLIGHT",
                "target_lat": 42.0,
                "target_lon": -76.0,
                "target_datetime": "2024-10-30T00:00:00.000"
            },
            "created_at": "2024-10-06T18:46:43.552"
        }
    ]
}

Cancel a Tasking Request

curl --location --request POST 'https://platform.ursaspace.com/api/v1/tfs/tasking/7502f737-0f06-4085-b6df-9f8da9cb0c27/cancel' --header "Authorization: Bearer $TOKEN"

{
    "owner": "alexander.mcelroy@ursaspace.com",
    "status": "CANCELED",
    "id": "7502f737-0f06-4085-b6df-9f8da9cb0c27",
    "tasking_request": {
        "mode": "CAPELLA_SPOTLIGHT",
        "target_lat": 42.0,
        "target_lon": -76.0,
        "target_datetime": "2024-10-30T00:00:00.000"
    },
    "created_at": "2024-10-06T18:46:43.552"
}