Skip to content

Usage Resource

Get usage data for an account or a user.

Last updated: August 29, 2022


To learn more about usage results, see the Account Usage Guide.

Usage

/usage

Usage endpoints

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}
Role: Admin

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. 999712307605640000

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

Example request with start and end date set

Example:

https://ard.maxar.com/api/v1/usage/account/99997123076056000?start_date=2021-01-01&end_date=2021-07-28
Query parameters are appended to the request URL, starting with a question mark ?. The format is:

parameter=value
Example:

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": "9999712307605640000",
    "usage": {
        "area": {
            "fresh_imagery_sqkm": 51.5,
            "standard_imagery_sqkm": 206.4,
            "training_imagery_sqkm": 9.3,
            "total_imagery_sqkm": 267.2,
            "estimate": false
        },
        "cost": {
            "fresh_imagery_cost": 52.0,
            "standard_imagery_cost": 1032.0,
            "training_imagery_cost": 27.9,
            "total_imagery_cost": 1111.9,
            "estimate": false
        },
        "limits": {
            "limit_sqkm": 3000000,
            "fresh_imagery_fee_limit": 500,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
            "annual_subscription_fee_limit": 100000
        },
        "available": {
            "available_sqkm": 2999732.8,
            "available_fresh_cost": 448,
            "available_standard_cost": -1,
            "available_training_cost": -1,
            "available_total_cost": 98888.1
        }
    },
    "usage_period": {
        "start_date": "2021-06-01",
        "end_date": "2021-07-28"
    },
    "links": {
        "account": "https://ard.maxar.com/api/v1/admin/account/9999712307605640000"
    },
    "response_timestamp": "2021-07-28T20:12:24Z"
}

Response fields

name description example
account_id The ID for the account the usage data is associated with. "account_id":"9999712307605640000"
usage Usage data for the account, broken down by usage category. This table provides examples for each field.
area Square kilometer usage to date, by category and in total. Examples are provided below for each field in the "area" section.
fresh_imagery_sqkm The "fresh" imagery sqkm used to date for the account or user. "standard_imagery_sqkm": 206.4
training_imagery_sqkm The "training" imagery sqkm used to date for the account or user. "standard_imagery_sqkm": 9.3
total_imagery_sqkm The total sqkms used to date for the account or user. "total_imagery_sqkm": 267.2
estimate The "estimate" fields can be true or false. When set to false, this is an actual value, not an estimate. When set to true, the value is an estimate and could change. "estimate": false
cost The dollar amount spent to date on imagery in the specified imagery age category or in total. Examples are provided for the specific cost fields.
fresh_imagery_cost The dollar amount spent to date on "fresh" imagery. "fresh_imagery_cost": 52.0
standard_imagery_cost The dollar amount spent to date on "standard" imagery "standard_imagery_cost": 1032.0
training_imagery_cost The dollar amount spent to date on "training" imagery "training_imagery_cost": 27.9
total_imagery_cost The total dollar amount spent to date on ARD imagery. Examples are provided for the specific limits fields.
limits The total and category spending limit for the account
annual_subscription_fee_limit The total annual allocation for the ARD subscription in dollars. "annual_subscription_fee_limit": 582.50
fresh_imagery_fee_limit The limit set for imagery in the "fresh" imagery age category in dollars. Once the limit has been met for this category, no more "fresh" imagery can be ordered. 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. "fresh_imagery_fee_limit": 200.00
standard_imagery_fee_limit The limit set for imagery in the "standard" imagery age category. Once the limit has been met for this category, no more "standard" imagery can be ordered. 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. "standard_imagery_fee_limit": -1
training_imagery_fee_limit The limit set for imagery in the "training" imagery age category. Once the limit has been met for this category, no more "training" imagery can be ordered. 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": -1
available The sqkm and cost allocation for the category or in total. Examples are provided for the specific available fields.
available_sqkm The remaining total sqkms available for the account or user. "available_sqkm": 2999732.8
available_fresh_cost The remaining allocation available for fresh imagery, in dollars. "available_fresh_cost": 448
available_standard_cost The reamining allocation available for standard imagery, in dollars. "available_standard_cost": -1
available_training_cost The remaining allocation available for training imagery, in dollars. "available_training_cost": -1
available_total_cost The total remaining imagery allocation available, in dollars. "available_total_cost": 98888.1
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. Examples are shown for the specific fields below.
start_date The start date for the usage period. If no date is specified in the request, the contract start date is used. "start_date": "2021-06-01"
end_date The end date for the usage period. If no date is specified in the request, the contract end date is used. "end_date": "2021-07-28"|
links HTTP link to the details for the account. Requires ARD authentication. "links": {"account": "https://ard.maxar.com/api/v1/admin/account/9999712307605640000"
response_timestamp The date and time the usage request was made. "response_timestamp": "2021-07-28T20:12:24Z"

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.

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. 999712307605640000

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. 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 example shows the results of an asynchronous usage request with a specified date range and the 'show_users' field value set to "true".

{
    "id": "5963959603229706895",
    "account_id": "55237",
    "usage_as_of": "2022-07-12T21:43:08Z",
    "status": "SUCCEEDED",
    "links": {
        "account": "https://ard.maxar.com/api/v1/admin/account/55237"
    },
    "duration": "0:00:00.995151",
    "usage_period": {
        "start_date": "2022-06-01",
        "end_date": "2022-07-12T23:59:59Z"
    },
    "usage": {
        "area": {
            "fresh_imagery_sqkm": 81.7,
            "standard_imagery_sqkm": 0,
            "training_imagery_sqkm": 6.3,
            "total_imagery_sqkm": 88.0,
            "estimate": false
        },
        "cost": {
            "fresh_imagery_cost": 5000,
            "standard_imagery_cost": 0,
            "training_imagery_cost": 300,
            "total_imagery_cost": 5300,
            "estimate": false
        },
        "limits": {
            "limit_sqkm": -1,
            "fresh_imagery_fee_limit": -1,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
            "annual_subscription_fee_limit": 10000.0
        },
        "available": {
            "available_sqkm": -1,
            "fresh_imagery_balance": -1,
            "standard_imagery_balance": -1,
            "training_imagery_balance": -1,
            "total_imagery_balance": 4700
        }
    },
    "users": [
        {

            "area": {
                "fresh_imagery_sqkm": 0,
                "standard_imagery_sqkm": 0,
                "training_imagery_sqkm": 0,
                "total_imagery_sqkm": 0,
                "estimate": false
            },
            "cost": {
                "fresh_imagery_cost": 5000,
                "standard_imagery_cost": 0,
                "training_imagery_cost": 300,
                "total_imagery_cost": 5300,
                "estimate": false
            },
            "limits": {
                "limit_sqkm": -1,
                "fresh_imagery_fee_limit": -1,
                "standard_imagery_fee_limit": -1,
                "training_imagery_fee_limit": -1,
                "annual_subscription_fee_limit": -1
            },
            "available": {
                "available_sqkm": -1,
                "fresh_imagery_balance": -1,
                "standard_imagery_balance": -1,
                "training_imagery_balance": -1,
                "total_imagery_balance": 4700
            },
            "id": "faaec512-544e-4438-8be2",
            "name": "Shea Barnes"
        }
    ],
    "response_timestamp": "2022-07-12T21:43:50Z"
}

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.

More Documents

Account Usage Guide

Back to top