Search Stats

last updated: March 18, 2024

Search Stats gives you a quick way to determine the number of items which meets your search specifications. This endpoint allows you to specify a time interval and search filter and returns a histogram of item counts, grouped by interval, which match your filter criteria.

This endpoint can be used to answer questions such as:

  • How does availability of imagery with less than 10 percent cloud cover change seasonally in Jakarta?
  • How deep is Planet’s 2019 SkySat archive over Shanghai?
  • How many items which meet my search criteria are published each hour?

Request Body

The body of a stats request must include a search filter and time interval.

  • filter (required): is your structure search criteria; you can read more on supported filters on our Search Filters page
  • interval (required): specifies the time interval of the returned histogram buckets; ”hour”, ”day”, ”week”, ”month”, or ”year”
  • item_types (required): limits results by item type(s)
  • utc_offset (optional): offsets the start time of your histogram buckets to match your desired timezone (ISO 8601 UTC offset, ex. +1h or -8h)

Example Request

POST https://api.planet.com/data/v1/stats

{
    "item_types": [
        "PSScene"
    ],
    "interval": "day",
    "filter": {  
       "type":"AndFilter",
       "config":[  
           {  
            "type":"DateRangeFilter",
            "field_name":"acquired",
             "config":{  
                "gte":"2022-03-01T00:00:00Z",
                "lte":"2022-03-07T00:00:00Z"
             }
          },
          {
             "type": "AssetFilter",
             "config": [
                "ortho_analytic_8b"
             ]
          }
       ]
    },
    "utc_offset": "-8h"
}

Request for counts of all PlanetScope 4-band items with analytic_sr assets acquired between February 1, 2020 and February 7, 2020, grouped by day in Pacific Standard Time.

Response Schema

The stats response returns an array of stats bucket results, each of which include a bucket start time and count of items which meet the request’s filter criteria.

Example response

{
    "buckets": [
        {
            "count": 178479,
            "start_time": "2022-02-28T16:00:00.000000Z"
        },
        {
            "count": 226455,
            "start_time": "2022-03-01T16:00:00.000000Z"
        },
        {
            "count": 242567,
            "start_time": "2022-03-02T16:00:00.000000Z"
        },
        {
            "count": 243330,
            "start_time": "2022-03-03T16:00:00.000000Z"
        },
        {
            "count": 230189,
            "start_time": "2022-03-04T16:00:00.000000Z"
        },
        {
            "count": 219070,
            "start_time": "2022-03-05T16:00:00.000000Z"
        },
        {
            "count": 38622,
            "start_time": "2022-03-06T16:00:00.000000Z"
        }
    ],
    "interval": "day",
    "utc_offset": "-8h"
}

Response includes daily histogram buckets and counts of items which meet the request’s filter criteria. The time zone of each bucket has been adjusted to Pacific Standard Time (with a UTC offset of -8h).

Rate this guide: