callusgs package 

dataset_browse(dataset_id: str) → ApiResponse

This request is used to return the browse configurations for the specified dataset.

Parameters:: dataset_id (str) – Determines which dataset to return browse configurations for
Returns:: List of Dicts, each containing information about configuration of subdatasets
Return type:: ApiResponse

dataset_bulk_products(dataset_name: str | None = None) → ApiResponse

Lists all available bulk products for a dataset - this does not guarantee scene availability.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (Optional[str], optional) – Used to identify the which dataset to return results for, defaults to None
Returns:: List of dictionaries containing bulk download information
Return type:: ApiResponse

dataset_catalogs() → ApiResponse

This method is used to retrieve the available dataset catalogs. The use of dataset catalogs are not required, but are used to group datasets by their use within our web applications.

Returns:: Dictionary with all available data catalogs
Return type:: ApiResponse

This method is used to search datasets under the categories.

Parameters:

catalog (Optional[str], optional) – Used to identify datasets that are associated with a given application, defaults to None
include_message (Optional[bool], optional) – Optional parameter to include messages regarding specific dataset components, defaults to None
public_only (Optional[bool], optional) – Used as a filter out datasets that are not accessible to unauthenticated general public users, defaults to None
use_customization (Optional[bool], optional) – Used as a filter out datasets that are excluded by user customization, defaults to None
parent_id (Optional[str], optional) – If provided, returned categories are limited to categories that are children of the provided ID, defaults to None
dataset_filter (Optional[str], optional) – If provided, filters the datasets - this automatically adds a wildcard before and after the input value, defaults to None

Returns:

Dict containing all datasets within a catalog

Return type:

dataset_clear_customization(dataset_name: str | None = None, metadata_type: List[str] | None = None, file_group_ids: List[str] | None = None) → None

This method is used the remove an entire customization or clear out a specific metadata type.

Parameters:

dataset_name (Optional[str], optional) – Used to identify the dataset to clear. If null, all dataset customizations will be cleared., defaults to None
metadata_type (Optional[List[str]], optional) – If populated, identifies which metadata to clear(export, full, res_sum, shp), defaults to None
file_group_ids (Optional[List[str]], optional) – If populated, identifies which file group to clear, defaults to None

Raises:

dataset_coverage(dataset_name: str) → ApiResponse

Returns coverage for a given dataset.

Parameters:: dataset_name (str) – Determines which dataset to return coverage for
Returns:: Bounding box and GeoJSON coverage
Return type:: ApiResponse

dataset_download_options(dataset_name: str, scene_filter: SceneFilter | None = None) → ApiResponse

This request lists all available products for a given dataset.

Warning

Product listed here does not guarantee scene availability!

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Used to identify the which dataset to return results for
scene_filter (Optional[SceneFilter], optional) – Used to filter data within the dataset, defaults to None

Returns:

List of available products

Return type:

dataset_file_groups(dataset_name: str) → ApiResponse

This method is used to list all configured file groups for a dataset.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (str) – Dataset alias
Returns:: Primary and secondary file group information
Return type:: ApiResponse

dataset_filters(dataset_name: str) → ApiResponse

This request is used to return the metadata filter fields for the specified dataset. These values can be used as additional criteria when submitting search and hit queries.

Parameters:: dataset_name (str) – Determines which dataset to return filters for
Returns:: Dict with all related dataset fiters
Return type:: ApiResponse

dataset_get_customization(dataset_name: str) → ApiResponse

This method is used to retrieve metadata customization for a specific dataset.

Parameters:: dataset_name (str) – Used to identify the dataset to search
Returns:: Dict containing customized metadata representations
Return type:: ApiResponse

dataset_get_customizations(dataset_names: ~typing.List[str] | None = None, metadata_type: ~typing.List[str] | None = <class 'str'>) → ApiResponse

This method is used to retrieve metadata customizations for multiple datasets at once.

Parameters:

dataset_names (Optional[List[str]], optional) – Used to identify the dataset(s) to return. If null it will return all the users customizations, defaults to None
metadata_type (Optional[List[str]], optional) – If populated, identifies which metadata to return(export, full, res_sum, shp), defaults to str

Returns:

Dict containing customized metadata representations for datasets, identified by their Ids

Return type:

dataset_messages(catalog: str, dataset_name: str | None = None, dataset_names: List[str] | None = None) → ApiResponse

Returns any notices regarding the given datasets features.

Parameters:

