API Reference

class capella_console_client.CapellaConsoleClient(email=None, password=None, token=None, verbose=False, no_token_check=False, base_url='https://api.capellaspace.com', search_url=None, no_auth=False)[source]

API client for https://api.capellaspace.com.

API docs: https://docs.capellaspace.com/accessing-data/searching-for-data

Parameters
  • email (Optional[str]) – email on api.capellaspace.com

  • password (Optional[str]) – password on api.capellaspace.com

  • token (Optional[str]) – valid JWT access token

  • verbose (bool) – flag to enable verbose logging

  • no_token_check (bool) – does not check if provided JWT token is valid

  • base_url (Optional[str]) – Capella console API base URL override

  • search_url (Optional[str]) – Capella catalog/search/ override

  • no_auth (bool) – bypass authentication

Note

not providing either email and password or a jwt token for authentication will prompt you for email and password, which is not what you want in a script

NOTE: Precedence order (high to low)
  1. email and password

  2. JWT token

create_repeat_request(**kwargs)[source]

Create a new repeat request

Find more information at https://docs.capellaspace.com/constellation-tasking/tasking-requests

Parameters
  • geometry – A GeoJSON representation of the area/point of interest. Must be either a polygon or point

  • name – Can be used along with description to help characterize and describe the tasking request. Default: “”

  • description – Can be used along with name to help characterize and describe the tasking request. Default: “”

  • collection_tier – Preference for data to be collected within a certain time after window_open. Can be either “flexible” or “routine”. Default: “routine”

  • product_category – Category used to define image collection. “Extended” has broader look angles and “Custom” allows specifying advanced image acquisition parameters. More information on the specifics of each can be found at https://support.capellaspace.com/hc/en-us/articles/360049110852-SAR-Imagery-Product-Tasking-Categories. One of “standard”, “extended”, and “custom”. Default: “standard”

  • archive_holdback – If defined will specify a time period during which the resulting imagery will be kept from the publicly accessible archive. One of “none”, “one_year”, “thirty_day”, “permanent”. Default: “none”

  • custom_attribute_1 – Can be used along with custom_attribute_2 to help you track a Capella task with your own metadata or internal systems. Default: None

  • custom_attribute_2 – Can be used along with custom_attribute_1 to help you track a Capella task with your own metadata or internal systems. Default: None

  • product_types – List of analytics to add to the order along with the imagery. Currently available analytics are Amplitude Change Detection and Vessel Detection. One of “ACD”, “VS”. Default: None

  • repeat_start – Starting date (in UTC) when you would like data to begin being collected. Default: Now

  • repeat_end – Starting date (in UTC) when you would like data to stop being collected. This and repetition_count are mutually exclusive; only one of them can be defined per request. Default: None

  • repetition_interval – Number of days between the start of each derived request. Default: 7

  • repetition_count – Total number of acquisitions in the repeat series. This and repeat_end are mutually exclusive; only one of them can be defined per request. Default: None

  • maintain_scene_framing – Whether to maintain consistent framing (look-direction, ascending/descending, orbital-plane) across all acquisitions. Default: False

  • look_angle_tolerance – Tolerance to look-angle deviations across all acquisitions. Default: None

  • collect_mode – Collect mode to be used by the satellite when making the collect. One of “spotlight”, “stripmap”, “sliding_spotlight”. Default: “spotlight”

  • look_direction – Constraint on view angle. One of “right”, “left”, “either”. Default: “either”

  • asc_dsc – Constraint on ascending/descending pass. One of “ascending”, “descending”, “either”. Default: “either”

  • orbital_planes – List of orbital planes allowed to service request. If empty any spacecraft in any plane can service request. One of 45, 53, 97. Default: None

  • local_time – Times, in the timezone of the area where the image will be collected, during which the collect can be taken. Represented by a list of time ranges as seconds in the day. For example, [[21600, 64800]] would allow collects between 6 AM and 6 PM; [[0, 21600], [64800, 86400]] would allow collects between 6 PM and 12 AM as well as from 12 AM to 6 AM. Alternatively, you can pass string values of “day”, “night”, or “anytime” which are parsed to [[21600, 64800]], [[0, 21600], [64800, 86400]], and [[0, 86400]] respectively. Default: None

  • off_nadir_min – Minimum off-nadir angle permitted. Must be less than off_nadir_max. Default: None

  • off_nadir_max – Maximum off-nadir angle permitted. Must be greater than off_nadir_min. Default: None

  • elevation_min – Minimum elevation angle permitted. Default: None

  • elevation_max – Maximum elevation angle permitted. Default: None

  • image_length – Image length. Default: None

  • image_width – Image width. Default: None

  • azimuth – Azimuth angle at collect mid-time. Clockwise angle from North to the spacecraft in the target frame of reference. Default: None

  • grr_min – Minimum ground-range resolution. Minimum is in ordinal sense. Default: None

  • grr_max – Maximum ground-range resolution. Maximum is in ordinal sense. Default: None

  • srr_min – Minimum slant-range resolution. Minimum is in ordinal sense. Default: None

  • srr_max – Maximum slant-range resolution. Maximum is in ordinal sense. Default: None

  • azr_min – Minimum azimuth resolution. Minimum is in ordinal sense. Default: None

  • azr_max – Maximum azimuth resolution. Maximum is in ordinal sense. Default: None

  • nesz_max – Maximum allowable NESZ of resulting collect. Default: None

  • num_looks – Number of looks to use in processing collect. Default: None

  • polarization – Image polarization. One of “HH”, “VV”. Default: None

