Skip to content

Account Access and Administration

In most cases you will not have to communicate directly with the API and you can use the Select and Order objects.

Should you wish to build your own tooling, the ARD Python SDK provides an authenticated requests session object that can be used to communicate with the API.

Authentication requires either a credential file or environment variables. The credential file .ard-config is stored in your user home directory and must contain:

[ard]
user_name = <your user name>
user_password = <your password>
In environments where you are unable to store a credential file, set the following environment variables:

export ARD_USERNAME=<your user name>
export ARD_PASSWORD=<your password>

The complete ARD API documentation can be found here.

Authenticated Sessions

Communication with the API can be done through an authenticated requests session object:

from max_ard.session import get_user_session
session = get_user_session()

The requests module is a popular HTTP library for Python that makes working with API endpoints simple. See the requests docs for more examples.

You can use the authenticated session the same as with regular requests patterns. 

# default requests pattern
import requests
response = requests.get('https://api.github.com/user')

# authenticated ARD API pattern
from max_ard.session import get_user_session
session = get_user_session()
response = session.get('https://ard.maxar.com/api/v1/auth/self')

A typical pattern to GET information from an API endpoint would be:

response = session.get('https://ard.maxar.com/v1/auth/self')
# response.json() is the decoded response, ready to use
print(response.json())

ARD Sessions will raise exceptions when server errors are encountered. You do not need to check the response with raise_for_status().

Similarly, to POST to an API endpoint you could do:

payload = {
    "datetime": "2019-10-25T09:00:00Z/2020-10-26T13:00:00Z",
    "intersects": "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
    "stack_depth": 5,
}

response = session.post('https://ard.maxar.com/api/v1/select', json=payload)
print(response.json())

Should you need the access token, you can get it from:

session.token

Account Administration

The AccountManager object provides methods for checking usage data, and storing access credentials for Cloud storage providers.

Data Usage

Ther are two AccountManager methods for checking data usage - get_account_usage and get_user_usage. Both methods can take start and end dates via the start_date and end_date parameters. Dates must be provided in the YYYY-MM-DD format.

from max_ard import AccountManager
manager = AccountManager()
# usage objects have a formatted __repr__
print(manager.get_account_usage())

 Data Usage
 ----------

  Account limit: unlimited sq.km ($unlimited)

  Imagery ordered: 0.0 sq.km ($0.0)
  ├ Fresh (< 90 days): 0.0 sq.km ($0.0)
  ├ Standard (90 days - 3 years): 0.0 sq.km ($0.0)
  └ Training (> 3 years): 0.0 sq.km ($0.0)

  Remaining balance: unlimited sq.km ($unlimited)

# gets usage for the current user
# Usage objects are Pydantic data models
manager.get_user_usage()

# for a different user in your account (requires admin privileges) 
# manager.get_user_usage(username=<user name>)

AdminUsage(area=UsageArea(fresh_imagery_sqkm=0.0, standard_imagery_sqkm=0.0, training_imagery_sqkm=0.0, total_imagery_sqkm=0.0, estimate=False), cost=UsageCost(fresh_imagery_cost=0.0, standard_imagery_cost=0.0, training_imagery_cost=0.0, total_imagery_cost=0.0, estimate=False), limits=UsageLimits(limit_sqkm=-1.0, fresh_imagery_fee_limit=-1.0, standard_imagery_fee_limit=-1.0, training_imagery_fee_limit=-1.0, annual_subscription_fee_limit=-1.0), available=UsageAvailable(available_sqkm=-1.0, fresh_imagery_balance=-1.0, standard_imagery_balance=-1.0, training_imagery_balance=-1.0, total_imagery_balance=-1.0))

Credential Storage

Google Cloud Storage and Azure Blob storage use long access tokens that are awkward to include in the order request. To simplify the process, Admin users can store the long tokens in the ARD system. Other users in the same account can then refer to the token name in orders.

The AccountManager object has methods to add, remove, get, and list credentials. Note that once access credentials are stored the access token is never returned.

  • add_credentials(<name>, <credentials>, <optional description>)
  • get_credentials(<name>)
  • list_credentials()
  • delete_credentials(<name>)

Adding credentials

The .add_credentials method requires two arguments:

  • A name for the credentials that will be used as an ID to specify the credentials in orders. The name should be URL-friendly and you should avoid reserved characters and spaces that are URL escaped.
  • The credentials token. This is either the SAS URL for Azure, or the Base64-encoded JSON credential for Google Cloud. For Google Cloud credentials, you can pass a path to the JSON credentials file instead and the SDK will load the contents and convert to Base64 for you.

Optionally you can pass:

  • A description of the credentials to help manage tokens. The description is displayed when getting or listing credentials.

Credentials are unique by name - adding credentials with a name that already exists will overwrite the exisiting credentials.

Getting credentials by name

You can get a credential by name to view its description or other metadata.

List all credentials

The list_credentials method returns a list of all credential objects.

Delete credentials

Credentials can be deleted by name. Deleted credentials cannot be restored.

Credentials Objects

RegisteredCredentials objects are Pydantic models of credentials. They have the following attributes:

  • credentials_id: the short name given to the credentials when it was registered
  • account_id: your account ID
  • description: description provided
  • created: timestamp of first registration of these credentials
  • modified: timestamp of last modification to these credentials

Example

# Azure Blob Storage SAS URL
>> token = "https://storagesample.blob.core.windows.net/?..."
# Base64 Google Cloud credentials JSON
>> token = "YWtnamFzZGhna2po..."
# or a local path to Google Cloud credentials json file
>> token = "/path/to/credentials.json"

# add a token
>> manager.add_credentials("our-shared-credentials", token, "description of the credentials")
{<JSON response>}

# get a credential object
>> creds = manager.get_credentials("our-shared-token")
>> creds
<RegisteredCredentials "our-shared-credentials" (description of the cr...)>
>> creds.created
'2021-11-18T19:30:26Z'
>> creds.description
'description of the credentials'

# list all credentials
>> manager.list_credentials()
[<RegisteredCredentials "our-shared-credentials" (description of the cr...)>]

>> manager.delete_credentials("our-shared-credential")

>> manager.list_credentials()
[]

Monitors

The AccountManager object can also list Monitors. Users with administrative credentials will see all active monitors that belong to the account.

manager.list_monitors()

This returns a list of Monitor objects. For more information, see Monitoring.

Back to top