catalog (str) – Used to identify datasets that are associated with a given application
dataset_name (Optional[str], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None
dataset_names (Optional[List[str]], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None

Returns:

Dict containing notices per dataset supplied

Return type:

dataset_metadata(dataset_name: str) → ApiResponse

This method is used to retrieve all metadata fields for a given dataset.

Parameters:: dataset_name (str) – The system-friendly dataset name
Returns:: All metadata for given dataset
Return type:: ApiResponse

dataset_order_products(dataset_name: str) → ApiResponse

Lists all available order products for a dataset.

Warning

Product listed here does not guarantee scene availability!

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (str) – Used to identify the which dataset to return results for
Returns:: List of all products available for given dataset name
Return type:: ApiResponse
Example:

Api.dataset_order_products(“landsat_ot_c2_l2”)

# [ # { # “productCode”: “LO220”, # “productName”: “L8-9 Collection 2 Level 1 and Level 2 Std Products from Level 0 input” # }, # { # “productCode”: “LO221”, # “productName”: “L8-9 Collection 2 Level 2 Std product from Level 1 input” # }, # …, # ]

This method is used to find datasets available for searching. By passing only API Key, all available datasets are returned. Additional parameters such as temporal range and spatial bounding box can be used to find datasets that provide more specific data. The dataset name parameter can be used to limit the results based on matching the supplied value against the public dataset name with assumed wildcards at the beginning and end.

Note

Can be used to transfrom “natural language description” to datasetId and/or dataset_alias.

Warning

SpatialFilter is an abstract class. SpatialFilterMbr or SpatialFilterGeoJson must be supplied.

Parameters:

catalog (Optional[str], optional) – Used to identify datasets that are associated with a given application, defaults to None
category_id (Optional[str], optional) – Used to restrict results to a specific category (does not search sub-sategories), defaults to None
dataset_name (Optional[str], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None
include_messages (Optional[bool], optional) – Optional parameter to include messages regarding specific dataset components, defaults to None
public_only (Optional[bool], optional) – Used as a filter out datasets that are not accessible to unauthenticated general public users, defaults to None
include_unknown_spatial (Optional[bool], optional) – Optional parameter to include datasets that do not support geographic searching, defaults to None
temporal_filter (Optional[TemporalFilter], optional) – Used to filter data based on data acquisition, defaults to None
spatial_filter (Optional[SpatialFilter], optional) – Used to filter data based on data location, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Defined the sorting as Ascending (ASC) or Descending (DESC), defaults to “ASC”
sort_field (Optional[str], optional) – Identifies which field should be used to sort datasets (shortName - default, longName, dastasetName, GloVis), defaults to None
use_customization (Optional[bool], optional) – Optional parameter to indicate whether to use customization, defaults to None

Returns:

Get dataset descriptions and attributes

Return type:

Example:

Api().dataset_search(“EE”, “dataset_name=”Collection 2 Level-1”)

dataset_set_customization(dataset_name: str, excluded: bool | None = None, metadata: Metadata | None = None, search_sort: SearchSort | None = None, file_groups: FileGroups | None = None) → None

This method is used to create or update dataset customizations for a given dataset.

Warning

Metadata is an abstract class. Instead use a combination of MetadataAnd, MetadataBetween, MetadataOr and MetadataValue.

Parameters:

dataset_name (str) – Used to identify the dataset to search
excluded (Optional[bool], optional) – Used to exclude the dataset, defaults to None
metadata (Optional[Metadata], optional) – Used to customize the metadata layout, defaults to None
search_sort (Optional[SearchSort], optional) – Used to sort the dataset results, defaults to None
file_groups (Optional[FileGroups], optional) – Used to customize downloads by file groups, defaults to None

Raises:

dataset_set_customizations(dataset_customization: DatasetCustomization) → None

This method is used to create or update customizations for multiple datasets at once.

Parameters:: dataset_customization (DatasetCustomization) – Used to create or update a dataset customization for multiple datasets
Raises:: GeneralEarthExplorerException –

download(url: str, output_directory: Path | None = PosixPath('.'), chunk_size: int = 1024, no_progess: bool | None = False) → None

download_complete_proxied(proxied_downloads: List[ProxiedDownload]) → ApiResponse

Updates status to ‘C’ with total downloaded file size for completed proxied downloads.

Parameters:: proxied_downloads (List[ProxiedDownload]) – Used to specify multiple proxied downloads
Returns:: Dict containing number of failed downloads and number of statuses updated
Return type:: ApiResponse

download_eula(eula_code: str | None = None, eula_codes: List[str] | None = None) → ApiResponse

Gets the contents of a EULA from the eulaCodes.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

eula_code (Optional[str], optional) – Used to specify a single eula, defaults to None
eula_codes (Optional[List[str]], optional) – Used to specify multiple eulas, defaults to None

Returns:

List of EULAs

Return type:

download_labels(download_application: str | None = None) → ApiResponse

Gets a list of unique download labels associated with the orders.

Parameters:: download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
Returns:: Information about all valid(?) download orders [‘label’, ‘dateEntered’, ‘downloadSize’, ‘downloadCount’, ‘totalComplete’]
Return type:: ApiResponse

download_options(dataset_name: str, entity_ids: str | List[str] | None = None, list_id: str | None = None, include_secondary_file_groups: bool | None = None) → ApiResponse

The download options request is used to discover downloadable products for each dataset. If a download is marked as not available, an order must be placed to generate that product.

Note

“listId” is the id of the customized list which is built by scene-list-add. The parameter entityIds can be either a string array or a string. If passing them in a string, separate them by comma (no space between the IDs). If passing them in the test page, use string without quotes/spaces/brackets, just pass entityIds with commas, for example, LT50290302005219EDC00,LE70820552011359EDC00

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Dataset alias
entity_ids (Optional[Union[str, List[str]]], optional) – List of scenes, defaults to None
list_id (Optional[str], optional) – Used to identify the list of scenes to use, defaults to None
include_secondary_file_groups (Optional[bool], optional) – Optional parameter to return file group IDs with secondary products, defaults to None

Returns:

List of all available download options for a given datset

Return type:

download_order_load(download_application: str | None = None, label: str | None = None) → ApiResponse

This method is used to prepare a download order for processing by moving the scenes into the queue for processing.

Note

label must be label of order.

Parameters:

download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
label (Optional[str], optional) – Determines which order to load, defaults to None

Returns:

Metadata for specified orders given by labels

Return type:

download_order_remove(label: str, download_application: str | None = None) → None

This method is used to remove an order from the download queue.

Parameters:

download_application (str) – Used to denote the application that will perform the download
label (Optional[str], optional) – Determines which order to remove, defaults to None

Raises:

download_remove(download_id: int) → None

Removes an item from the download queue.

Note

“downloadId” can be retrieved by calling download-search.

Parameters:: download_id (int) – Represents the ID of the download from within the queue
Raises:: GeneralEarthExplorerException –

download_request(configuration_code: Literal['no_data', 'test', 'order', 'order+email'] | None = None, download_application: str | None = 'M2M', downloads: List[DownloadInput] | None = None, data_paths: List[FilepathDownload] | None = None, label: str | None = None, system_id: str | None = 'M2M', data_groups: List[FilegroupDownload] | None = None) → ApiResponse

This method is used to insert the requested downloads into the download queue and returns the available download URLs.

Each ID supplied in the downloads parameter you provide will be returned in one of three elements:

availableDownloads: URLs provided in this list are immediately available; note that these URLs take you to other distribution systems that may require authentication

preparingDownloads: IDs have been accepted but the URLs are NOT YET available for use

failed: IDs were rejected; see the errorMessage field for an explanation

Other information is also provided in the response:

newRecords: Includes a downloadId for each element of the downloads parameter that was accepted and a label that applies to the whole request

duplicateProducts: Requests that duplicate previous requests by the same user; these are not re-added to the queue and are not included in newRecords

numInvalidScenes: The number of products that could not be found by ID or failed to be requested for any reason

remainingLimits: The number of remaining downloads to hit the rate limits by user and IP address

limitType: The type of the limits are counted by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

recentDownloadCount: The number of downloads requested in the past 15 minutes

pendingDownloadCount: The number of downloads in pending state before they are available for download

unattemptedDownloadCount: The number of downloads in available status but the user has not downloaded yet

Warning

This API may be online while the distribution systems are unavailable. When this occurs, you will recieve the following error when requesting products that belong to any of these systems: ‘This download has been temporarily disabled. Please try again at a later time. We apologize for the inconvenience.’. Once the distribution system is back online, this error will stop occuring and download requests will succeed.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Note

The configuration_code parameter is seemingly related to the Bulk Download System, at least when set to either “order” or “order+email”. Setting to “None” is recommended!

Parameters:

configuration_code (Optional[Literal["no_data", "test", "order", "order+email"]], optional) – Used to customize the the download routine, primarily for testing, defaults to None
download_application (Optional[str], optional) – Used to denote the application that will perform the download. Internal use only!, defaults to “M2M”
downloads (Optional[List[DownloadInput]], optional) – Used to identify higher level products that this data may be used to create, defaults to None
data_paths (Optional[List[FilepathDownload]], optional) – Used to identify products by data path, specifically for internal automation and DDS functionality, defaults to None
label (Optional[str], optional) – If this value is passed it will overide all individual download label values, defaults to None
system_id (Optional[str], optional) – Identifies the system submitting the download/order. Internal use only!, defaults to None
data_groups (Optional[List[FilegroupDownload]], optional) – Identifies the products by file groups, defaults to None

Raises:

ValueError – When download_application or system_id do not equal “M2M.

Returns:

Dict of available downloads, downloads in prepration and failed requests

Return type:

download_retrieve(download_application: str | None = None, label: str | None = None) → ApiResponse

Returns all available and previously requests but not completed downloads.

Warning

This API may be online while the distribution systems are unavailable. When this occurs, the downloads being fulfilled by those systems will not appear as available nor are they counted in the ‘queueSize’ response field.

Parameters:

download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
label (Optional[str], optional) – Determines which downloads to return, defaults to None

Returns:

Dict with EULAs, List of available downloads ([‘url’, ‘label’, ‘entityId’, ‘eulaCode’, ‘filesize’ ‘datasetId’, ‘displayId’, ‘downloadId’, ‘statusCode’, ‘statusText’, ‘productCode’, ‘productName’, ‘collectionName’]), queue size and requested downloads

Return type:

download_search(active_only: bool | None = None, label: str | None = None, download_application: str | None = None) → ApiResponse

This method is used to search for downloads within the queue, regardless of status, that match the given label.

Parameters:

active_only (Optional[bool], optional) – Determines if completed, failed, cleared and proxied downloads are returned, defaults to None
label (Optional[str], optional) – Used to filter downloads by label, defaults to None
download_application (Optional[str], optional) – Used to filter downloads by the intended downloading application, defaults to None

Returns:

All download orders according to filters ([‘label’, ‘entityId’, ‘eulaCode’, ‘filesize’ ‘datasetId’, ‘displayId’, ‘downloadId’, ‘statusCode’, ‘statusText’, ‘productCode’, ‘productName’, ‘collectionName’])

Return type:

download_summary(download_application: str, label: str, send_email: bool | None) → ApiResponse

Gets a summary of all downloads, by dataset, for any matching labels.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

download_application (str) – Used to denote the application that will perform the download
label (str) – Determines which downloads to return
send_email (Optional[bool]) – If set to true, a summary email will also be sent

Returns:

Information about downloaded files

Return type:

grid2ll(grid_type: Literal['WRS1', 'WRS2'] | None = 'WRS2', response_shape: Literal['polygon', 'point'] | None = None, path: str | None = None, row: str | None = None) → ApiResponse

Used to translate between known grids and coordinates.

Parameters:

grid_type (Optional[Literal["WRS1", "WRS2"]], optional) – Which grid system is being used?, defaults to “WRS2”
response_shape (Optional[Literal["polygon", "point"]], optional) – What type of geometry should be returned - a bounding box polygon or a center point?, defaults to None
path (Optional[str], optional) – The x coordinate in the grid system, defaults to None
row (Optional[str], optional) – The y coordinate in the grid system, defaults to None

Returns:

Dict describing returned geometry

Return type:

login(username: str, password: str, user_context: Any = None)

Upon a successful login, an API key will be returned. This key will be active for two hours and should be destroyed upon final use of the service by calling the logout method.

Note

This request requires an HTTP POST request instead of a HTTP GET request as a security measure to prevent username and password information from being logged by firewalls, web servers, etc.

Parameters:

username (str) – ERS Username
password (str) – ERS Password
user_context (Any, optional) – Metadata describing the user the request is on behalf of, defaults to None

Raises:

HTTPError –

login_app_guest(application_token: str, user_token: str)

This endpoint assumes that the calling application has generated a single-use token to complete the authentication and return an API Key specific to that guest user. All subsequent requests should use the API Key under the ‘X-Auth-Token’ HTTP header as the Single Sign-On cookie will not authenticate those requests. The API Key will be active for two hours, which is restarted after each subsequent request, and should be destroyed upon final use of the service by calling the logout method.

The ‘appToken’ field will be used to verify the ‘Referrer’ HTTP Header to ensure the request was authentically sent from the assumed application.

Parameters:

application_token (str) – The token for the calling application
user_token (str) – The single-use token generated for this user

Raises:

HTTPError –

login_sso(user_context: UserContext = None)

This endpoint assumes that a user has an active ERS Single Sign-On Cookie in their browser or attached to this request. Authentication will be performed from the Single Sign-On Cookie and return an API Key upon successful authentication. All subsequent requests should use the API Key under the ‘X-Auth-Token’ HTTP header as the Single Sign-On cookie will not authenticate those requests. The API Key will be active for two hours, which is restarted after each subsequent request, and should be destroyed upon final use of the service by calling the logout method.

Parameters:: user_context (UserContext, optional) – Metadata describing the user the request is on behalf of, defaults to None
Raises:: NotImplementedError –

login_token(username: str, token: str)

This login method uses ERS application tokens to allow for authentication that is not directly tied the users ERS password. Instructions for generating the application token can be found here.

Upon a successful login, an API key will be returned. This key will be active for two hours and should be destroyed upon final use of the service by calling the logout method.

Note

This request requires an HTTP POST request instead of a HTTP GET request as a security measure to prevent username and password information from being logged by firewalls, web servers, etc.

Parameters:

username (str) – ERS Username
token (str) – Application Token

Raises:

HTTPError –

logout() → None: This method is used to remove the users API key from being used in the future. :raises HTTPError:

notifications(system_id: str) → ApiResponse

Gets a notification list.

Parameters:: system_id (str) – Used to identify notifications that are associated with a given application
Returns:: List of all notifications
Return type:: ApiResponse

order_products(dataset_name: str, entity_ids: List[str] | None = None, list_id: str | None = None) → ApiResponse

Gets a list of currently selected products - paginated.

Note

“listId” is the id of the customized list which is built by scene-list-add.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Dataset alias
entity_ids (Optional[List[str]], optional) – List of scenes, defaults to None
list_id (Optional[str], optional) – Used to identify the list of scenes to use, defaults to None

Returns:

Information about selected products (i.e. id, price, entityId, availability, datasetId, productCode and productName)

Return type:

Submits the current product list as a TRAM order - internally calling tram-order-create.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

products (List[Product]) – Used to identify higher level products that this data may be used to create
auto_bulk_order (Optional[bool], optional) – If any products can be bulk ordered as a result of completed processing this option allows users to have orders automatically submitted, defaults to None
processing_parameters (Optional[str], optional) – Optional processing parameters to send to the processing system, defaults to None
priority (Optional[int], optional) – Processing Priority, defaults to None
order_comment (Optional[str], optional) – Optional textual identifier for the order, defaults to None
system_id (Optional[str], optional) – Identifies the system submitting the order, defaults to None

Returns:

Information about successfull (orderNumber) and failed orders

Return type:

permissions() → ApiResponse

Returns a list of user permissions for the authenticated user. This method does not accept any input.

Returns:: List of user permissions
Return type:: List[str]

placename(feature_type: Literal['US', 'World'] | None = None, name: str | None = None) → ApiResponse

Geocoder

Parameters:

feature_type (Optional[Literal["US", "World"]], optional) – Type of feature - see type hint, defaults to None
name (Optional[str], optional) – Name of the feature, defaults to None

Returns:

Return list of dictionaries for matched places. Dictionary keys are: [‘id’, ‘feature_id’, ‘placename’, ‘feature_code’, ‘country_code’, ‘latitude’, ‘longitude’, ‘feature_name’, ‘country_name’].

Return type:

Raises:

HTTPError –

rate_limit_summary(ip_address: List[str] | None = None) → ApiResponse

Returns download rate limits and how many downloads are in each status as well as how close the user is to reaching the rate limits

Three elements are provided in the response:

initialLimits: Includes the initial downloads rate limits

recentDownloadCount: The maximum number of downloads requested in the past 15 minutes

pendingDownloadCount: The maximum number of downloads in pending state before they are available for download

unattemptedDownloadCount: The maximum number of downloads in available status but the user has not downloaded yet

remainingLimits: Includes downloads that are currently remaining and count towards the rate limits. Users should be watching out for any of those numbers approaching 0 which means it is close to hitting the rate limits

limitType: The type of the limits are counted by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

recentDownloadCount: The number of downloads requested in the past 15 minutes

pendingDownloadCount: The number of downloads in pending state before they are available for download

unattemptedDownloadCount: The number of downloads in available status but the user has not downloaded yet

recentDownloadCounts: Includes the downloads count in each status for the past 15 minutes

countType: The type of the download counts are calculated by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

downloadCount: The number of downloads per status in the past 15 minutes

Warning

Users should be watching out for any of the remainingLimits numbers approaching 0 which means it is close to hitting the rate limits.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Warning

This API may be online while the distribution systems are unavailable. When this occurs, you will recieve the following error when requesting products that belong to any of these systems: ‘This download has been temporarily disabled. Please try again at a later time. We apologize for the inconvenience.’. Once the distribution system is back online, this error will stop occuring and download requests will succeed.

Parameters:: ip_address (Optional[List[str]], optional) – Used to specify multiple IP address, defaults to None
Returns:: Rate Limit stats
Return type:: ApiResponse

scene_list_add(list_id: str, dataset_name: str, id_field: Literal['entityId', 'displayId'] | None = 'entityId', entity_id: str | None = None, entity_ids: List[str] | None = None, ttl: str | None = None, check_download_restriction: bool | None = None) → None

Adds items in the given scene list.

Parameters:

list_id (str) – User defined name for the list
dataset_name (str) – Dataset alias
id_field (Optional[str], optional) – Used to determine which ID is being used, defaults to entityId
entity_id (Optional[str], optional) – Scene Identifier, defaults to None
entity_ids (Optional[List[str]], optional) – A list of Scene Identifiers, defaults to None
ttl (Optional[str], optional) – User defined lifetime using ISO-8601 formatted duration (such as “P1M”) for the list, defaults to None
check_download_restriction (Optional[bool], optional) – Optional parameter to check download restricted access and availability, defaults to None

Raises:

HTTPError –
RuntimeError – If number of added items does not equal 1 or len(entity_ids), a RunTimeError is raised

Example:

Api.scene_list_add(: list_id=”my_scene_list”, dataset_name=”landsat_ot_c2_l2”, id_field=”displayId”, entity_id=”LC08_L2SP_012025_20201231_20210308_02_T1”

)

scene_list_get(list_id: str, dataset_name: str | None = None, starting_number: int | None = None, max_results: int | None = None) → ApiResponse

Returns items in the given scene list.

Note

starting_number is 1-indexed

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
max_results (Optional[int], optional) – How many results should be returned?, defaults to None

Returns:

List of items in requested scene list. Each entry is a dictionary in the form of {‘entityId’, ‘datasetName’}.

Return type:

Raises:

HTTPError –

Example:

Api.scene_list_get(list_id=”my_scene_list”)

scene_list_remove(list_id: str, dataset_name: str | None = None, entity_id: str | None = None, entity_ids: List[str] | None = None) → None

Removes items from the given list. If no datasetName is provided, the call removes the whole list. If a datasetName is provided but no entityId, this call removes that dataset with all its IDs. If a datasetName and entityId(s) are provided, the call removes the ID(s) from the dataset.

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None
entity_id (Optional[str], optional) – Scene Identifier, defaults to None
entity_ids (Optional[List[str]], optional) – A list of Scene Identifiers, defaults to None

Raises:

HTTPError –

Example:

Api.scene_list_remove(: list_id=”my_scene_list”, dataset_name=”landsat_ot_c2_l2”, entity_id=”LC80120252020366LGN00”

)

scene_list_summary(list_id: str, dataset_name: str | None = None) → ApiResponse

Returns summary information for a given list.

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None

Returns:

Dictionary containing a summary and datasets ({‘summary’, ‘datasets’}).

Return type:

Raises:

HTTPError –

scene_list_types(list_filter: str | None) → ApiResponse

Returns scene list types (exclude, search, order, bulk, etc).

Parameters:: list_filter (Optional[str]) – If provided, only returns listIds that have the provided filter value within the ID
Returns:: List of scene list, each containing a dictionary describing a scene list.
Return type:: ApiResponse

scene_metadata(dataset_name: str, entity_id: str, id_type: str | None = 'entityId', metadata_type: str | None = None, include_null_metadata: bool | None = None, use_customization: bool | None = None) → ApiResponse

This request is used to return metadata for a given scene.

Note

The parameter entity_id is named confusingly. Depending on id_type, passing one of entityId, displayId or orderingId is allowed

Parameters:

dataset_name (str) – Used to identify the dataset to search
entity_id (str) – Used to identify the scene to return results for
id_type (Optional[str], optional) – If populated, identifies which ID field (entityId, displayId or orderingId) to use when searching for the provided entityId, defaults to “entityId”
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary, full, fgdc, iso), defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to display metadata view as per user customization, defaults to None

Returns:

Dict containing scene metadata

Return type:

Raises:

HTTPError –

scene_metadata_list(list_id: str, dataset_name: str | None = None, metadata_type: str | None = None, include_null_metadata: bool | None = None, use_customization: bool | None = None) → ApiResponse

Scene Metadata where the input is a pre-set list.

Parameters:

list_id (str) – Used to identify the list of scenes to use
dataset_name (Optional[str], optional) – Used to identify the dataset to search, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to display metadata view as per user customization, defaults to None

Returns:

Dict containing metadata for requested list

Return type:

scene_metadata_xml(dataset_name: str, entity_id: str, metadata_type: str | None = None) → ApiResponse

Returns metadata formatted in XML, ahering to FGDC, ISO and EE scene metadata formatting standards.

Note

It’s unclear if entity_id refers exclucively to the entityId or if other kinds of Ids can be passed as well.

Parameters:

dataset_name (str) – Used to identify the dataset to search
entity_id (str) – Used to identify the scene to return results for
metadata_type (Optional[str], optional) – Used to identify the scene to return results for, defaults to None

Returns:

Returns dictionary with metadata for requested scene. The XML content is available with the key ‘exportContent’

Return type:

Raises:

HTTPError –

scene_search(dataset_name: str, max_results: int = 100, starting_number: int | None = None, metadata_type: str | None = None, sort_field: str | None = None, sort_direction: Literal['ASC', 'DESC'] | None = None, sort_customization: SortCustomization | None = None, use_customization: bool | None = None, scene_filter: SceneFilter | None = None, compare_list_name: str | None = None, bulk_list_name: str | None = None, order_list_name: str | None = None, exclude_list_name: str | None = None, include_null_metadata: bool | None = None) → ApiResponse

Searching is done with limited search criteria. All coordinates are assumed decimal-degree format. If lowerLeft or upperRight are supplied, then both must exist in the request to complete the bounding box. Starting and ending dates, if supplied, are used as a range to search data based on acquisition dates. The current implementation will only search at the date level, discarding any time information. If data in a given dataset is composite data, or data acquired over multiple days, a search will be done to match any intersection of the acquisition range. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter timeouts for large result sets for some datasets. To use the sceneFilter field, pass one of the four search filter objects (SearchFilterAnd, SearchFilterBetween, SearchFilterOr, SearchFilterValue) in JSON format with sceneFilter being the root element of the object.

Searches without a ‘sceneFilter’ parameter can take much longer to execute. To minimize this impact we use a cached scene count for ‘totalHits’ instead of computing the actual row count. An additional field, ‘totalHitsAccuracy’, is also included in the response to indicate if the ‘totalHits’ value was computed based off the query or using an approximated value. This does not impact the users ability to access these results via pagination. This cached value is updated daily for all datasets with active data ingests. Ingest frequency for each dataset can be found using the ‘ingestFrequency’ field in the dataset, dataset-categories and dataset-search endpoint responses.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

dataset_name (str) – Used to identify the dataset to search. Can be datasetAlias.
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
sort_field (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Determines how the results should be sorted, defaults to None
sort_customization (Optional[SortCustomization], optional) – Used to pass in custom sorts, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to indicate whether to use customization, defaults to None
scene_filter (Optional[SceneFilter], optional) – Used to filter data within the dataset, defaults to None
compare_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for comparison, defaults to None
bulk_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for bulk ordering, defaults to None
order_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for on-demand ordering, defaults to None
exclude_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to exclude scenes from the results, defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None

Raises:

HTTPError –

Returns:

Dictionary containing search results as List[Dict] together with some additional search meatadata ([‘recordsReturned’, ‘totalHits’, ‘totalHitsAccuracy’, ‘isCustomized’, ‘numExcluded’, ‘startingNumber’, ‘nextRecord’])

Return type:

Example:

# General search Api.scene_search( “gls_all”, max_results=500, scene_filter=SceneFilter(AcquisitionFilter(…), CloudCoverFilter(…), …), bulk_list_name=”my_bulk_list”, metadata_type=”summary”, order_list_name=”my_order_list”, starting_number=1, compare_list_name=”my_comparison_list”, exlucde_list_name=”my_exclude_list” )

# Search with spatial filter and ingest filter

# Search with acquisition filter

# Search with metadata filter (metadata filter ids can be retrieved by calling dataset-filters)

# Sort search results using useCustomization flag and sortCustomization

scene_search_delete(dataset_name: str, max_results: int = 100, starting_number: int | None = None, sort_field: str | None = None, sort_direction: Literal['ASC', 'DEC'] | None = None, temporal_filter: TemporalFilter | None = None) → ApiResponse

This method is used to detect deleted scenes from datasets that support it. Supported datasets are determined by the ‘supportDeletionSearch’ parameter in the ‘datasets’ response. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter timeouts for large result sets for some datasets.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

dataset_name (str) – Used to identify the dataset to search
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
sort_field (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DEC"]], optional) – Determines how the results should be sorted, defaults to None
temporal_filter (Optional[TemporalFilter], optional) – Used to filter data based on data acquisition, defaults to None

Returns:

Dictionary containing search results as List[Dict] together with some additional search meatadata

Return type:

Raises:

HTTPError –

scene_search_secondary(entity_id: str, dataset_name: str, max_results: int = 100, starting_number: int | None = None, metadata_type: str | None = None, sort_filed: str | None = None, sort_direction: Literal['ASC', 'DESC'] | None = None, compare_list_name: str | None = None, bulk_list_name: str | None = None, order_list_name: str | None = None, exlucde_list_name: str | None = None) → ApiResponse

This method is used to find the related scenes for a given scene.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

entity_id (str) – Used to identify the scene to find related scenes for
dataset_name (str) – Used to identify the dataset to search
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
sort_filed (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Determines how the results should be sorted, defaults to None
compare_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for comparison, defaults to None
bulk_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for bulk ordering, defaults to None
order_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for on-demand ordering, defaults to None
exlucde_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to exclude scenes from the results, defaults to None

Returns:

Dictionary containing search results for related scenes as List[Dict] together with some additional search meatadata

Return type:

Raises:

HTTPError –

tram_order_detail_update(order_number: str, detail_key: str, detail_value: str) → ApiResponse

This method is used to set metadata for an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_number (str) – The order ID for the order to update
detail_key (str) – The system detail key
detail_value (str) – The value to store under the detailKey

Returns:

Updated key-value pair

Return type:

tram_order_details(order_number: str) → ApiResponse

This method is used to view the metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get details for
Returns:: Metadata for order as dictionary
Return type:: ApiResponse

tram_order_details_clear(order_number: str) → ApiResponse

This method is used to clear all metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to clear details for
Returns:: Data section is Null
Return type:: ApiResponse

tram_order_details_remove(order_number: str, detail_key: str) → ApiResponse

This method is used to remove the metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_number (str) – The order ID to clear details for
detail_key (str) – The system detail key

Returns:

Previous value of deleted key

Return type:

Search TRAM orders.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_id (Optional[str], optional) – The order ID to get status for (accepts ‘%’ wildcard), defaults to None
max_results (Optional[int], optional) – How many results should be returned on each page?, defaults to 25
system_id (Optional[str], optional) – Limit results based on the application that order was submitted from, defaults to None
sort_asc (Optional[bool], optional) – True for ascending results, false for descending results, defaults to None
sort_field (Optional[Literal["order_id", "date_entered", "date_updated"]], optional) – Which field should sorting be done on?, defaults to None
status_filter (Optional[List[str]], optional) – An array of status codes to…, defaults to None

Returns:

List of order information

Return type:

tram_order_status(order_number: str) → ApiResponse

Gets the status of a TRAM order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get status for
Returns:: Status for requested order
Return type:: ApiResponse

tram_order_units(order_number: str) → ApiResponse

Lists units for a specified order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get units for
Returns:: List of TRAM units
Return type:: ApiResponse

user_preferences_get(system_id: str | None = None, setting: List[str] | None = None) → ApiResponse

This method is used to retrieve user’s preference settings.

Parameters:

system_id (Optional[str], optional) – Used to identify which system to return preferences for. If null it will return all the users preferences, defaults to None
setting (Optional[List[str]], optional) – If populated, identifies which setting(s) to return, defaults to None

Returns:

Dict containing, possibly subset, preferences of calling user

Return type:

Raises:

HTTPError –

user_preferences_set(system_id: str | None = None, user_preferences: Dict[str, str] | None = None) → None

This method is used to create or update user’s preferences.

Parameters:

system_id (Optional[str], optional) – Used to identify which system the preferences are for, defaults to None
user_preferences (Optional[Dict[str]], optional) – Used to set user preferences for various systems, defaults to None

Raises:

HTTPError –

Example:

preferences = {

“userPreferences”: {

“map”: {: “lat”: “43.53”, “lng”: “-96.73”, “showZoom”: false, “showMouse”: true, “zoomLevel”: “7”, “defaultBasemap”: “OpenStreetMap”

}, “browse”: {

“browseSize”: “10”, “selectedOpacity”: “100”, “nonSelectedOpacity”: “100”

}, “general”: {

“defaultDataset”: “gls_all”, “codiscoveryEnabled”: false

}

Api.user_preferences_set(“EE”, preferences)

callusgs.errors module

Implementation of USGS’s machine-to-machine API exception codes: https://m2m.cr.usgs.gov/api/docs/exceptioncodes/

exception callusgs.errors.AuthenticationEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.DownloadEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

class callusgs.errors.ErrorCodes

Bases: object

KNOWN_ERROR_CODES: Dict[str, Dict[str, str | Callable]] = {'AUTH_INVALID': {'cls': <class 'callusgs.errors.AuthenticationEarthExplorerException'>, 'msg': 'User credential verification failed'}, 'AUTH_KEY_INVALID': {'cls': <class 'callusgs.errors.AuthenticationEarthExplorerException'>, 'msg': 'Invalid API Key'}, 'AUTH_UNAUTHORIZED': {'cls': <class 'callusgs.errors.AuthenticationEarthExplorerException'>, 'msg': 'User account does not have access to the requested endpoint'}, 'DATASET_AUTH': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Dataset is not available for the user - full details in error message'}, 'DATASET_CUSTOMS_GET_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to get dataset customizations'}, 'DATASET_CUSTOMS_SET_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to create or update dataset customization'}, 'DATASET_CUSTOM_CLEAR_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to clear dataset customization'}, 'DATASET_CUSTOM_GET_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to get dataset customization'}, 'DATASET_CUSTOM_SET_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to create or update dataset customization'}, 'DATASET_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'This dataset does not support - full details in error message'}, 'DATASET_INVALID': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Invalid dataset used'}, 'DATASET_UNAUTHORIZED': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Dataset is not available for the user - full details in error message'}, 'DOWNLOAD_ERROR': {'cls': <class 'callusgs.errors.DownloadEarthExplorerException'>, 'msg': 'Download does not belong to the user'}, 'ENDPOINT_UNAVAILABLE': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'This endpoint is not available to the requested version'}, 'EXPORT_ERROR': {'cls': <class 'callusgs.errors.ExportEarthExplorerException'>, 'msg': 'Unable to create metadata export'}, 'INPUT_FORMAT': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'JSON payload could not be parsed as valid JSON'}, 'INPUT_INVALID': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'Invalid parameters used - full details in error message'}, 'INPUT_PARAMETER_INVALID': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'Invalid parameters used - full details in error message'}, 'INPUT_PARAMETER_REQUIRED': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'A parameter is required and was not supplied'}, 'NOT_FOUND': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': "Couldn't find the input - full details in error message"}, 'ORDER_AUTH': {'cls': <class 'callusgs.errors.OrderEarthExplorerException'>, 'msg': 'Order does not belong to the user'}, 'ORDER_ERROR': {'cls': <class 'callusgs.errors.OrderEarthExplorerException'>, 'msg': 'An order related error occurred - full details in error message'}, 'ORDER_INVALID': {'cls': <class 'callusgs.errors.OrderEarthExplorerException'>, 'msg': 'Invalid order given'}, 'RATE_LIMIT': {'cls': <class 'callusgs.errors.RateLimitEarthExplorerException'>, 'msg': 'User attempted to run multiple requests at a time'}, 'RATE_LIMIT_USER_DL': {'cls': <class 'callusgs.errors.RateLimitEarthExplorerException'>, 'msg': 'User has reached download-related rate limits'}, 'RESTORE_ORDER_ERROR': {'cls': <class 'callusgs.errors.OrderEarthExplorerException'>, 'msg': 'Unable to restore order units - full details in error message'}, 'SEARCH_CREATE_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to create search records or unable to auto-execute the search request'}, 'SEARCH_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to execute search request'}, 'SEARCH_EXECUTE_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to execute search request'}, 'SEARCH_FAILED': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Search failed'}, 'SEARCH_RESULT_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to translate results into response format'}, 'SEARCH_UNAVAILABLE': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Search has not been completed'}, 'SEARCH_UPDATE_ERROR': {'cls': <class 'callusgs.errors.InventoryEarthExplorerException'>, 'msg': 'Unable to update the search - full details in the error message'}, 'SERVER_ERROR': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'API not configured to handle the request - full details in error message'}, 'SUBSCRIPTION_ERROR': {'cls': <class 'callusgs.errors.SubscriptionEarthExplorerException'>, 'msg': 'Subscription creation failed'}, 'UNKNOWN': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'An unknown error occurred - full details in developer log'}, 'VERSION_UNKNOWN': {'cls': <class 'callusgs.errors.GeneralEarthExplorerException'>, 'msg': 'Unknown version used'}}

exception callusgs.errors.ExportEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.GeneralEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.InventoryEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.OrderEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.RateLimitEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

exception callusgs.errors.SubscriptionEarthExplorerException

Bases: Exception

Errors, that fall into the ‘General’ module

callusgs.types module

Implementation of USGS’s machine-to-machine API data types: https://m2m.cr.usgs.gov/api/docs/datatypes/

class callusgs.types.AcquisitionFilter(start: str, end: str): Bases: EarthExplorerBaseType

Bases: object

Custom data type to represent Api response objects.

raise_status() → None

class callusgs.types.Browse(browse_rotation_enabled: bool, browse_name: str, browse_path: str, overlay_path: str, overlay_type: str, thumbnail_path: str): Bases: EarthExplorerBaseType

class callusgs.types.CloudCoverFilter(_min: int, _max: int, include_unknown: bool): Bases: EarthExplorerBaseType

class callusgs.types.Coordinate(latitude: float, longitude: float): Bases: EarthExplorerBaseType

class callusgs.types.Dataset(abstract_text: str, acquisition_start: str, acquisition_end: str, catalogs: List[str], collection_name: str, collection_long_name: str, dataset_id: str, dataset_alias: str, dataset_category_name: str, data_owner: str, date_updated: str, doi_number: str, ingest_frequency: str, keywords: str, scene_count: int, spatial_bounds: SpatialBounds, temporal_coverage: TemporalCoverage, support_cloud_cover: bool, support_deletion_search: bool): Bases: EarthExplorerBaseType

class callusgs.types.DatasetCategory(_id: int, category_name: str, category_description: str, parent_category_id: int, parent_category_name: str, reference_link: str): Bases: EarthExplorerBaseType

class callusgs.types.DatasetCustomization(dataset_name: str, excluded: bool, metadata: InventoryMetadata, search_sort: SearchSort, file_groups: FileGroups): Bases: EarthExplorerBaseType

class callusgs.types.DatasetFilter(_id: int, legacy_field_id: int, dictionary_link: str, field_config: FieldConfig, field_label: str, search_sql: str): Bases: EarthExplorerBaseType

class callusgs.types.DateRange(start_date: str, end_date: str): Bases: EarthExplorerBaseType

class callusgs.types.DownloadInput(entity_id: str, product_id: str, data_use: str, label: str): Bases: EarthExplorerBaseType

class callusgs.types.DownloadQueueDownload(download_id: int, collection_name: str, dataset_id: str, display_id: str, entity_id: str, eula_code: str | None, file_size: int, label: str, product_code: str, product_name: str, status_code: str, status_text: str): Bases: EarthExplorerBaseType

class callusgs.types.DownloadResponse(_id: int, display_id: str, entity_id: str, dataset_id: str, available: str, file_size: int, product_name: str, product_code: str, bulk_available: str, download_system: str, secondary_downloads: DownloadResponse): Bases: EarthExplorerBaseType

class callusgs.types.EarthExplorerBaseType

Bases: object

json() → str

class callusgs.types.Eula(eula_code: str | None, agreement_content: str | None): Bases: EarthExplorerBaseType

class callusgs.types.FieldConfig(type: str, filters: List[Any], validators: List[Any], display_list_id: str): Bases: EarthExplorerBaseType

class callusgs.types.FileGroups(file_group_id: str, product_ids: List[str]): Bases: EarthExplorerBaseType

class callusgs.types.FilegroupDownload(dataset_name: str, file_groups: List[str], list_id: str, data_use: str, label: str): Bases: EarthExplorerBaseType

class callusgs.types.FilepathDownload(dataset_name: str, product_code: str, data_path: str, data_use: str, label: str): Bases: EarthExplorerBaseType

class callusgs.types.GeoJson(type: str, coordinates: List[float] | List[List[List[float]]]): Bases: EarthExplorerBaseType

class callusgs.types.IngestFilter(start: str, end: str): Bases: EarthExplorerBaseType

class callusgs.types.IngestSubscription(subscription_id: int, subscription_name: str, username: str, catalog_id: str, datasets: str, run_options: RunOptions, run_start_date: str, run_end_date: str, request_app: str, request_app_reference_id: str, run_frequency: str, status: str, date_entered: str, last_run_date: str, last_attempty_date: str): Bases: EarthExplorerBaseType

class callusgs.types.IngestSubscriptionLog(run_id: int, subscription_id: int, run_date: str, execution_time: str, num_scenes_matched: str, result_code: str, run_script_output: str, run_summary: str, run_options: RunOptions, datasets: str, catalog_id: str, last_run_date: str, order_ids: str, bulld_ids: str): Bases: EarthExplorerBaseType

class callusgs.types.IngestUpdateTemplate(template_id: str, dar_id: str, scene_ids: List[str], view_name: str, id_field: str = 'EE_DISPLAY_ID'): Bases: EarthExplorerBaseType

class callusgs.types.InventoryMetadata(metadata_type: str, _id: str, sort_order: int): Bases: EarthExplorerBaseType

class callusgs.types.Metadata

This is an abstract data model, use MetadataAnd, MetadataBetween, MetadataOr, or MetadataValue

class callusgs.types.MetadataAnd(child_filters: List[MetadataFilter | Metadata]): Bases: EarthExplorerBaseType

class callusgs.types.MetadataBetween(filter_id: str, first_value: int, second_value: int): Bases: EarthExplorerBaseType

class callusgs.types.MetadataExport(export_id: str, export_name: str, dataset_id: str, dataset_name: str, scene_filter: SceneFilter, custom_message: str, export_type: str, status: str, status_name: str, date_entered: str, date_updated: str): Bases: EarthExplorerBaseType

class callusgs.types.MetadataField(_id: int, field_name: str, dictionary_link: str, value: str): Bases: EarthExplorerBaseType

class callusgs.types.MetadataFilter

This is an abstract data model, use MetadataAnd, MetadataBetween, MetadataOr, or MetadataValue

class callusgs.types.MetadataOr(child_filters: List[MetadataFilter | Metadata]): Bases: EarthExplorerBaseType

class callusgs.types.MetadataValue(filter_type: str, filter_id: str, value: str, operand: str): Bases: EarthExplorerBaseType

class callusgs.types.Notifaction(_id: int, subject: str, message_content: str, severity_code: str, severity_css_class: str, severity_text: str, date_updated: str): Bases: EarthExplorerBaseType

class callusgs.types.Options(bulk: bool, order: bool, download: bool, secondary: bool): Bases: EarthExplorerBaseType

class callusgs.types.ProductDownload(dataset_name: str, product_ids: List[str], scene_filter: SceneFilter): Bases: EarthExplorerBaseType

class callusgs.types.ProductInput(dataset_name: str, entity_id: str, product_id: str, product_code: str): Bases: EarthExplorerBaseType

class callusgs.types.ProductResponse(_id: int, entity_id: str, dataset_id: str, available: str, price: float, product_name: str, product_code: str): Bases: EarthExplorerBaseType

class callusgs.types.ProxiedDownload(download_id: int, downloaded_size: int): Bases: EarthExplorerBaseType

class callusgs.types.RunOptions(result_formats: List[str]): Bases: EarthExplorerBaseType

class callusgs.types.Scene(browse: List[Browse], cloud_cover: str, entity_id: str, display_id: str, metadata: List[MetadataField], options: Options, selected: Selected, spatial_bounds: SpatialBounds, spatial_coverage: SpatialBounds, temporal_coverage: TemporalCoverage, publish_date: str): Bases: EarthExplorerBaseType

class callusgs.types.SceneDatasetFilter(dataset_name: str, scene_filter: List[SceneFilter]): Bases: EarthExplorerBaseType

class callusgs.types.SceneFilter(acquisition_filter: AcquisitionFilter | None = None, cloudcover_filter: CloudCoverFilter | None = None, dataset_name: str | None = None, ingest_filter: IngestFilter | None = None, metadata_filter: MetadataFilter | None = None, seasonal_filter: List[int] | None = None, spatial_filter: SpatialFilter | None = None): Bases: EarthExplorerBaseType

class callusgs.types.SceneMetadataConfig(include_nulls: bool, type: str, template: str): Bases: EarthExplorerBaseType

class callusgs.types.SearchSort(_id: str, direction: str): Bases: EarthExplorerBaseType

class callusgs.types.Selected(bulk: bool, order: bool, compare: bool): Bases: EarthExplorerBaseType

class callusgs.types.SortCustomization(filed_name: str, direction: str): Bases: EarthExplorerBaseType

class callusgs.types.SpatialBounds

This is an abstract data model, use spatialBoundsMbr or geoJson

class callusgs.types.SpatialBoundsMbr(north: str, east: str, south: str, west: str): Bases: EarthExplorerBaseType

class callusgs.types.SpatialFilter

This is an abstract data model, use SpatialFilterMbr or SpatialFilterGeoJson

class callusgs.types.SpatialFilterGeoJson(geo_json: GeoJson): Bases: EarthExplorerBaseType

class callusgs.types.SpatialFilterMbr(lower_left: Coordinate, upper_right: Coordinate): Bases: EarthExplorerBaseType

class callusgs.types.SubscriptionDataset(dataset_name: str): Bases: EarthExplorerBaseType

class callusgs.types.TemplateConfiguration

This is an abstract data model, use ingestUpdateTemplate

class callusgs.types.TemporalCoverage(start_date: str, end_date: str): Bases: EarthExplorerBaseType

class callusgs.types.TemporalFilter(start: str, end: str): Bases: EarthExplorerBaseType

class callusgs.types.TramOrder(order_id: int, username: str, processing_priority: int, order_comment: str, status_code: str, status_code_text: str, date_entered: str, last_updated_date: str): Bases: EarthExplorerBaseType

class callusgs.types.TramUnit(unit_number: int, product_code: str, product_name: str, dataset_id: str, dataset_name: str, collection_name: str, ordering_id: str, unit_price: str, unit_comment: str, status_code: str, status_code_text: str, last_updated_date: str): Bases: EarthExplorerBaseType

class callusgs.types.UserContext(contact_id: str, ip_address: str): Bases: EarthExplorerBaseType

Module contents

class callusgs.Api(relogin: bool = True, method: str | None = 'token', user: str | None = None, auth: str | None = None)

Bases: object

DATA_SECTION: str = 'Value of data section is not 1'

ENDPOINT: str = 'https://m2m.cr.usgs.gov/api/api/json/stable/'

data_owner(data_owner: str) → ApiResponse

This method is used to provide the contact information of the data owner.

Parameters:: data_owner (str) – Used to identify the data owner - this value comes from the dataset-search response
Returns:: Dict containing contact information
Return type:: ApiResponse

dataset(dataset_id: str | None = None, dataset_name: str | None = None) → ApiResponse

This method is used to retrieve the dataset by id or name.

Note

Input datasetId or datasetName and get dataset description (including the respective other part).

Warning

Either dataset_id or dataset_name must be given!

Parameters:

dataset_id (Optional[str], optional) – The dataset identifier, defaults to None
dataset_name (Optional[str], optional) – The system-friendly dataset name, defaults to None

Raises:

AttributeError –

Returns:

Dict containing dataset information

Return type:

dataset_browse(dataset_id: str) → ApiResponse

This request is used to return the browse configurations for the specified dataset.

Parameters:: dataset_id (str) – Determines which dataset to return browse configurations for
Returns:: List of Dicts, each containing information about configuration of subdatasets
Return type:: ApiResponse

dataset_bulk_products(dataset_name: str | None = None) → ApiResponse

Lists all available bulk products for a dataset - this does not guarantee scene availability.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (Optional[str], optional) – Used to identify the which dataset to return results for, defaults to None
Returns:: List of dictionaries containing bulk download information
Return type:: ApiResponse

dataset_catalogs() → ApiResponse

This method is used to retrieve the available dataset catalogs. The use of dataset catalogs are not required, but are used to group datasets by their use within our web applications.

Returns:: Dictionary with all available data catalogs
Return type:: ApiResponse

This method is used to search datasets under the categories.

Parameters:

catalog (Optional[str], optional) – Used to identify datasets that are associated with a given application, defaults to None
include_message (Optional[bool], optional) – Optional parameter to include messages regarding specific dataset components, defaults to None
public_only (Optional[bool], optional) – Used as a filter out datasets that are not accessible to unauthenticated general public users, defaults to None
use_customization (Optional[bool], optional) – Used as a filter out datasets that are excluded by user customization, defaults to None
parent_id (Optional[str], optional) – If provided, returned categories are limited to categories that are children of the provided ID, defaults to None
dataset_filter (Optional[str], optional) – If provided, filters the datasets - this automatically adds a wildcard before and after the input value, defaults to None

Returns:

Dict containing all datasets within a catalog

Return type:

dataset_clear_customization(dataset_name: str | None = None, metadata_type: List[str] | None = None, file_group_ids: List[str] | None = None) → None

This method is used the remove an entire customization or clear out a specific metadata type.

Parameters:

dataset_name (Optional[str], optional) – Used to identify the dataset to clear. If null, all dataset customizations will be cleared., defaults to None
metadata_type (Optional[List[str]], optional) – If populated, identifies which metadata to clear(export, full, res_sum, shp), defaults to None
file_group_ids (Optional[List[str]], optional) – If populated, identifies which file group to clear, defaults to None

Raises:

dataset_coverage(dataset_name: str) → ApiResponse

Returns coverage for a given dataset.

Parameters:: dataset_name (str) – Determines which dataset to return coverage for
Returns:: Bounding box and GeoJSON coverage
Return type:: ApiResponse

dataset_download_options(dataset_name: str, scene_filter: SceneFilter | None = None) → ApiResponse

This request lists all available products for a given dataset.

Warning

Product listed here does not guarantee scene availability!

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Used to identify the which dataset to return results for
scene_filter (Optional[SceneFilter], optional) – Used to filter data within the dataset, defaults to None

Returns:

List of available products

Return type:

dataset_file_groups(dataset_name: str) → ApiResponse

This method is used to list all configured file groups for a dataset.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (str) – Dataset alias
Returns:: Primary and secondary file group information
Return type:: ApiResponse

dataset_filters(dataset_name: str) → ApiResponse

This request is used to return the metadata filter fields for the specified dataset. These values can be used as additional criteria when submitting search and hit queries.

Parameters:: dataset_name (str) – Determines which dataset to return filters for
Returns:: Dict with all related dataset fiters
Return type:: ApiResponse

dataset_get_customization(dataset_name: str) → ApiResponse

This method is used to retrieve metadata customization for a specific dataset.

Parameters:: dataset_name (str) – Used to identify the dataset to search
Returns:: Dict containing customized metadata representations
Return type:: ApiResponse

dataset_get_customizations(dataset_names: ~typing.List[str] | None = None, metadata_type: ~typing.List[str] | None = <class 'str'>) → ApiResponse

This method is used to retrieve metadata customizations for multiple datasets at once.

Parameters:

dataset_names (Optional[List[str]], optional) – Used to identify the dataset(s) to return. If null it will return all the users customizations, defaults to None
metadata_type (Optional[List[str]], optional) – If populated, identifies which metadata to return(export, full, res_sum, shp), defaults to str

Returns:

Dict containing customized metadata representations for datasets, identified by their Ids

Return type:

dataset_messages(catalog: str, dataset_name: str | None = None, dataset_names: List[str] | None = None) → ApiResponse

Returns any notices regarding the given datasets features.

Parameters:

catalog (str) – Used to identify datasets that are associated with a given application
dataset_name (Optional[str], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None
dataset_names (Optional[List[str]], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None

Returns:

Dict containing notices per dataset supplied

Return type:

dataset_metadata(dataset_name: str) → ApiResponse

This method is used to retrieve all metadata fields for a given dataset.

Parameters:: dataset_name (str) – The system-friendly dataset name
Returns:: All metadata for given dataset
Return type:: ApiResponse

dataset_order_products(dataset_name: str) → ApiResponse

Lists all available order products for a dataset.

Warning

Product listed here does not guarantee scene availability!

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: dataset_name (str) – Used to identify the which dataset to return results for
Returns:: List of all products available for given dataset name
Return type:: ApiResponse
Example:

Api.dataset_order_products(“landsat_ot_c2_l2”)

# [ # { # “productCode”: “LO220”, # “productName”: “L8-9 Collection 2 Level 1 and Level 2 Std Products from Level 0 input” # }, # { # “productCode”: “LO221”, # “productName”: “L8-9 Collection 2 Level 2 Std product from Level 1 input” # }, # …, # ]

This method is used to find datasets available for searching. By passing only API Key, all available datasets are returned. Additional parameters such as temporal range and spatial bounding box can be used to find datasets that provide more specific data. The dataset name parameter can be used to limit the results based on matching the supplied value against the public dataset name with assumed wildcards at the beginning and end.

Note

Can be used to transfrom “natural language description” to datasetId and/or dataset_alias.

Warning

SpatialFilter is an abstract class. SpatialFilterMbr or SpatialFilterGeoJson must be supplied.

Parameters:

catalog (Optional[str], optional) – Used to identify datasets that are associated with a given application, defaults to None
category_id (Optional[str], optional) – Used to restrict results to a specific category (does not search sub-sategories), defaults to None
dataset_name (Optional[str], optional) – Used as a filter with wildcards inserted at the beginning and the end of the supplied value, defaults to None
include_messages (Optional[bool], optional) – Optional parameter to include messages regarding specific dataset components, defaults to None
public_only (Optional[bool], optional) – Used as a filter out datasets that are not accessible to unauthenticated general public users, defaults to None
include_unknown_spatial (Optional[bool], optional) – Optional parameter to include datasets that do not support geographic searching, defaults to None
temporal_filter (Optional[TemporalFilter], optional) – Used to filter data based on data acquisition, defaults to None
spatial_filter (Optional[SpatialFilter], optional) – Used to filter data based on data location, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Defined the sorting as Ascending (ASC) or Descending (DESC), defaults to “ASC”
sort_field (Optional[str], optional) – Identifies which field should be used to sort datasets (shortName - default, longName, dastasetName, GloVis), defaults to None
use_customization (Optional[bool], optional) – Optional parameter to indicate whether to use customization, defaults to None

Returns:

Get dataset descriptions and attributes

Return type:

Example:

Api().dataset_search(“EE”, “dataset_name=”Collection 2 Level-1”)

dataset_set_customization(dataset_name: str, excluded: bool | None = None, metadata: Metadata | None = None, search_sort: SearchSort | None = None, file_groups: FileGroups | None = None) → None

This method is used to create or update dataset customizations for a given dataset.

Warning

Metadata is an abstract class. Instead use a combination of MetadataAnd, MetadataBetween, MetadataOr and MetadataValue.

Parameters:

dataset_name (str) – Used to identify the dataset to search
excluded (Optional[bool], optional) – Used to exclude the dataset, defaults to None
metadata (Optional[Metadata], optional) – Used to customize the metadata layout, defaults to None
search_sort (Optional[SearchSort], optional) – Used to sort the dataset results, defaults to None
file_groups (Optional[FileGroups], optional) – Used to customize downloads by file groups, defaults to None

Raises:

dataset_set_customizations(dataset_customization: DatasetCustomization) → None

This method is used to create or update customizations for multiple datasets at once.

Parameters:: dataset_customization (DatasetCustomization) – Used to create or update a dataset customization for multiple datasets
Raises:: GeneralEarthExplorerException –

download(url: str, output_directory: Path | None = PosixPath('.'), chunk_size: int = 1024, no_progess: bool | None = False) → None

download_complete_proxied(proxied_downloads: List[ProxiedDownload]) → ApiResponse

Updates status to ‘C’ with total downloaded file size for completed proxied downloads.

Parameters:: proxied_downloads (List[ProxiedDownload]) – Used to specify multiple proxied downloads
Returns:: Dict containing number of failed downloads and number of statuses updated
Return type:: ApiResponse

download_eula(eula_code: str | None = None, eula_codes: List[str] | None = None) → ApiResponse

Gets the contents of a EULA from the eulaCodes.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

eula_code (Optional[str], optional) – Used to specify a single eula, defaults to None
eula_codes (Optional[List[str]], optional) – Used to specify multiple eulas, defaults to None

Returns:

List of EULAs

Return type:

download_labels(download_application: str | None = None) → ApiResponse

Gets a list of unique download labels associated with the orders.

Parameters:: download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
Returns:: Information about all valid(?) download orders [‘label’, ‘dateEntered’, ‘downloadSize’, ‘downloadCount’, ‘totalComplete’]
Return type:: ApiResponse

download_options(dataset_name: str, entity_ids: str | List[str] | None = None, list_id: str | None = None, include_secondary_file_groups: bool | None = None) → ApiResponse

The download options request is used to discover downloadable products for each dataset. If a download is marked as not available, an order must be placed to generate that product.

Note

“listId” is the id of the customized list which is built by scene-list-add. The parameter entityIds can be either a string array or a string. If passing them in a string, separate them by comma (no space between the IDs). If passing them in the test page, use string without quotes/spaces/brackets, just pass entityIds with commas, for example, LT50290302005219EDC00,LE70820552011359EDC00

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Dataset alias
entity_ids (Optional[Union[str, List[str]]], optional) – List of scenes, defaults to None
list_id (Optional[str], optional) – Used to identify the list of scenes to use, defaults to None
include_secondary_file_groups (Optional[bool], optional) – Optional parameter to return file group IDs with secondary products, defaults to None

Returns:

List of all available download options for a given datset

Return type:

download_order_load(download_application: str | None = None, label: str | None = None) → ApiResponse

This method is used to prepare a download order for processing by moving the scenes into the queue for processing.

Note

label must be label of order.

Parameters:

download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
label (Optional[str], optional) – Determines which order to load, defaults to None

Returns:

Metadata for specified orders given by labels

Return type:

download_order_remove(label: str, download_application: str | None = None) → None

This method is used to remove an order from the download queue.

Parameters:

download_application (str) – Used to denote the application that will perform the download
label (Optional[str], optional) – Determines which order to remove, defaults to None

Raises:

download_remove(download_id: int) → None

Removes an item from the download queue.

Note

“downloadId” can be retrieved by calling download-search.

Parameters:: download_id (int) – Represents the ID of the download from within the queue
Raises:: GeneralEarthExplorerException –

download_request(configuration_code: Literal['no_data', 'test', 'order', 'order+email'] | None = None, download_application: str | None = 'M2M', downloads: List[DownloadInput] | None = None, data_paths: List[FilepathDownload] | None = None, label: str | None = None, system_id: str | None = 'M2M', data_groups: List[FilegroupDownload] | None = None) → ApiResponse

This method is used to insert the requested downloads into the download queue and returns the available download URLs.

Each ID supplied in the downloads parameter you provide will be returned in one of three elements:

availableDownloads: URLs provided in this list are immediately available; note that these URLs take you to other distribution systems that may require authentication

preparingDownloads: IDs have been accepted but the URLs are NOT YET available for use

failed: IDs were rejected; see the errorMessage field for an explanation

Other information is also provided in the response:

newRecords: Includes a downloadId for each element of the downloads parameter that was accepted and a label that applies to the whole request

duplicateProducts: Requests that duplicate previous requests by the same user; these are not re-added to the queue and are not included in newRecords

numInvalidScenes: The number of products that could not be found by ID or failed to be requested for any reason

remainingLimits: The number of remaining downloads to hit the rate limits by user and IP address

limitType: The type of the limits are counted by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

recentDownloadCount: The number of downloads requested in the past 15 minutes

pendingDownloadCount: The number of downloads in pending state before they are available for download

unattemptedDownloadCount: The number of downloads in available status but the user has not downloaded yet

Warning

This API may be online while the distribution systems are unavailable. When this occurs, you will recieve the following error when requesting products that belong to any of these systems: ‘This download has been temporarily disabled. Please try again at a later time. We apologize for the inconvenience.’. Once the distribution system is back online, this error will stop occuring and download requests will succeed.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Note

The configuration_code parameter is seemingly related to the Bulk Download System, at least when set to either “order” or “order+email”. Setting to “None” is recommended!

Parameters:

configuration_code (Optional[Literal["no_data", "test", "order", "order+email"]], optional) – Used to customize the the download routine, primarily for testing, defaults to None
download_application (Optional[str], optional) – Used to denote the application that will perform the download. Internal use only!, defaults to “M2M”
downloads (Optional[List[DownloadInput]], optional) – Used to identify higher level products that this data may be used to create, defaults to None
data_paths (Optional[List[FilepathDownload]], optional) – Used to identify products by data path, specifically for internal automation and DDS functionality, defaults to None
label (Optional[str], optional) – If this value is passed it will overide all individual download label values, defaults to None
system_id (Optional[str], optional) – Identifies the system submitting the download/order. Internal use only!, defaults to None
data_groups (Optional[List[FilegroupDownload]], optional) – Identifies the products by file groups, defaults to None

Raises:

ValueError – When download_application or system_id do not equal “M2M.

Returns:

Dict of available downloads, downloads in prepration and failed requests

Return type:

download_retrieve(download_application: str | None = None, label: str | None = None) → ApiResponse

Returns all available and previously requests but not completed downloads.

Warning

This API may be online while the distribution systems are unavailable. When this occurs, the downloads being fulfilled by those systems will not appear as available nor are they counted in the ‘queueSize’ response field.

Parameters:

download_application (Optional[str], optional) – Used to denote the application that will perform the download, defaults to None
label (Optional[str], optional) – Determines which downloads to return, defaults to None

Returns:

Dict with EULAs, List of available downloads ([‘url’, ‘label’, ‘entityId’, ‘eulaCode’, ‘filesize’ ‘datasetId’, ‘displayId’, ‘downloadId’, ‘statusCode’, ‘statusText’, ‘productCode’, ‘productName’, ‘collectionName’]), queue size and requested downloads

Return type:

download_search(active_only: bool | None = None, label: str | None = None, download_application: str | None = None) → ApiResponse

This method is used to search for downloads within the queue, regardless of status, that match the given label.

Parameters:

active_only (Optional[bool], optional) – Determines if completed, failed, cleared and proxied downloads are returned, defaults to None
label (Optional[str], optional) – Used to filter downloads by label, defaults to None
download_application (Optional[str], optional) – Used to filter downloads by the intended downloading application, defaults to None

Returns:

All download orders according to filters ([‘label’, ‘entityId’, ‘eulaCode’, ‘filesize’ ‘datasetId’, ‘displayId’, ‘downloadId’, ‘statusCode’, ‘statusText’, ‘productCode’, ‘productName’, ‘collectionName’])

Return type:

download_summary(download_application: str, label: str, send_email: bool | None) → ApiResponse

Gets a summary of all downloads, by dataset, for any matching labels.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

download_application (str) – Used to denote the application that will perform the download
label (str) – Determines which downloads to return
send_email (Optional[bool]) – If set to true, a summary email will also be sent

Returns:

Information about downloaded files

Return type:

grid2ll(grid_type: Literal['WRS1', 'WRS2'] | None = 'WRS2', response_shape: Literal['polygon', 'point'] | None = None, path: str | None = None, row: str | None = None) → ApiResponse

Used to translate between known grids and coordinates.

Parameters:

grid_type (Optional[Literal["WRS1", "WRS2"]], optional) – Which grid system is being used?, defaults to “WRS2”
response_shape (Optional[Literal["polygon", "point"]], optional) – What type of geometry should be returned - a bounding box polygon or a center point?, defaults to None
path (Optional[str], optional) – The x coordinate in the grid system, defaults to None
row (Optional[str], optional) – The y coordinate in the grid system, defaults to None

Returns:

Dict describing returned geometry

Return type:

headers: Dict[str, str]

key: str | None

login(username: str, password: str, user_context: Any = None)

Upon a successful login, an API key will be returned. This key will be active for two hours and should be destroyed upon final use of the service by calling the logout method.

Note

This request requires an HTTP POST request instead of a HTTP GET request as a security measure to prevent username and password information from being logged by firewalls, web servers, etc.

Parameters:

username (str) – ERS Username
password (str) – ERS Password
user_context (Any, optional) – Metadata describing the user the request is on behalf of, defaults to None

Raises:

HTTPError –

login_app_guest(application_token: str, user_token: str)

This endpoint assumes that the calling application has generated a single-use token to complete the authentication and return an API Key specific to that guest user. All subsequent requests should use the API Key under the ‘X-Auth-Token’ HTTP header as the Single Sign-On cookie will not authenticate those requests. The API Key will be active for two hours, which is restarted after each subsequent request, and should be destroyed upon final use of the service by calling the logout method.

The ‘appToken’ field will be used to verify the ‘Referrer’ HTTP Header to ensure the request was authentically sent from the assumed application.

Parameters:

application_token (str) – The token for the calling application
user_token (str) – The single-use token generated for this user

Raises:

HTTPError –

login_sso(user_context: UserContext = None)

This endpoint assumes that a user has an active ERS Single Sign-On Cookie in their browser or attached to this request. Authentication will be performed from the Single Sign-On Cookie and return an API Key upon successful authentication. All subsequent requests should use the API Key under the ‘X-Auth-Token’ HTTP header as the Single Sign-On cookie will not authenticate those requests. The API Key will be active for two hours, which is restarted after each subsequent request, and should be destroyed upon final use of the service by calling the logout method.

Parameters:: user_context (UserContext, optional) – Metadata describing the user the request is on behalf of, defaults to None
Raises:: NotImplementedError –

login_timestamp: datetime | None

login_token(username: str, token: str)

This login method uses ERS application tokens to allow for authentication that is not directly tied the users ERS password. Instructions for generating the application token can be found here.

Upon a successful login, an API key will be returned. This key will be active for two hours and should be destroyed upon final use of the service by calling the logout method.

Note

This request requires an HTTP POST request instead of a HTTP GET request as a security measure to prevent username and password information from being logged by firewalls, web servers, etc.

Parameters:

username (str) – ERS Username
token (str) – Application Token

Raises:

HTTPError –

logout() → None: This method is used to remove the users API key from being used in the future. :raises HTTPError:

notifications(system_id: str) → ApiResponse

Gets a notification list.

Parameters:: system_id (str) – Used to identify notifications that are associated with a given application
Returns:: List of all notifications
Return type:: ApiResponse

order_products(dataset_name: str, entity_ids: List[str] | None = None, list_id: str | None = None) → ApiResponse

Gets a list of currently selected products - paginated.

Note

“listId” is the id of the customized list which is built by scene-list-add.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

dataset_name (str) – Dataset alias
entity_ids (Optional[List[str]], optional) – List of scenes, defaults to None
list_id (Optional[str], optional) – Used to identify the list of scenes to use, defaults to None

Returns:

Information about selected products (i.e. id, price, entityId, availability, datasetId, productCode and productName)

Return type:

Submits the current product list as a TRAM order - internally calling tram-order-create.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

products (List[Product]) – Used to identify higher level products that this data may be used to create
auto_bulk_order (Optional[bool], optional) – If any products can be bulk ordered as a result of completed processing this option allows users to have orders automatically submitted, defaults to None
processing_parameters (Optional[str], optional) – Optional processing parameters to send to the processing system, defaults to None
priority (Optional[int], optional) – Processing Priority, defaults to None
order_comment (Optional[str], optional) – Optional textual identifier for the order, defaults to None
system_id (Optional[str], optional) – Identifies the system submitting the order, defaults to None

Returns:

Information about successfull (orderNumber) and failed orders

Return type:

permissions() → ApiResponse

Returns a list of user permissions for the authenticated user. This method does not accept any input.

Returns:: List of user permissions
Return type:: List[str]

placename(feature_type: Literal['US', 'World'] | None = None, name: str | None = None) → ApiResponse

Geocoder

Parameters:

feature_type (Optional[Literal["US", "World"]], optional) – Type of feature - see type hint, defaults to None
name (Optional[str], optional) – Name of the feature, defaults to None

Returns:

Return list of dictionaries for matched places. Dictionary keys are: [‘id’, ‘feature_id’, ‘placename’, ‘feature_code’, ‘country_code’, ‘latitude’, ‘longitude’, ‘feature_name’, ‘country_name’].

Return type:

Raises:

HTTPError –

rate_limit_summary(ip_address: List[str] | None = None) → ApiResponse

Returns download rate limits and how many downloads are in each status as well as how close the user is to reaching the rate limits

Three elements are provided in the response:

initialLimits: Includes the initial downloads rate limits

recentDownloadCount: The maximum number of downloads requested in the past 15 minutes

pendingDownloadCount: The maximum number of downloads in pending state before they are available for download

unattemptedDownloadCount: The maximum number of downloads in available status but the user has not downloaded yet

remainingLimits: Includes downloads that are currently remaining and count towards the rate limits. Users should be watching out for any of those numbers approaching 0 which means it is close to hitting the rate limits

limitType: The type of the limits are counted by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

recentDownloadCount: The number of downloads requested in the past 15 minutes

pendingDownloadCount: The number of downloads in pending state before they are available for download

unattemptedDownloadCount: The number of downloads in available status but the user has not downloaded yet

recentDownloadCounts: Includes the downloads count in each status for the past 15 minutes

countType: The type of the download counts are calculated by, the value is either ‘user’ or ‘ip’

username: The user name associated with the request

ipAddress: The IP address associated with the request

downloadCount: The number of downloads per status in the past 15 minutes

Warning

Users should be watching out for any of the remainingLimits numbers approaching 0 which means it is close to hitting the rate limits.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Warning

This API may be online while the distribution systems are unavailable. When this occurs, you will recieve the following error when requesting products that belong to any of these systems: ‘This download has been temporarily disabled. Please try again at a later time. We apologize for the inconvenience.’. Once the distribution system is back online, this error will stop occuring and download requests will succeed.

Parameters:: ip_address (Optional[List[str]], optional) – Used to specify multiple IP address, defaults to None
Returns:: Rate Limit stats
Return type:: ApiResponse

scene_list_add(list_id: str, dataset_name: str, id_field: Literal['entityId', 'displayId'] | None = 'entityId', entity_id: str | None = None, entity_ids: List[str] | None = None, ttl: str | None = None, check_download_restriction: bool | None = None) → None

Adds items in the given scene list.

Parameters:

list_id (str) – User defined name for the list
dataset_name (str) – Dataset alias
id_field (Optional[str], optional) – Used to determine which ID is being used, defaults to entityId
entity_id (Optional[str], optional) – Scene Identifier, defaults to None
entity_ids (Optional[List[str]], optional) – A list of Scene Identifiers, defaults to None
ttl (Optional[str], optional) – User defined lifetime using ISO-8601 formatted duration (such as “P1M”) for the list, defaults to None
check_download_restriction (Optional[bool], optional) – Optional parameter to check download restricted access and availability, defaults to None

Raises:

HTTPError –
RuntimeError – If number of added items does not equal 1 or len(entity_ids), a RunTimeError is raised

Example:

Api.scene_list_add(: list_id=”my_scene_list”, dataset_name=”landsat_ot_c2_l2”, id_field=”displayId”, entity_id=”LC08_L2SP_012025_20201231_20210308_02_T1”

)

scene_list_get(list_id: str, dataset_name: str | None = None, starting_number: int | None = None, max_results: int | None = None) → ApiResponse

Returns items in the given scene list.

Note

starting_number is 1-indexed

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
max_results (Optional[int], optional) – How many results should be returned?, defaults to None

Returns:

List of items in requested scene list. Each entry is a dictionary in the form of {‘entityId’, ‘datasetName’}.

Return type:

Raises:

HTTPError –

Example:

Api.scene_list_get(list_id=”my_scene_list”)

scene_list_remove(list_id: str, dataset_name: str | None = None, entity_id: str | None = None, entity_ids: List[str] | None = None) → None

Removes items from the given list. If no datasetName is provided, the call removes the whole list. If a datasetName is provided but no entityId, this call removes that dataset with all its IDs. If a datasetName and entityId(s) are provided, the call removes the ID(s) from the dataset.

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None
entity_id (Optional[str], optional) – Scene Identifier, defaults to None
entity_ids (Optional[List[str]], optional) – A list of Scene Identifiers, defaults to None

Raises:

HTTPError –

Example:

Api.scene_list_remove(: list_id=”my_scene_list”, dataset_name=”landsat_ot_c2_l2”, entity_id=”LC80120252020366LGN00”

)

scene_list_summary(list_id: str, dataset_name: str | None = None) → ApiResponse

Returns summary information for a given list.

Parameters:

list_id (str) – User defined name for the list
dataset_name (Optional[str], optional) – Dataset alias, defaults to None

Returns:

Dictionary containing a summary and datasets ({‘summary’, ‘datasets’}).

Return type:

Raises:

HTTPError –

scene_list_types(list_filter: str | None) → ApiResponse

Returns scene list types (exclude, search, order, bulk, etc).

Parameters:: list_filter (Optional[str]) – If provided, only returns listIds that have the provided filter value within the ID
Returns:: List of scene list, each containing a dictionary describing a scene list.
Return type:: ApiResponse

scene_metadata(dataset_name: str, entity_id: str, id_type: str | None = 'entityId', metadata_type: str | None = None, include_null_metadata: bool | None = None, use_customization: bool | None = None) → ApiResponse

This request is used to return metadata for a given scene.

Note

The parameter entity_id is named confusingly. Depending on id_type, passing one of entityId, displayId or orderingId is allowed

Parameters:

dataset_name (str) – Used to identify the dataset to search
entity_id (str) – Used to identify the scene to return results for
id_type (Optional[str], optional) – If populated, identifies which ID field (entityId, displayId or orderingId) to use when searching for the provided entityId, defaults to “entityId”
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary, full, fgdc, iso), defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to display metadata view as per user customization, defaults to None

Returns:

Dict containing scene metadata

Return type:

Raises:

HTTPError –

scene_metadata_list(list_id: str, dataset_name: str | None = None, metadata_type: str | None = None, include_null_metadata: bool | None = None, use_customization: bool | None = None) → ApiResponse

Scene Metadata where the input is a pre-set list.

Parameters:

list_id (str) – Used to identify the list of scenes to use
dataset_name (Optional[str], optional) – Used to identify the dataset to search, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to display metadata view as per user customization, defaults to None

Returns:

Dict containing metadata for requested list

Return type:

scene_metadata_xml(dataset_name: str, entity_id: str, metadata_type: str | None = None) → ApiResponse

Returns metadata formatted in XML, ahering to FGDC, ISO and EE scene metadata formatting standards.

Note

It’s unclear if entity_id refers exclucively to the entityId or if other kinds of Ids can be passed as well.

Parameters:

dataset_name (str) – Used to identify the dataset to search
entity_id (str) – Used to identify the scene to return results for
metadata_type (Optional[str], optional) – Used to identify the scene to return results for, defaults to None

Returns:

Returns dictionary with metadata for requested scene. The XML content is available with the key ‘exportContent’

Return type:

Raises:

HTTPError –

scene_search(dataset_name: str, max_results: int = 100, starting_number: int | None = None, metadata_type: str | None = None, sort_field: str | None = None, sort_direction: Literal['ASC', 'DESC'] | None = None, sort_customization: SortCustomization | None = None, use_customization: bool | None = None, scene_filter: SceneFilter | None = None, compare_list_name: str | None = None, bulk_list_name: str | None = None, order_list_name: str | None = None, exclude_list_name: str | None = None, include_null_metadata: bool | None = None) → ApiResponse

Searching is done with limited search criteria. All coordinates are assumed decimal-degree format. If lowerLeft or upperRight are supplied, then both must exist in the request to complete the bounding box. Starting and ending dates, if supplied, are used as a range to search data based on acquisition dates. The current implementation will only search at the date level, discarding any time information. If data in a given dataset is composite data, or data acquired over multiple days, a search will be done to match any intersection of the acquisition range. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter timeouts for large result sets for some datasets. To use the sceneFilter field, pass one of the four search filter objects (SearchFilterAnd, SearchFilterBetween, SearchFilterOr, SearchFilterValue) in JSON format with sceneFilter being the root element of the object.

Searches without a ‘sceneFilter’ parameter can take much longer to execute. To minimize this impact we use a cached scene count for ‘totalHits’ instead of computing the actual row count. An additional field, ‘totalHitsAccuracy’, is also included in the response to indicate if the ‘totalHits’ value was computed based off the query or using an approximated value. This does not impact the users ability to access these results via pagination. This cached value is updated daily for all datasets with active data ingests. Ingest frequency for each dataset can be found using the ‘ingestFrequency’ field in the dataset, dataset-categories and dataset-search endpoint responses.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

dataset_name (str) – Used to identify the dataset to search. Can be datasetAlias.
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
sort_field (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Determines how the results should be sorted, defaults to None
sort_customization (Optional[SortCustomization], optional) – Used to pass in custom sorts, defaults to None
use_customization (Optional[bool], optional) – Optional parameter to indicate whether to use customization, defaults to None
scene_filter (Optional[SceneFilter], optional) – Used to filter data within the dataset, defaults to None
compare_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for comparison, defaults to None
bulk_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for bulk ordering, defaults to None
order_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for on-demand ordering, defaults to None
exclude_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to exclude scenes from the results, defaults to None
include_null_metadata (Optional[bool], optional) – Optional parameter to include null metadata values, defaults to None

Raises:

HTTPError –

Returns:

Dictionary containing search results as List[Dict] together with some additional search meatadata ([‘recordsReturned’, ‘totalHits’, ‘totalHitsAccuracy’, ‘isCustomized’, ‘numExcluded’, ‘startingNumber’, ‘nextRecord’])

Return type:

Example:

# General search Api.scene_search( “gls_all”, max_results=500, scene_filter=SceneFilter(AcquisitionFilter(…), CloudCoverFilter(…), …), bulk_list_name=”my_bulk_list”, metadata_type=”summary”, order_list_name=”my_order_list”, starting_number=1, compare_list_name=”my_comparison_list”, exlucde_list_name=”my_exclude_list” )

# Search with spatial filter and ingest filter

# Search with acquisition filter

# Search with metadata filter (metadata filter ids can be retrieved by calling dataset-filters)

# Sort search results using useCustomization flag and sortCustomization

scene_search_delete(dataset_name: str, max_results: int = 100, starting_number: int | None = None, sort_field: str | None = None, sort_direction: Literal['ASC', 'DEC'] | None = None, temporal_filter: TemporalFilter | None = None) → ApiResponse

This method is used to detect deleted scenes from datasets that support it. Supported datasets are determined by the ‘supportDeletionSearch’ parameter in the ‘datasets’ response. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter timeouts for large result sets for some datasets.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

dataset_name (str) – Used to identify the dataset to search
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
sort_field (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DEC"]], optional) – Determines how the results should be sorted, defaults to None
temporal_filter (Optional[TemporalFilter], optional) – Used to filter data based on data acquisition, defaults to None

Returns:

Dictionary containing search results as List[Dict] together with some additional search meatadata

Return type:

Raises:

HTTPError –

scene_search_secondary(entity_id: str, dataset_name: str, max_results: int = 100, starting_number: int | None = None, metadata_type: str | None = None, sort_filed: str | None = None, sort_direction: Literal['ASC', 'DESC'] | None = None, compare_list_name: str | None = None, bulk_list_name: str | None = None, order_list_name: str | None = None, exlucde_list_name: str | None = None) → ApiResponse

This method is used to find the related scenes for a given scene.

Note

It returns 100 results by default. Users can set input ‘maxResults’ to get different results number returned. It is recommened to set the maxResults less than 10,000 to get better performance. The allowed maximum is 50_000.

Note

The response of this request includes a ‘totalHits’ response parameter that indicates the total number of scenes that match the search query to allow for pagination.

Note

The argument dataset_name can be given by datasetAlias.

Note

starting_number is 1-indexed

Parameters:

entity_id (str) – Used to identify the scene to find related scenes for
dataset_name (str) – Used to identify the dataset to search
max_results (int, optional) – How many results should be returned ?, defaults to 100
starting_number (Optional[int], optional) – Used to identify the start number to search from, defaults to None
metadata_type (Optional[str], optional) – If populated, identifies which metadata to return (summary or full), defaults to None
sort_filed (Optional[str], optional) – Determines which field to sort the results on, defaults to None
sort_direction (Optional[Literal["ASC", "DESC"]], optional) – Determines how the results should be sorted, defaults to None
compare_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for comparison, defaults to None
bulk_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for bulk ordering, defaults to None
order_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to track scenes selected for on-demand ordering, defaults to None
exlucde_list_name (Optional[str], optional) – If provided, defined a scene-list listId to use to exclude scenes from the results, defaults to None

Returns:

Dictionary containing search results for related scenes as List[Dict] together with some additional search meatadata

Return type:

Raises:

HTTPError –

tram_order_detail_update(order_number: str, detail_key: str, detail_value: str) → ApiResponse

This method is used to set metadata for an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_number (str) – The order ID for the order to update
detail_key (str) – The system detail key
detail_value (str) – The value to store under the detailKey

Returns:

Updated key-value pair

Return type:

tram_order_details(order_number: str) → ApiResponse

This method is used to view the metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get details for
Returns:: Metadata for order as dictionary
Return type:: ApiResponse

tram_order_details_clear(order_number: str) → ApiResponse

This method is used to clear all metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to clear details for
Returns:: Data section is Null
Return type:: ApiResponse

tram_order_details_remove(order_number: str, detail_key: str) → ApiResponse

This method is used to remove the metadata within an order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_number (str) – The order ID to clear details for
detail_key (str) – The system detail key

Returns:

Previous value of deleted key

Return type:

Search TRAM orders.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:

order_id (Optional[str], optional) – The order ID to get status for (accepts ‘%’ wildcard), defaults to None
max_results (Optional[int], optional) – How many results should be returned on each page?, defaults to 25
system_id (Optional[str], optional) – Limit results based on the application that order was submitted from, defaults to None
sort_asc (Optional[bool], optional) – True for ascending results, false for descending results, defaults to None
sort_field (Optional[Literal["order_id", "date_entered", "date_updated"]], optional) – Which field should sorting be done on?, defaults to None
status_filter (Optional[List[str]], optional) – An array of status codes to…, defaults to None

Returns:

List of order information

Return type:

tram_order_status(order_number: str) → ApiResponse

Gets the status of a TRAM order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get status for
Returns:: Status for requested order
Return type:: ApiResponse

tram_order_units(order_number: str) → ApiResponse

Lists units for a specified order.

Warning

This method is only documented and accessible when having the MACHINE role assigned to your account.

Parameters:: order_number (str) – The order ID to get units for
Returns:: List of TRAM units
Return type:: ApiResponse

user_preferences_get(system_id: str | None = None, setting: List[str] | None = None) → ApiResponse

This method is used to retrieve user’s preference settings.

Parameters:

system_id (Optional[str], optional) – Used to identify which system to return preferences for. If null it will return all the users preferences, defaults to None
setting (Optional[List[str]], optional) – If populated, identifies which setting(s) to return, defaults to None

Returns:

Dict containing, possibly subset, preferences of calling user

Return type: