Skip to content

Temporal Queries

Last Updated: April 4, 2022

Maxar ARD's temporal fields let you search for time-series imagery with precision and flexibility. Queries can use different combinations of temporal fields to tune results to exactly the imagery you need.

Example search request with temporal fields

This example uses the datetime and query:collect_day fields. The request body can be used in a Select or Tile Metadata request.

{
    "datetime": "2017/2021",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 3,
    "query": {
        "collect_day": {
            "or": [{
                    "gte": "12"
                },
                {
                    "lte": "17"
                }
            ]
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 15
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }

}

Temporal fields

Each of the fields below can accept a single value or a range. The datetime field accepts a range for the value of the timestamp, in ISO-8601 format. The query:collect fields accept two single values using operators.

field description example
datetime Query for the value of the imagery timestamp by ISO-8601 formatted date, date and time, or date range. "datetime": "2020-07-01T10:00:00Z/2021-01-25T20:00:00Z"
query:collect_month Query for a specific month or grouping of months using single values with an operator. "collect_month": {"in": ["12", "01", "02"]}
query:collect_month_day Query for month and day or a month and day range using single values with an operator. "collect_month_day": {"or": [{"gte": "12-21"},{"lte": "03-20"}]
query:collect_day Query for imagery captured on a specified day or range of days. "collect_day": {"or": [{"gte": "12"},{"lte": "17"}

Operators

To search for imagery within a range when using the query:collect fields, use two specific dates with a search operator. You'll use query operators to create the range.

Example operators

operator definition example
between Search for results between two numbers. The "between" operator requires dates to be ordered earliest to latest. "collect_month_day": {"between": ["09-23", "12-21"]}
eq Search for results that match a single value. collect_day": {"eq": "10"}
gt greater than "gt": "12-21"
gte greater than or equal to "gte": "12-21"
lt less than "lt": "03-20"
lte less than or equal to "lte": "03-20"
in Search for results that match any value in the group. "collect_month": {"in": ["03", "04", "05"]}
or Search for results that match one of the clauses in query. The "or" operator doesn't require values to be ordered earlier to later. "collect_month_day": {"or": [{"gte": "12-21"},{"lte": "03-20"}]}

For example, to query for imagery between September 23 and December 21, you can use the "between" operator to get results. The "between" operator only works when the first value in the range is lower than the second. It requires dates to be ordered earliest to latest.

"collect_month_day": {"between": ["09-23", "12-21"]}
To create a range where the first value is later than the second, use the "or" operator instead. You can use the "or" operator to create a range of values in any order. The values in the list require a query operator.

"collect_month_day": {
            "or": [
                {"gte": "12-21"},
                {"lte": "03-20"}
            ]
        }

Date and time field

The datetime field lets you query for imagery within an AOI by date, date and time, date range, or an open-ended date range. This field is always optional, and requires ISO-8601 formatted values.

query type example
date "datetime": "2020-07-01"
date and time "datetime": "2020-07-01T00:00:00Z"
date range "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z"
date range with open end date "datetime": "2020-07-01T00:00:00Z/.."
date range with open start date "datetime": "../2021-01-25T00:00:00Z"
date range by year "datetime": "2015/2021"

Note: A query for a year range like "2015/2021" will return imagery from January 1, 2015 through December 31, 2020.

Month, day, and month-day query fields

Temporal data can also be queried by:

  • month

  • month and day

  • day

query field example
query:collect_month "collect_month": {"in": ["12", "01", "02"]}
query:collect_month_day "collect_month_day": {"or": [{"gte": "12-21"},{"lte": "03-20"}
query:collect_day "collect_day": {"or": [{"gte": "12"},{"lte": "17"}

This example combines the datetime field and the query:collect_month_day field to look for imagery captured between 12-21 and 02-03, starting with 2017 and ending December 31, 2020 (excluding 2021).

Note: If your collect fields don't intersect the date range you supply, no results will be returned.

{
    "datetime": "2017/2021",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 3,
    "query": {
        "collect_month_day": {
            "or": [{
                    "gte": "12-21"
                },
                {
                    "lte": "02-03"
                }
            ]
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }
}

This example looks for imagery collected in December (12), January (01), and February (02) in every year in the imagery archive.

{
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 3,
    "query": {
        "collect_month": {"in": ["12", "01", "02"]},
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }
}

Seasonal Queries

Seasonal queries can be constructed using the query:collect fields. Examples of seasonal queries are shown below.

Meteorological Seasons (month groupings)

Northern Hemisphere, Temperate Zone

season query clause
Winter "collect_month": {"in": ["12", "01", "02"]}
Spring "collect_month": {"in": ["03", "04", "05"]}
Summer "collect_month": {"in": ["06", "07", "08"]}
Autumn "collect_month": {"in": ["09", "10", "11"]}

Northern Hemisphere, Tropical Zone

season query clause
Dry "collect_month": {"in": ["11", "12", "01", "02", "03", "04"]}
Wet "collect_month": {"in": ["05", "06", "07", "08", "09", "10"]}

Southern Hemisphere, Temperate Zone

season query clause
Winter "collect_month": {"in": ["06", "07", "08"]}
Spring "collect_month": {"in": ["09", "10", "11"]}
Summer "collect_month": {"in": ["12", "01", "02"]}
Autumn "collect_month": {"in": ["03", "04", "05"]}

Southern Hemisphere, Tropical Zone

season query clause
Wet "collect_month": {"in": ["11", "12", "01", "02", "03", "04"]}
Dry "collect_month": {"in": ["05", "06", "07", "08", "09", "10"]}

India Meteorological Department

season query clause
Winter "collect_month": {"in": ["12", "01", "02"]}
Summer/Pre-monsoon "collect_month": {"in": ["03", "04", "05"]}
Monsoon/Rainy "collect_month": {"in": ["06", "07", "08", "09"]}
Autumn/Post-monsoon "collect_month": {"in": ["10", "11"]}

Astronomical Seasons (month-day ranges)

Northern Hemisphere

season query clause
Winter "collect_month_day": {"or": [{"gte": "12-21"},{"lte": "03-20"}]}
Spring "collect_month_day": {"between": ["03-20", "06-21"]}
Summer "collect_month_day": {"between": ["06-21", "09-23"]}
Autumn "collect_month_day": {"between": ["09-23", "12-21"]}

Southern Hemisphere

season query clause
Winter "collect_month_day": {"between": ["06-21", "09-23"]}
Spring "collect_month_day": {"or": [{"gte": "09-23"},{"lte": "12-21"}]}
Summer "collect_month_day": {"between": ["09-23", "12-21"]}
Autumn "collect_month_day": {"between": ["03-20", "06-21"]}

Using Month and day fields with image age category.

A Maxar ARD subscription includes different pricing for three image age categories. You can combine image age category and query:collect fields to get imagery by month, month-day, or day in a specified image age category.

For example, if you want to search for imagery collected in your AOI from March 20 to June 21, and you only want "training" data, you can send a request like this:

{
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "image_age_category": ["training"],
    "stack_depth": 3,
    "query": {
        "collect_month_day": {
            "between": ["03-20", "06-21"]
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }
}

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

More Resources

Selecting Imagery

Query for Cell Metadata

Area of Interest (AOI) Guidelines

Back to top