Returns

created repeat request metadata

Return type

Dict[str, Any]

create_tasking_request(**kwargs)[source]

Create a new tasking request

Find more information at https://docs.capellaspace.com/constellation-tasking/tasking-requests

Parameters
  • geometry – A GeoJSON representation of the area/point of interest. Must be either a polygon or point

  • name – Can be used along with description to help characterize and describe the tasking request. Default: “”

  • description – Can be used along with name to help characterize and describe the tasking request. Default: “”

  • window_open – Earliest time (in UTC) that you would like data to be collected. Default: Now

  • window_close – Latest time (in UTC) that you would like data to be collected. Default: Seven days after window_open

  • collection_tier – Preference for data to be collected within a certain time after window_open. Can be one of “urgent”, “priority”, “standard”, and “flexible”. Default: “standard”

  • product_category – Category used to define image collection. “Extended” has broader look angles and “Custom” allows specifying advanced image acquisition parameters. More information on the specifics of each can be found at https://support.capellaspace.com/hc/en-us/articles/360049110852-SAR-Imagery-Product-Tasking-Categories. One of “standard”, “extended”, and “custom”. Default: “standard”

  • product_types – List of analytics to add to the order along with the imagery. Currently available analytics are Amplitude Change Detection and Vessel Detection. One of “ACD”, “VS”. Default: None

  • archive_holdback – If defined will specify a time period during which the resulting imagery will be kept from the publicly accessible archive. One of “none”, “one_year”, “thirty_day”, “permanent”. Default: “none”

  • custom_attribute_1 – Can be used along with custom_attribute_2 to help you track a Capella task with your own metadata or internal systems. Default: None

  • custom_attribute_2 – Can be used along with custom_attribute_1 to help you track a Capella task with your own metadata or internal systems. Default: None

  • collect_mode – Collect mode to be used by the satellite when making the collect. One of “spotlight”, “stripmap”, “sliding_spotlight”. Default: “spotlight”

  • look_direction – Constraint on view angle. One of “right”, “left”, “either”. Default: “either”

  • asc_dsc – Constraint on ascending/descending pass. One of “ascending”, “descending”, “either”. Default: “either”

  • orbital_planes – List of orbital planes allowed to service request. If empty any spacecraft in any plane can service request. One of 45, 53, 97. Default: None

  • local_time – Times, in the timezone of the area where the image will be collected, during which the collect can be taken. Represented by a list of time ranges as seconds in the day. For example, [[21600, 64800]] would allow collects between 6 AM and 6 PM; [[0, 21600], [64800, 86400]] would allow collects between 6 PM and 12 AM as well as from 12 AM to 6 AM. Alternatively, you can pass string values of “day”, “night”, or “anytime” which are parsed to [[21600, 64800]], [[0, 21600], [64800, 86400]], and [[0, 86400]] respectively. Default: None

  • off_nadir_min – Minimum off-nadir angle permitted. Must be less than off_nadir_max. Default: None

  • off_nadir_max – Maximum off-nadir angle permitted. Must be greater than off_nadir_min. Default: None

  • elevation_min – Minimum elevation angle permitted. Default: None

  • elevation_max – Maximum elevation angle permitted. Default: None

  • image_length – Image length. Default: None

  • image_width – Image width. Default: None

  • azimuth – Azimuth angle at collect mid-time. Clockwise angle from North to the spacecraft in the target frame of reference. Default: None

  • grr_min – Minimum ground-range resolution. Minimum is in ordinal sense. Default: None

  • grr_max – Maximum ground-range resolution. Maximum is in ordinal sense. Default: None

  • srr_min – Minimum slant-range resolution. Minimum is in ordinal sense. Default: None

  • srr_max – Maximum slant-range resolution. Maximum is in ordinal sense. Default: None

  • azr_min – Minimum azimuth resolution. Minimum is in ordinal sense. Default: None

  • azr_max – Maximum azimuth resolution. Maximum is in ordinal sense. Default: None

  • nesz_max – Maximum allowable NESZ of resulting collect. Default: None

  • num_looks – Number of looks to use in processing collect. Default: None

  • polarization – Image polarization. One of “HH”, “VV”. Default: None

