Usage Resource¶
Last updated: December 20, 2022
Usage¶
/usage
Usage requests¶
| http method | path | description | role required |
|---|---|---|---|
| GET | /usage/account/{account_id} | Get usage data for an account. | Admin or User |
| GET | /usage/user/{user_id} | Get usage data for a user. | Admin or User |
| POST | /usage/async/account/{account_id} | Request asynchronous usage results | Admin or User |
| GET | /usage/async/{request_id} | Get asynchronous usage results | Admin or User |
Get usage data for an account¶
GET /usage/account/{account_id}
An account administrator uses this request to get usage data for their account.
Path parameters¶
| Parameter | Description | example |
|---|---|---|
| account_id | The ID for the account the usage data is requested for. | 557471230760500000 |
Query parameters¶
The start and end date query parameters are optional. If these parameters are not set, the start and end dates for the subscription are applied.
| param | description | example |
|---|---|---|
| start_date | The start date for the requested usage period. | start_date=2021-01-01 |
| end_date | The end date for the requested usage period. | end_date=2021-07-28 |
Start date and end dates can include a time.
Example:
start_date=2022-01-17T16:58:19Z
Example request with start and end date set¶
Example:
https://ard.maxar.com/api/v1/usage/account/557471230760500000?start_date=2021-01-01&end_date=2021-07-28
?. The format is:
parameter=value
start_date=2021-01-01
When both start and end date are selected, they're joined by an ampersand &.
Example:
start_date=2021-01-01&end_date=2021-07-28
Response¶
{
"account_id": "557471230760500000",
"usage": {
"area": {
"fresh_imagery_sqkm": 14768.9,
"standard_imagery_sqkm": 42007.9,
"training_imagery_sqkm": 16231.8,
"total_imagery_sqkm": 73008.6,
"estimate": false
},
"cost": {
"fresh_imagery_cost": 147.75,
"standard_imagery_cost": 420.04,
"training_imagery_cost": 162.26,
"total_imagery_cost": 730.05,
"estimate": false
},
"limits": {
"fresh_imagery_fee_limit": 500,
"standard_imagery_fee_limit": -1,
"training_imagery_fee_limit": -1,
"annual_subscription_fee_limit": 1000
},
"available": {
"fresh_imagery_balance": 352.25,
"standard_imagery_balance": -1,
"training_imagery_balance": -1,
"total_imagery_balance": 269.95
}
},
"tasking_usage": {
"area": {
"tasking_imagery_sqkm": 50.0
},
"cost": {
"tasking_imagery_cost": 1775.0
},
"limits": {
"tasking_imagery_fee_limit": 10000
},
"available": {
"tasking_imagery_balance": 8225
},
"usage_as_of": "2022-12-15T20:19:20Z"
},
"usage_period": {
"start_date": "2021-01-01T00:00:00Z",
"end_date": "2022-12-15T20:19:20Z"
},
"links": {
"account": "https://ard.maxar.com/api/v1/admin/account/55747123076050000"
},
"response_timestamp": "2022-12-15T20:19:20Z"
}
Response fields¶
| name | description |
|---|---|
| account_id | The ID for the account. |
| usage | Order usage data for the account. |
| area | Square kilometer usage to date, by category. |
| cost | The cost object shows the dollar amount spent to date on imagery by category. |
| limits | The total and category spending limit for the account, as determined by the subscription. |
| available | The sqkm and cost allocation for the category or in total. |
| tasking_usage | The dollar amount spent to date for tasking requests. Usage is charged based on square kilometers in the AOI when the tasking request is submitted. |
| usage_period | The start date and end date for the usage period. If query parameters for start and end date are set, these are the dates displayed. If query parameters or not set, the start and end dates for the contract are used. |
| start_date | The start date for the usage period. If no date is specified in the request, the contract start date is used. |
| end_date | The end date for the usage period. If no date is specified in the request, the contract end date is used. |
| links | HTTP link to the details for the account. Requires ARD authentication. |
| response_timestamp | The date and time the usage request was made. |
The default value for the limit fields is null or -1. This indicates no limit has been set for the category. When no limit is set, only the annual fee subscription limit applies.
Area object¶
| name | description |
|---|---|
| fresh_imagery_sqkm | The "fresh" imagery sqkm used to date for the account. |
| standard_imagery_sqkm | The "standard" imagery sqkm used to date for the account. |
| training_imagery_sqkm | The "training" imagery sqkm used to date for the account. |
| total_imagery_sqkm | The total sqkms used to date for the account. |
| estimate | When set to false, this is an actual value. When set to true, the value is estimated and could change. For usage requests, the value is always "false". |
Cost object¶
| name | description |
|---|---|
| fresh_imagery_cost | The dollar amount spent to date on "fresh" imagery. |
| standard_imagery_cost | The dollar amount spent to date on "standard" imagery |
| training_imagery_cost | The dollar amount spent to date on "training" imagery |
| total_imagery_cost | The total dollar amount spent to date on ARD imagery. |
Limits object¶
| name | description |
|---|---|
| annual_subscription_fee_limit | The total annual allocation for the ARD subscription in dollars. |
| fresh_imagery_fee_limit | The limit set for imagery in the "fresh" imagery age category in dollars. If the fee limit is set to zero "0", imagery from this category cannot be ordered. If the limit is set to -1, there is no fee limit set for this category, and only the annual subscription fee limit applies. |
| standard_imagery_fee_limit | The limit set for imagery in the "standard" imagery age category. If the fee limit is set to zero "0", imagery from this category cannot be ordered. If the limit is set to 1, there is fee limit for this category, and only the annual subscription fee limit applies. |
| training_imagery_fee_limit | The limit set for imagery in the "training" imagery age category. If the fee limit is set to zero "0", imagery from this category cannot be ordered. If the limit is set to 1, there is fee limit for this category, and only the annual subscription fee limit applies. |
Available object¶
| name | description |
|---|---|
| available_sqkm | The remaining total sqkms available for archive orders the account or user. |
| available_fresh_balance | The remaining allocation available for fresh imagery, in dollars. |
| available_standard_blance | The reamining allocation available for standard imagery, in dollars. |
| available_training_balance | The remaining allocation available for training imagery, in dollars. |
| total_imagery_balance | The total remaining archive imagery allocation available, in dollars. |
Tasking object¶
| object | field | description |
|---|---|---|
| area | tasking_imagery_sqkm | The total square kilometers in the tasking request. |
| cost | tasking_imagery_cost | the total cost of imagery in the tasking request. |
| limits | tasking_imagery_fee_limit | The tasking usage allotment determined by the account's subscription. |
| available | tasking_imagery_balance | The remaining usage allotment for tasking, as determined by the account's subscription. |
Request asyncronous usage results for an account¶
Request a csv file with usage results. This report can also be retrieved by an additional API request.
POST /usage/async/account/{account_id}
Role: Admin or User
Path parameters¶
| Parameter | Description | example |
|---|---|---|
| account_id | The ID for the account the usage data is requested for. | 557471230760500000 |
Query parameters¶
| Parameter | Description | example |
|---|---|---|
| start_date | The beginning date of the usage date range in ISO-8601 format. | start_date=2022-06-01 |
| end_date | The end date of the usage date range in ISO-8601 format. | end_date=2022-07-12 |
| show_users | Set the value to true to see usage data for each user in the response. Must be an "admin" to include this field in your request. | show_users=true |
Request body¶
List the email address where the usage CSV file should be sent.
{
"notifications": [
{
"type": "email",
"address": "example.email@maxar.com"
}
]
}
Asynchronous response example¶
This is an example of the response to a POST request for asynchronous usage:
{
"id": "6080552000503065666",
"account_id": "55747123076050000",
"response_timestamp": "2022-12-20T18:31:24Z",
"status": "RUNNING",
"usage_period": {
"start_date": "2021-01-01T00:00:00Z",
"end_date": "2022-12-20T18:31:24Z"
},
"links": {
"status": "https://ard.maxar.com/api/v1/usage/async/6080552000503065666"
}
}
To see the results, make a GET request to the asynchronous endpoint.
GET /usage/async/{usage request ID}
https://ard.maxar.com/api/v1/usage/async/6080552000503065666
Example:
{
"id": "6080552000503065666",
"account_id": "55747123076050000",
"usage": {
"area": {
"fresh_imagery_sqkm": 14768.9,
"standard_imagery_sqkm": 42007.9,
"training_imagery_sqkm": 16231.8,
"total_imagery_sqkm": 73008.6,
"estimate": false
},
"cost": {
"fresh_imagery_cost": 147.75,
"standard_imagery_cost": 420.04,
"training_imagery_cost": 162.26,
"total_imagery_cost": 730.05,
"estimate": false
},
"limits": {
"fresh_imagery_fee_limit": -1,
"standard_imagery_fee_limit": -1,
"training_imagery_fee_limit": -1,
"annual_subscription_fee_limit": -1
},
"available": {
"fresh_imagery_balance": -1,
"standard_imagery_balance": -1,
"training_imagery_balance": -1,
"total_imagery_balance": -1
}
},
"tasking_usage": {
"area": {
"tasking_imagery_sqkm": 24943.958
},
"cost": {
"tasking_imagery_cost": 249.44
},
"limits": {
"tasking_imagery_fee_limit": -1
},
"available": {
"tasking_imagery_balance": -1
},
"usage_as_of": "2022-12-20T18:31:26Z"
},
"usage_period": {
"start_date": "2021-01-01T00:00:00Z",
"end_date": "2022-12-20T18:31:24Z"
},
"links": {
"account": "https://ard.maxar.com/api/v1/admin/account/55747123076050000"
},
"status": "SUCCEEDED",
"response_timestamp": "2022-12-20T19:16:44Z"
}
Emailed Usage report¶
A CSV file with your account's usage will be emailed to the address you included in the request body. The title of the email is:
"The usage report you requested is now available"
Get usage data for a specific user¶
GET /usage/user/{user_id}
Role: User or Admin
Path parameters¶
| Parameter | Description |
|---|---|
| user_id | The ID for the account the usage data is requested for. |
Response¶
See the Response in the account usage section above. All fields are the same. The usage limits shown here are the limits set for the user. If the annual subscription fee is set to -1 or null, this means there is no limit set for the user, and the account's limit applies.