Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/statistical/) # Statistical API The Statistical API enables you to get statistics calculated based on satellite imagery without having to download images. In your Statistical API request, you can specify your area of interest, time period, evalscript and which statistical measures should be calculated. The requested statistics are returned in the API response. Using Statistical API you can [calculate the percentage of cloudy pixels for a given area of interest and time period](https://docs.planet.com/develop/apis/statistical/examples.md#percentage-of-cloudy-pixels-for-selected-area-of-interest), or [calculate mean, standard deviation, and histogram of band values for a parcel in a given time period](https://docs.planet.com/develop/apis/statistical/examples.md#statistics-histogram-and-percentiles-for-one-single-band-output). Find more examples [here](https://docs.planet.com/develop/apis/statistical/examples.md). To become familiar with the Statistical API, check the [Requests Builder](https://insights.planet.com/analyze/requests-builder/), and our [API reference](https://docs.planet.com/develop/apis/statistical/reference.md). ## General Approach Based on parameters specified by users in requests (for example, area of interest, time range, evalscript) the Statistical API processes satellite data in a similar way as the Processing API. Instead of returning images, it calculates requested statistics and returns the results in a json format. ## Deployments Statistical API is available on AWS (2 regions). The API's endpoint depends on the chosen deployment as specified in the following table. | Deployment | API endpoint | Region | | ------------------ | --------------------------------------------------------- | ------------ | | AWS EU (Frankfurt) | | eu-central-1 | | AWS US (Oregon) | | us-west-2 | ## Rate Limiting The Statistical API follows the general rate limiting policies described in [Rate Limiting](https://docs.planet.com/develop/rate-limiting.md). ## Data Sources Restrictions All data sources must be from the same deployment where the request is made. ## Statistical API and Evalscripts All general rules for building [evalscripts](https://docs.planet.com/develop/evalscripts.md) apply. However, there are some specifics when using evalscripts with the Statistical API: * The `evaluatePixel()` function **must**, in addition to other outputs, always return `dataMask` output. This output defines which pixels are excluded from calculations. For more details and an example, see [here](https://docs.planet.com/develop/apis/statistical.md#exclude-pixels-from-calculations-datamask-output). * The default value of `sampleType` is `FLOAT32`. * The `output.bands` parameter in the `setup()` function can be an array. This makes it possible to specify custom names for the output bands and different output `dataMask` for different outputs. See an example [here](https://docs.planet.com/develop/apis/statistical/examples.md#multiple-outputs-with-different-datamasks-multi-band-output-with-custom-bands-names-and-different-histogram-types). ## Features ### Split the Requested `timeRange` into Multiple Time Intervals The Statistical API supports requesting statistics for multiple time intervals with only one request. For example, requesting the `aggregationInterval` and `timeRange` as: * JSON ``` ... "timeRange": { "from": "2020-06-01T00:00:00Z", "to": "2020-07-31T00:00:00Z" }, "aggregationInterval": { "of": "P10D" } ... ``` Returns the requested statistics calculated for multiple 10-day intervals, see this [example](https://docs.planet.com/develop/apis/statistical/examples.md#statistics-for-one-single-band-output-for-two-months-with-10-days-aggregation-period). The aggregation intervals should be at least one day long (for example, "P5D", "P30D"). You can only use a period or a time designator and not both. If a `timeRange` is not divisible by an `aggregationInterval`, the last ("not full") time interval will be dismissed by default (`SKIP` option). You can instead set the `lastIntervalBehavior` to `SHORTEN` (shortens the last interval so that it ends at the end of the provided time range) or `EXTEND` (extends the last interval over the end of the provided time range so that all the intervals are of equal duration). note The data is mosaicked for each of the time intervals (as defined with the `mosaicking` parameter in an evalscript) before the statistics are calculated. To calculate statistics over time (for example, the maximum NDVI value in a month), you should set mosaicking to ORBIT or TILE and calculate the required value in an evalscript, see this [example](https://docs.planet.com/develop/apis/statistical/examples.md#statistics-of-maximum-monthly-ndvi-for-a-parcel-in-2020). While mosaicking SIMPLE can be used to generate a single image per interval, it is not suitable for aggregating statistics over longer time intervals. For short intervals (e.g., daily requests), it may still produce valid results. ### Histogram Requesting histograms is optional, and a variety of histogram customisations are available. You can specify any of the following: * arbitrary `bins` * width of bins `binWidth` * number of bins `nBins` Along with `binWidth` and `nBins`, you can also provide values for `lowEdge` and/or `highEdge` parameters. Otherwise, their default values will be used, which correspond to `min` and `max` statistics for a particular output band. [This example](https://docs.planet.com/develop/apis/statistical/examples.md#multiple-outputs-with-different-datamasks-multi-band-output-with-custom-bands-names-and-different-histogram-types) demonstrates all three options. ### Percentile Calculations It is possible to get values for any percentile. For example, to get values for 33%, 75%, and 90% percentiles, add the **percentiles** parameter to your requests as: * JSON ``` ... { "percentiles": { "k": [33, 75, 90] } } ... ``` See also this [example](https://docs.planet.com/develop/apis/statistical/examples.md#statistics-histogram-and-percentiles-for-one-single-band-output). ### Exclude Pixels from Calculations (dataMask output) It is possible to exclude specific pixels from the calculation of the statistics. The most common use cases are excluding no data and cloudy pixels. With the Statistical API, this is achieved by defining a special output called **dataMask**. This output should have a value of "0" assigned for the pixels that should be excluded from the calculations, and a value of "1" elsewhere. The values of the **dataMask** output are defined by the user in an evalscript. For an illustrative example of excluding water pixels from statistics of NDVI, see this [example](https://docs.planet.com/develop/apis/statistical/examples.md#statistics-of-maximum-monthly-ndvi-for-a-parcel-in-2020). note The Statistical API does not automatically exclude the no data pixels from calculating the statistics. We recommend that you always exclude those unless there is a good reason not to. This is especially important when you are requesting statistics for a polygon, as it will ensure that pixels outside of the polygon (and inside of the bounding box) are excluded. To exclude no data pixels, you need to pass the input `dataMask` band to the `dataMask` output. For example: * javascript ``` function evaluatePixel(samples) { return { ..., dataMask: [samples.dataMask] } } ``` All evalscripts in the examples [here](https://docs.planet.com/develop/apis/statistical/examples.md) exclude no data pixels. ### Geometry Pixel Count The response includes a `geometryPixelCount` field that represents the number of pixels intersecting the request geometry. This is useful for understanding the spatial extent of your area of interest in pixel terms, regardless of data availability. `geometryPixelCount` is related to, but distinct from, the per-band `sampleCount` and `noDataCount` statistics: * `sampleCount` is the total number of pixels in the bounding box of the request geometry. * `noDataCount` is the number of pixels excluded from calculations by the `dataMask` output (no data pixels, pixels outside the request geometry, pixels excluded by user). * `geometryPixelCount` is the number of pixels intersecting the request geometry, independent of data availability or `dataMask`. tip When there is data for every pixel in the geometry and the evalscript passes the input `dataMask` directly to the output without modification, the only pixels counted as noData are those outside the geometry, which means `geometryPixelCount = sampleCount - noDataCount`. When some pixels within the geometry have `dataMask=0` (e.g., due to clouds or missing data), `noDataCount` increases accordingly. You can track how many geometry pixels have `dataMask=0` per interval by computing `geometryPixelCount - (sampleCount - noDataCount)`. The following diagram illustrates how `sampleCount`, `noDataCount`, and `geometryPixelCount` relate to the request geometry and its bounding box. ![Statistical API Pixel Counts](/develop/apis/statistical/pixel-counts.svg) Statistical API Pixel Counts ### Multiple Outputs and Multi-Band Outputs Statistics can be requested for multiple outputs. This is useful when we need to use different dataMasks or different sampleTypes for each output. Additionally, each output can have multiple bands. It is possible to request different statistics for each band and for each output. [This example](https://docs.planet.com/develop/apis/statistical/examples.md#multiple-outputs-with-different-datamasks-multi-band-output-with-custom-bands-names-and-different-histogram-types) demonstrates how to do all of this. ## Additional Resources ## Additional Resources [Planet University: Extracting Statistics From Imagery on the Planet Insights Platform](https://university.planet.com/extracting-statistics-from-imagery-on-the-planet-insights-platform/2124090/scorm/15ejmo1augv83) [Planet University course discussing the Statistical API and how calculate statistics from satellite imagery, without having to download the imagery.](https://university.planet.com/extracting-statistics-from-imagery-on-the-planet-insights-platform/2124090/scorm/15ejmo1augv83)