Returns

created tasking request metadata

Return type

Dict[str, Any]

download_asset(pre_signed_url, local_path=None, override=False, show_progress=False)[source]

downloads a presigned asset url to disk

Parameters
  • pre_signed_url (str) – presigned asset url, see get_presigned_items()

  • local_path (Union[Path, str]) – local output path - file is written to OS’s temp dir if not provided

  • override (bool) – override already existing local_path

  • show_progress (bool) – show download status progressbar

Return type

Path

download_product(assets_presigned=None, order_id=None, local_dir=PosixPath('/tmp'), include=None, exclude=None, override=False, threaded=True, show_progress=False)[source]

download all assets of a product (TO BE DEPRECATED)

Parameters
  • assets_presigned (Optional[Dict[str, Any]]) – mapping of presigned assets of multiple products, see get_presigned_assets()

  • order_id (Optional[str]) –

    optionally provide order_id instead of assets_presigned, see submit_order()

    NOTE: Precedence order (high to low)
    1. assets_presigned

    2. order_id

  • local_dir (Union[Path, str]) – local directory where assets are saved to, tempdir if not provided

  • include (Union[List[Union[str, AssetType]], str]) – white-listing, which assets should be included, e.g. [“HH”] => only download HH asset

  • exclude (Union[List[Union[str, AssetType]], str]) –

    black-listing, which assets should be excluded, e.g. [“HH”, “thumbnail”] => download ALL except HH and thumbnail assets NOTE: explicit DENY overrides explicit ALLOW

    asset choices:
    • ’HH’, ‘VV’, ‘raster’, ‘metadata’, ‘thumbnail’ (external)

      Note: raster == ‘HH’ || ‘VV’

    • ’log’, ‘profile’, ‘stats’, ‘stats_plots’ (internal accessible only)

  • override (bool) – override already existing

  • threaded (bool) – download assets of product in multiple threads

  • show_progress (bool) – show download status progressbar

Returns

Local paths of downloaded files keyed by asset type, e.g.

{
    "<asset_type>": <path-to-asset>,
    ...
}

Return type

Dict[str, Path]

download_products(items_presigned=None, order_id=None, tasking_request_id=None, collect_id=None, local_dir=PosixPath('/tmp'), include=None, exclude=None, override=False, threaded=True, show_progress=False, separate_dirs=True, product_types=None)[source]

download all assets of multiple products

