Account Usage Data¶
Last updated: December 15, 2022
Overview¶
When the ARD Support team creates your account, they set the following pricing data and fee limits:
| Category | Description |
|---|---|
| Limits | The amount of imagery that can be purchased is limited by what is set in the ARD subscription agreement. Once an account reaches this limit, orders cannot be placed. The terms of the agreement may also set limits on imagery purchased in a specific age category. |
| Pricing | Price per square kilometer. Pricing is set at the account level. The price is different for each imagery age category. The terms of the agreement may specify that imagery from one or more categories cannot be ordered. |
Fee limits can also be set for individual users within the account. As an account administrator, you can set these limits when you create a user in your account or update the user record with these details. These can be set from the ARD Dashboard Account Users Page or by submitting a request to the Admin API. To learn how to set fee limits for a user in your account, see Account/User API reference.
Square kilometers (sqkm) limits may also be set for the account. This is an optional field that defaults to "unlimited".
Image age categories¶
ARD subscriptions include pricing for archive imagery based on its age. These categories are:
These are the image age categories for archive imagery:
| image age category | time since acquisition |
|---|---|
| Fresh imagery | less than or equal to 90 days |
| Standard imagery | 91 days to 3 years |
| Training imagery | more than 3 years |
The subscription agreement will indicate a price for each category. It may also limit the amount of imagery that can be purchased in a specific category. We refer to this as a category fee limit. If no category fee limit is set, the total annual subscription fee limit applies.
Tasking usage¶
Tasking is an add-on purchase to a subscription. Cost for tasking requests are incurred up front when the tasking request is placed. There is no additional charge when the imagery from tasking fulfillment is delivered.
View account usage limits¶
To see the pricing and fee limits set for your account, make a Get Account Details request to the ARD Admin/Account API resource. This will show details about the account you're a part of.
View usage data¶
Usage data can be viewed from the ARD Dashboard or by making a request to the Usage API. The ARD Dashboard requires a date range before usage can be displayed. In the API, the date range is optional, but it may be needed if the amount of usage data is too large to return before the API request times out.
If the results of a usage data request are too large to be returned, you can make a request to the Asynchronous Usage endpoint. In this type of request, you'll specify an email address and a csv file will be sent to you when the request completes.
ARD Dashboard view¶
If you're an account administrator, you can view your account's usage data from the Maxar ARD Dashboard.
-
Go to https://ard.maxar.com/dashboard
-
Sign in with your ARD username and password. Your username is the email address where you received your account activation email.
-
Go to the "Manage" tab and choose "Usage" from the dropdown menu.
-
Enter a date range.
From this page, you can view your usage for the date range and the amount remaining. For more information, see Dashboard Help: Usage.
Usage API Request¶
You can request your account's usage data by making a request to the ARD Usage API. The request can be constrained by start_date and end_date query parameters. See ARD Usage API Reference for more information. Administrators and users can make this request.
Usage API Response¶
Example:
{
"account": {
"account_id": "5600098189427357..",
"name": "Maxar ARD Docs",
"sap": "65432",
"contract_start": "2022-02-20",
"contract_end": "2023-02-20",
"active": true,
"internal": false,
"sales_support_contacts": null,
"created": "2021-02-25T20:55:26Z",
"modified": "2022-06-03T15:13:41Z",
"pricing": {
"fresh_imagery_price": 25,
"standard_imagery_price": 20,
"training_imagery_price": 5
},
"limits": {
"annual_subscription_fee_limit": 15000,
"fresh_imagery_fee_limit": 20000,
"standard_imagery_fee_limit": -1,
"training_imagery_fee_limit": -1,
"tasking_imagery_fee_limit": 5000
}
},
"links": {
"self": "https://ard.maxar.com/api/v1/admin/account/56000981894273578..",
"users": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../user",
"applications": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../application",
"credentials": "https://ard.maxar.com/api/v1/admin/account/56000981894273578../credentials"
},
"response_timestamp": "2022-06-03T15:14:08Z"
}
The value -1 for any field means unlimited. In most cases this means the field was not set. If a fee limit is set to -1, the available balance will be -1 since there is no fee limit to use for calculation.
See the Use API Reference documentation for a detailed explanation of this response.
Asynchronous usage data request¶
If the results set for a usage request is too large to be returned before the request times out, you can make a request to the Asynchronous Usage endpoint.
This request requires an account ID and accepts start and end date parameters.
Asynchronous usage request example¶
POST usage/async/account/{account_id}
Example:
https://ard.maxar.com/api/v1/usage/async/account/557471230760500000?start_date=2022-04-23&end_date=2022-05-05
Include the following request body to have a csv usage file emailed to you:
{
"notifications": [
{
"type": "email",
"address": "example.email@mail.com"
}
]
}
Asynchronous usage request response¶
{
"id": "5963831769331387698",
"account_id": "557471230760500000",
"response_timestamp": "2022-07-12T17:29:08Z",
"status": "RUNNING",
"usage_period": {
"start_date": "2021-01-01T00:00:00Z",
"end_date": "2022-07-12T17:29:08Z"
},
"links": {
"status": "https://ard.maxar.com/api/v1/usage/async/5963831769331387698"
}
}
To retrieve asynchronous usage results from the API, copy the "ID" from this response, and make a follow-up request to:
GET /usage/async/{request_id}
Example:
https://ard.maxar.com/api/v1/usage/async/5963831769331387698
This will return the same results as a standard Usage API request, shown above.
View usage estimates when selecting imagery¶
A request to the Select API returns an estimate of usage that would be incurred if the selected imagery is ordered.
| Usage type | Description |
|---|---|
| area | The square kilometers covered by selected imagery. The "area" section displays the total sqkm usage and the sqkm usage by category. |
| cost | The amount that will be spent on ordered imagery by imagery age category. The total amount spent in all three categories is also displayed. |
| limits | Displays the sqkm and fee limits set for the account. |
| available | Shows the remaining available allotment for ordering ARD imagery, in dollars. The remaining sqkm allotment is also displayed in this section. See below to understand how available balances are calculated. |
Usage and cost estimates shown for the imagery selection may not match the usage costs incurred by order in some cases. For example:
-
Other users in the account may place orders and reduce the available allotment for the account.
-
One or more images in the selection could move from one image age category to another, reducing the cost of that image. For example, an image may be in the "fresh" image category when the selection is made, but it moved to the "standard" category by the time the order was placed.
View usage estimates for an order by submitting a "dry run" order request¶
The Ordering API allows a validation check before an order is placed. The validation check will return any errors that would prevent an order from being placed. The dry run response also estimates the usage that will be incurred when the order is placed.
To validate an order before placing it, add "dry_run":true to your order request. The response includes the estimated usage the order will consume when submitted.
Placing an ARD order¶
If an order request is submitted that will exceed the costs allowed by the subscription fee limits, it will return an error and the order will not be placed.
When an order successfully completes, an order status request will show the actual usage and cost of the order. Costs are not incurred until the ordered files are delivered to your cloud location. There is no charge for a failed order.