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
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)
email and password
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
- Return type
- 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, seeget_presigned_assets()
optionally provide order_id instead of assets_presigned, see
submit_order()
- NOTE: Precedence order (high to low)
assets_presigned
order_id
local_dir (
Union
[Path
,str
]) – local directory where assets are saved to, tempdir if not providedinclude (
Union
[List
[Union
[str
,AssetType
]],str
]) – white-listing, which assets should be included, e.g. [“HH”] => only download HH assetexclude (
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 existingthreaded (
bool
) – download assets of product in multiple threadsshow_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, seeget_presigned_items()
order_id (
Optional
[str
]) – optionally provide order_id instead of assets_presigned, seesubmit_order()
tasking_request_id (
Optional
[str
]) – tasking request UUID of the task request you wish to download all associated products forcollect UUID you wish to download all associated products for
- NOTE: Precedence order (high to low)
items_presigned
order_id
tasking_request_id
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 providedinclude (
Union
[List
[Union
[str
,AssetType
]],str
]) – white-listing, which assets should be included, e.g. [“HH”] => only download HH assetexclude (
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 existingthreaded (
bool
) – download assets of product in multiple threadsshow_progress (
bool
) – show download status progressbarseparate_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
- 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]]
- 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
- Return type
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)
- 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)
stac_ids
items
- Parameters
stac_ids (
Optional
[List
[str
]]) – STAC IDs that active order should includeitems (
Union
[List
[Dict
[str
,Any
]],SearchResult
,None
]) – STAC items, returned bysearch()
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 IDomit_search (
bool
) – omit search to ensure provided STAC IDs are valid - only works if items are providedomit_review (
bool
) – omit review stageReturns – str: order UUID
- Return type