Parameters
  • items_presigned (Optional[List[Dict[str, Any]]]) – stac items with presigned assets, see get_presigned_items()

  • order_id (Optional[str]) – optionally provide order_id instead of assets_presigned, see submit_order()

  • tasking_request_id (Optional[str]) – tasking request UUID of the task request you wish to download all associated products for

  • collect_id (Optional[str]) –

    collect UUID you wish to download all associated products for

    NOTE: Precedence order (high to low)
    1. items_presigned

    2. order_id

    3. tasking_request_id

    4. collect_id

    Meaning e.g. assets_presigned takes precedence over order_id, …

  • local_dir (Union[Path, str]) – local directory where assets are saved to, tempdir if not provided

  • include (Union[List[Union[str, AssetType]], str]) – white-listing, which assets should be included, e.g. [“HH”] => only download HH asset

  • exclude (Union[List[Union[str, AssetType]], str]) –

    black-listing, which assets should be excluded, e.g. [“HH”, “thumbnail”] => download ALL except HH and thumbnail assets

    NOTE: explicit DENY overrides explicit ALLOW

    asset choices:
    • ’HH’, ‘VV’, ‘raster’, ‘metadata’, ‘thumbnail’ (external) - raster == ‘HH’ || ‘VV’

    • ’log’, ‘profile’, ‘stats’, ‘stats_plots’ (internal)

  • override (bool) – override already existing

  • threaded (bool) – download assets of product in multiple threads

  • show_progress (bool) – show download status progressbar

  • separate_dirs (bool) –

    set to True in order to save the respective product assets into products directories, i.e.

    /tmp/<stac_id_1>/<stac_id_1>.tif /tmp/<stac_id_2>/<stac_id_2>.tif …

    set to False in order to the respective product assets directly into the provided local_dir, i.e.

    /tmp/<stac_id_1>.tif /tmp/<stac_id_2>.tif …

  • product_types (List[Union[str, ProductType]]) – filter by product type, e.g. [“SLC”, “GEO”]

Returns

Local paths of downloaded files keyed by STAC id and asset type, e.g.

{
    "stac_id_1": {
        "<asset_type>": <path-to-asset>,
        ...
    }
}

Return type

Dict[str, Dict[str, Path]]

get_asset_bytesize(pre_signed_url)[source]

get size in bytes of pre_signed_url

Return type

int

Parameters

pre_signed_url (str) –

get_collects_for_task(tasking_request_id)[source]

get all the collects associated with this task (see get_task())

Parameters
  • task – task metadata - return of get_task()

  • tasking_request_id (str) –

Returns

collect metadata associated

Return type

List[Dict[str, Any]]

get_presigned_assets(order_id, stac_ids=None, sort_by=None, assets_only=True)[source]

get presigned assets hrefs for all products contained in order

Parameters
Returns

List of assets of respective product, e.g.

[
    {
        "<asset_type>": {
            "title": ...,
            "href": ...,
            "type": ...
        },
        ...
    }
]

Return type

List[Dict[str, Any]]

get_presigned_items(order_id, stac_ids=None, sort_by=None)[source]

get presigned items hrefs for all products contained in order

Parameters
Returns

List of assets of respective product, e.g.

[
    {
        "<asset_type>": {
            "title": ...,
            "href": ...,
            "type": ...
        },
        ...
    }
]

Return type

List[Dict[str, Any]]

get_stac_items_of_order(order_id, ids_only=False)[source]

get stac items of an existing order

Parameters
  • order_id (str) – order id

  • ids_only (bool) –

Return type

Union[List[str], SearchResult]

get_task(tasking_request_id)[source]

fetch task for the specified tasking_request_id

Parameters

tasking_request_id (str) – tasking request UUID

Returns

task metadata

Return type

Dict[str, Any]

is_task_completed(task)[source]

check if a task has completed

Return type

bool

Parameters

task (Dict[str, Any]) –

list_orders(*order_ids, is_active=False)[source]

list orders

Parameters
  • order_id – list only specific orders (variadic, specify multiple)

  • is_active (Optional[bool]) – list only active (non-expired) orders

  • order_ids (Optional[str]) –

Returns

metadata of orders

Return type

List[Dict[str, Any]]

list_tasking_requests(*tasking_request_ids, for_org=False, **kwargs)[source]

list/ search tasking requests

Find more information at https://docs.capellaspace.com/constellation-tasking/tasking-requests

Parameters
  • tasking_request_ids (Optional[str]) – list only specific tasking_request_ids (variadic, specify multiple)

  • for_org (Optional[bool]) – list all tasking requests of your organization (instead of only yours) - requires organization index/ admin permission

  • kwargs (Optional[Dict[str, Any]]) –

Return type

List[Dict[str, Any]]

additionally the following search filters are supported:

  • status: TaskingRequestStatus, one of received, review, submitted, active, accepted, rejected, expired, completed, anomaly, canceled, error, failed

  • submission_time__gt: datetime, e.g. datetime.datetime(2022, 12, 9, 21)

Returns

metadata of tasking requests

Return type

List[Dict[str, Any]]

Parameters
search(**kwargs)[source]

paginated search for up to 500 matches (if no bigger limit specified)

Find more information at https://docs.capellaspace.com/accessing-data/searching-for-data

supported search filters:

  • bbox: List[float, float, float, float], e.g. [12.35, 41.78, 12.61, 42]

  • billable_area: Billable Area in m^2

  • center_frequency: Union[int, float], Center Frequency (GHz)

  • collections: List[str], e.g. [“capella-open-data”]

  • collect_id: str, capella internal collect-uuid, e.g. ‘78616ccc-0436-4dc2-adc8-b0a1e316b095’

  • constellation: str, e.g. “capella”

  • datetime: str, e.g. “2020-02-12T00:00:00Z”

  • epsg: int, e.g. 32648

  • frequency_band: str, Frequency band, one of “P”, “L”, “S”, “C”, “X”, “Ku”, “K”, “Ka”

  • ids: List[str], e.g. [“CAPELLA_C02_SP_GEO_HH_20201109060434_20201109060437”]

  • intersects: geometry component of the GeoJSON, e.g. {‘type’: ‘Point’, ‘coordinates’: [-113.1, 51.1]}

  • incidence_angle: Union[int, float], Center incidence angle, between 0 and 90

  • instruments: List[str], leveraged instruments, e.g. [“capella-radar-5”]

  • instrument_mode: str, Instrument mode, one of “spotlight”, “stripmap”, “sliding_spotlight”

  • limit: int, default: 500

  • local_datetime: str, local datetime, e.g. 2022-12-12TT07:37:42.324551+0800

  • local_time: str, local time, e.g. 07:37:42.324551

  • local_timezone: str, local timezone, e.g. Asia/Shanghai

  • look_angle: Union[int, float], e.g. 28.4

  • looks_azimuth: int, e.g. 5

  • looks_equivalent_number: int, Equivalent number of looks (ENL), e.g. 3

  • looks_range: int, e.g. 5

  • observation_direction: str, Antenna pointing direction, one of “right”, “left”

  • orbit_state: str, Orbit State, one of “ascending”, “descending”

  • orbital_plane: int, Orbital Plane, inclination angle of orbit

  • pixel_spacing_azimuth: Union[int, float], Pixel spacing azimuth (m), e.g. 0.5

  • pixel_spacing_range: Union[int, float], Pixel spacing range (m), e.g. 0.5

  • platform: str, e.g. “capella-2”

  • polarizations: str, one of “HH”, “VV”, “HV”, “VH”

  • product_category: str, one of “standard”, “custom”, “extended”

  • product_type: str, one of “SLC”, “GEO”

  • resolution_azimuth: float, Resolution azimuth (m), e.g. 0.5

  • resolution_ground_range: float, Resolution ground range (m), e.g. 0.5

  • resolution_range: float, Resolution range (m), e.g. 0.5

  • squint_angle: float, Squint angle, e.g. 30.1

supported operations:
  • eq: equality search

  • in: within group

  • gt: greater than

  • gte: greater than equal

  • lt: lower than

  • lte: lower than equal

sorting:
  • sortby: List[str] - must be supported fields, e.g. [“+datetime”]

Returns

STAC items matched

Return type

List[Dict[str, Any]]

submit_order(stac_ids=None, items=None, check_active_orders=False, omit_search=False, omit_review=False)[source]

submit an order by stac_ids or items.

NOTE: Precedence order (high to low)
  1. stac_ids

  2. items

Parameters
  • stac_ids (Optional[List[str]]) – STAC IDs that active order should include

  • items (Union[List[Dict[str, Any]], SearchResult, None]) – STAC items, returned by search()

  • check_active_orders (bool) – check if any active order containing ALL stac_ids is available if True: returns that order ID if False: submits a new order and returns new order ID

  • omit_search (bool) – omit search to ensure provided STAC IDs are valid - only works if items are provided

  • omit_review (bool) – omit review stage

  • Returns – str: order UUID

Return type

str

whoami()[source]

display user info

Returns

return of GET /user

Return type

Dict[str, Any]