# Planet Documentation
> Generated LLMS index and full text for Planet documentation.
- [Planet Documentation](https://docs.planet.com/index.md)
## data
- [Data Catalog](https://docs.planet.com/data.md): Analytic Feeds
- [Analytic Feeds](https://docs.planet.com/data/analytic-feeds.md)
- [Aircraft Detection](https://docs.planet.com/data/analytic-feeds/aircraft-detection.md): Detect and monitor aircraft on airfields and tarmacs.
- [Technical Specification](https://docs.planet.com/data/analytic-feeds/aircraft-detection/techspec.md): Key Product Features
- [Road & Building Change Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md): Detect changes in roads and buildings infrastructure.
- [Technical Specification](https://docs.planet.com/data/analytic-feeds/road-building-change-detection/techspec.md): Key Product Features
- [Vessel Detection](https://docs.planet.com/data/analytic-feeds/vessel-detection.md): Detect and monitor vessel over maritime areas.
- [Technical Specification](https://docs.planet.com/data/analytic-feeds/vessel-detection/techspec.md): Planet’s Vessel Detection and Classification products leverage advanced machine learning and computer vision techniques to identify maritime activity over vast areas of interest. Derived from high-frequency PlanetScope imagery, this solution provides automated, oriented bounding box detections of vessels, enabling customers to monitor maritime domains, secure coastlines, and analyze economic activity with precision.
- [Area Monitoring](https://docs.planet.com/data/area-monitoring.md): Sentinel Hub is a multi-spectral, temporal satellite imagery service for real-time processing of large remote sensing datasets.
- [Applications](https://docs.planet.com/data/area-monitoring/applications.md): Applications
- [Admin Application](https://docs.planet.com/data/area-monitoring/applications/admin-application.md): Admin Application
- [Area Monitoring Application](https://docs.planet.com/data/area-monitoring/applications/area-monitoring-browser.md): Area Monitoring Application
- [Expert Judgement Application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md): Expert Judgement Application
- [Geotagged Photo Application](https://docs.planet.com/data/area-monitoring/applications/geotagged-photo-application.md): Geotagged Photo Application
- [Common](https://docs.planet.com/data/area-monitoring/common.md): Details of commonly used properties and objects
- [Marker Service API](https://docs.planet.com/data/area-monitoring/marker-service-api.md): Documentation on the structure of the markers's data served through API
- [Markers](https://docs.planet.com/data/area-monitoring/markers.md): Markers
- [Bare-Soil Marker](https://docs.planet.com/data/area-monitoring/markers/bare-soil-marker.md): Bare-Soil Marker
- [Bare-Soil Marker Examples](https://docs.planet.com/data/area-monitoring/markers/bare-soil-marker/examples.md): Bare-Soil Marker Examples
- [Binary Land-Cover Marker](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker.md): Binary Land-Cover Marker
- [Binary Land-Cover Marker Examples](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker/examples.md): Binary land-cover marker examples
- [Crop and Land-Use Markers](https://docs.planet.com/data/area-monitoring/markers/crop-and-land-use-markers.md): Crop and Land-Use Markers
- [Crop and Land-Use Marker Examples](https://docs.planet.com/data/area-monitoring/markers/crop-and-land-use-markers/examples.md): Crop and land-use marker examples
- [Field Delineation](https://docs.planet.com/data/area-monitoring/markers/field-delineation.md): Field Delineation
- [Greening and Harvest Marker](https://docs.planet.com/data/area-monitoring/markers/greening-harvest-marker.md): Greening and Harvest Marker
- [Greening and Harvest Marker Examples](https://docs.planet.com/data/area-monitoring/markers/greening-harvest-marker/examples.md): Greening and Harvest Marker Examples
- [Homogeneity Marker](https://docs.planet.com/data/area-monitoring/markers/homogeneity-marker.md): Homogeneity Marker
- [Homogeneity Marker Examples](https://docs.planet.com/data/area-monitoring/markers/homogeneity-marker/examples.md): Homogeneity Marker Examples
- [Mowing Marker](https://docs.planet.com/data/area-monitoring/markers/mowing-marker.md): Mowing Marker
- [Mowing Marker Examples](https://docs.planet.com/data/area-monitoring/markers/mowing-marker/examples.md): Mowing Marker Examples
- [Ploughing Marker](https://docs.planet.com/data/area-monitoring/markers/ploughing-marker.md): Ploughing Marker
- [Similarity and Euclidian Distance Marker](https://docs.planet.com/data/area-monitoring/markers/similarity-and-euclidian-distance-marker.md): Similarity and Euclidian Distance Marker
- [Similarity and Euclidian Distance Marker Examples](https://docs.planet.com/data/area-monitoring/markers/similarity-and-euclidian-distance-marker/examples.md): Similarity and Euclidian Distance Marker Examples
- [References](https://docs.planet.com/data/area-monitoring/references.md): References
- [Signal Processing](https://docs.planet.com/data/area-monitoring/signal-processing.md): Signal Processing
- [Traffic Light System](https://docs.planet.com/data/area-monitoring/traffic-light-system.md): Traffic Light System
- [Traffic Light System Examples](https://docs.planet.com/data/area-monitoring/traffic-light-system/examples.md): Traffic Light System Examples
- [Videos](https://docs.planet.com/data/area-monitoring/videos.md): Videos
- [Visualizations](https://docs.planet.com/data/area-monitoring/visualizations.md): Documentation for visualization of area monitoring results
- [Communication](https://docs.planet.com/data/area-monitoring/visualizations/communication.md): Documentation for Communication React component
- [Marker Scores](https://docs.planet.com/data/area-monitoring/visualizations/marker-scores.md): Documentation for Marker Scores React component
- [Markers Summary](https://docs.planet.com/data/area-monitoring/visualizations/markers-summary.md): Documentation for Markers Summary React component
- [Observation](https://docs.planet.com/data/area-monitoring/visualizations/observation.md): Documentation for Observation React component
- [Photo Task Creator](https://docs.planet.com/data/area-monitoring/visualizations/photo-task-creator.md): Documentation for Photo Task Creator React component
- [Pixel Mowing](https://docs.planet.com/data/area-monitoring/visualizations/pixel-mowing.md): Documentation for visualization of pixel mowing marker results
- [Signal Marker Visualization](https://docs.planet.com/data/area-monitoring/visualizations/signal-marker-visualization.md): Documentation for Signal Marker Visualization React component
- [Timelapse](https://docs.planet.com/data/area-monitoring/visualizations/timelapse.md): Documentation for Timelapse React component
- [Planet Imagery](https://docs.planet.com/data/imagery.md)
- [Analysis-Ready PlanetScope](https://docs.planet.com/data/imagery/arps.md): Information about Analysis-Ready PlanetScope
- [Analysis-Ready PlanetScope Sandbox Data](https://docs.planet.com/data/imagery/arps/sandbox.md)
- [Technical Specification v1.0](https://docs.planet.com/data/imagery/arps/techspec/v1-0-0.md):
Publicly available flight data is incomplete, often omitting sensitive military movements, private flights, and activity in conflict zones. This leaves analysts with significant blind spots. The traditional alternative — manual analysis of satellite imagery — is slow, expensive, and impossible to scale across thousands of airfields. As a result, monitoring has been limited to a select number of locations with sporadic coverage, providing only isolated snapshots in time rather than a comprehensive view.
In a world of rapid geopolitical change, relying on incomplete data or slow, manual processes means missing critical indicators and failing to see the bigger picture of global movements.
### Automated, Global Monitoring From Space
Planet Aircraft Detection transforms airfield monitoring from a tedious, manual task into an automated, scalable solution. By applying a sophisticated machine learning model to our global, near-daily PlanetScope® imagery, we provide **automated detections of aircraft at rest on airfields across the entire world.**
This represents the first-ever attempt at global detection of large aircraft on a near-daily basis from satellite imagery. Instead of sporadic checks on a few known airfields, you gain a persistent, foundational layer of intelligence over any airport or airstrip of interest. Our solution enables pattern-of-life analysis, allowing you to establish baseline activity, automatically detect anomalies, and receive alerts on significant changes — empowering analysts of all backgrounds to move faster and with greater confidence.
Planet's ability to systematically scan airfields around the globe unlocks new analytical capabilities for defense, intelligence, and commercial organizations.
### Defense and Intelligence Analysis
For defense and intelligence agencies, understanding an adversary’s force posture and movements is paramount. Public flight data is often ineffective in sensitive or denied areas. Planet Analytic Feeds for Aircraft Detection provides a reliable, non-cooperative method for monitoring military airbases.
* **Track fleet deployments:** Count aircraft at an airbase and see where they reappear, providing insight into strategic movements.
* **Establish baselines and detect anomalies:** Automatically monitor airfields to establish normal patterns and receive alerts when unusual numbers or types of aircraft arrive or depart.
* **Enhance situational awareness:** Provide objective, evidence-based intelligence on global military activity without relying on public reporting.
**Planet’s Unique Approach.** Our near-daily coverage of Earth's landmass means you are no longer restricted to monitoring a handful of known sites. You can monitor all of them, ensuring you never miss a critical development.
### Economic Intelligence and Trend Analysis
The movement of commercial and cargo aircraft is a useful proxy for economic activity. Analysts can leverage our feed to gain a competitive edge and validate other economic indicators.
* **Predict economic trends:** Monitor the volume of cargo and executive jets at key airports to gauge supply chain activity and corporate travel.
* **Assess event impact:** Quantify the influx of air traffic for major global events like sporting championships or political summits to measure their economic impact.
* **Improve market models:** Integrate a novel, global dataset into economic models for more accurate forecasting.
**Planet’s Unique Approach.** The sheer scale of our automated detection provides a macro-level view of economic activity that is impossible to replicate with other sources, giving commercial analysts an unprecedented data source.
## API Information
| API | Available | Notes |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
| Data API | ✅ | Customers can use the Data API to query imagery associated with an aircraft detection analytic subscription |
| Orders API | ✅ | Customers can use the Orders API to order imagery associated with an aircraft detection analytic subscription |
| Subscriptions API | ✅ | Customers can use the Subscriptions API to subscribe to imagery associated with an aircraft detection analytic subscription |
| Analytics API | ✅ | The Analytics API is used to query aircraft detection results |
| Basemaps API | ❌ | |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/analytic-feeds/aircraft-detection/techspec/)
# Technical Specification
### Key Product Features
With Planet Analytic Feeds for Aircraft Detection, you receive an end-to-end solution designed for immediate integration and analysis.
* **Full imagery access.** You receive full access to the underlying PlanetScope imagery within your area of interest, including the ability to stream image tiles or download GeoTIFFs for visual verification, detailed analysis, and reporting. Our imagery provides clear, 3.7 m resolution evidence.
* **Automated aircraft detections.** Detections for aircraft ≥ 20 m in length or wingspan are delivered as GeoJSON feature collections via our Analytics API or visualized in our Feed Viewer. This data is ready for immediate integration into your existing GIS platforms and analytical workflows.
### Methodology
Our model is built on a foundation of cutting-edge machine learning techniques and a unique approach to data labeling, ensuring reliable performance at a global scale. We utilize a deep learning object detection model optimized to run efficiently on our medium-resolution PlanetScope imagery. This allows us to analyze thousands of airfields daily to identify aircraft at rest on tarmacs and runways.
#### Unique Training Data Approach
To achieve high accuracy, we developed an innovative labeling process. We use high-resolution SkySat® imagery captured within three minutes of a PlanetScope image. Our expert labelers identify aircraft in the crisp SkySat imagery, and those high-fidelity labels are then transferred to the corresponding PlanetScope scene. This unique multi-resolution approach ensures our model is trained on the most accurate ground truth data possible.
#### Robust Training Data
The model was trained on a curated dataset of over 15,000 labels derived from concurrent pairs of SkySat and PlanetScope images. This dataset has a broad geographic and temporal distribution, covering hundreds of airfields worldwide across multiple years and all seasons. This diversity ensures the model is robust and performs reliably in a wide variety of real-world conditions. It is continually updated and expanded to reduce model drift and address issues as they arise.
#### Reliable Performance
The model is rigorously tested against a globally distributed test set, achieving a high level of accuracy for detecting aircraft ≥20 meters.
* **Precision: 0.87** - This measures the accuracy of our detections. A high precision score means that when we identify an aircraft, it is highly likely to be a true aircraft, minimizing false alarms.
* **Recall: 0.78** - This measures the completeness of our detections. A high recall score means we successfully identify a high percentage of the actual aircraft vessels present in the imagery.
* **F1-Score: 0.82** - This provides a single, balanced measure of the model's overall accuracy by combining both precision and recall.
### Delivery Mechanisms
Results are available via the Analytics API and Feed Viewer. For more details please see:
* **[Analytics API](https://docs.planet.com/develop/apis/analytics.md)**
* **[Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md)**
### Full Metadata Reference
#### Feature-level Fields
| Property | Format | Example | Definition |
| -------- | --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| created | ISO 8601 DateTime | "2026-02-03T19:02:45.270966Z" | The timestamp when the feature was created in the system |
| geometry | GeoJSON Geometry | `{"type": "Polygon", "coordinates": [...]}` | The geographic polygon defining the location of the detected change |
| id | UUID | "17f21835-93c4-4664-b2ef-c2f57f5809a5" | The unique identifier for the feature |
| links | Array of Link Objects | `[{"href": "...", "rel": "self", "type": "..."}]` | Array of related resources including visual tiles, quads, process info, and observation data |
| type | String | "Feature" | The GeoJSON feature type |
#### Properties
| Property | Format | Example | Definition |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| bbox\_area\_m2 | Float | 1292.76 | The area of the detected aircraft's bounding box in square meters |
| bbox\_diagonal\_m | Float | 51.09171557111779 | The diagonal length of the aircraft bounding box in meters |
| bbox\_length\_m | Float | 38.55 | The estimated length of the aircraft in meters |
| bbox\_width\_m | Float | 33.53 | The estimated width of the aircraft in meters |
| category | String | "aircraft" | The category of the detected object |
| model\_id | String | "toothless\_aircraft" | The identifier of the detection model used |
| model\_version | String | "toothless-aircraft-ps-v1.2.0" | The version of the detection model used |
| object\_class\_label | String | "aircraft" | The classification label assigned to the detected object |
| observed | ISO 8601 DateTime | "2026-02-09T08:09:38.541005Z" | The timestamp when the aircraft was observed |
| score | Float | 0.805 | The model's confidence in the detection accuracy (0-1 scale, where higher values indicate greater certainty) |
| source\_asset\_type | String | "ortho\_visual" | The type of asset used for detection |
| source\_cloud\_cover | Float | 0.83 | The cloud cover percentage in the source imagery (0-1 scale) |
| source\_extent | WKT Polygon | "POLYGON ((51.1546410707396575 35.7877539840997514, 51.1144425763138770 35.6347767140370664, 51.4287071306998484 35.5791382492902173, 51.4695444327112881 35.7324398323834131, 51.1546410707396575 35.7877539840997514))" | The geographic extent of the source imagery as a polygon |
| source\_image\_mean\_gsd | Float | 3.3 | The mean ground sample distance of the source imagery in meters |
| source\_item\_id | String | "20260209\_080938\_54\_24fd" | The unique identifier of the source imagery item |
| source\_item\_type | String | "PSScene" | The type of source imagery item |
| source\_quality\_category | String | "standard" | The quality category of the source imagery |
| source\_sun\_azimuth\_angle | Float | 167.5 | The azimuth angle of the sun in the source imagery in degrees |
| source\_sun\_elevation\_angle | Float | 38.8 | The elevation angle of the sun in the source imagery in degrees |
In an increasingly dynamic world, waiting for reports is no longer an option. Planet Aircraft Detection provides the persistent, global awareness needed to understand airfield activity as it happens. Move beyond manual analysis and incomplete data to a new paradigm of automated insight. See the full picture, detect critical changes first, and act with the speed and confidence that only Planet can deliver.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/analytic-feeds/road-building-change-detection/)
# Road & Building Change Detection
Keeping up to date with human development is a daunting task, especially when scanning across enormous country-wide areas. Government agencies throughout the world are challenged to ensure protected areas remain untouched and that development only takes place when it is properly permitted. But even with the growth of satellite observations, identifying new activity in massive archives of data is costly and time-intensive.
Planet’s Road & Building Change Detection products point users to where development is taking place across country-wide areas on a weekly basis, helping them understand exactly how and where the places they care most about are evolving. Drawing on Planet’s daily scan of the Earth, analysts can look at activities as they unfold without the burden of sifting through huge volumes of imagery.
### Permit Enforcement
New road construction in southeastern New Mexico detected in the Analytics Feed Viewer.
The New Mexico State Land Office compares Road Change Detections with permit applications to determine if development has taken place prior to permit approval. They were able to generate an estimated $1M in revenue from permit violations discovered using Road Change Detection.
### Monitoring Protected Areas
New road construction in the Misiones Province of eastern Argentina detected in the Analytics Feed Viewer.
Policia Federal of Brazil leverages Road & Building Change Detections to draw their attention to where and when development is taking place within protected forested areas.
## API Information
| API | Available | Notes |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Data API | ❌ | Road & Building Change Detection runs on a weekly or monthly cadence, providing weekly or monthly visual mosaics alongside change detections. The Data API supports querying scene information only. |
| Orders API | ✅ | Road & Building Change Detection runs on a weekly or monthly cadence, providing weekly or monthly visual mosaics alongside change detections. The Orders API supports ordering mosaic quads. |
| Subscriptions API | ❌ | Road & Building Change Detection runs on a weekly or monthly cadence, providing weekly or monthly visual mosaics alongside change detections. The Subscriptions API does not currently support subscriptions for mosaic quads. |
| Analytics API | ✅ | The Analytics API is used to query Road & Building Change Detection results. |
| Basemaps API | ✅ | Road & Building Change Detection runs on a weekly or monthly cadence, providing weekly or monthly visual mosaics alongside change detections. The Basemaps API supports querying and delivering mosaic quads. |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/analytic-feeds/road-building-change-detection/techspec/)
# Technical Specification
### Key Product Features
With Planet Analytic Feeds for Road and Building Change Detection, you receive an end-to-end solution designed for immediate integration and analysis.
| Product | Cadence | Includes | Format | Delivery | Web Application |
| ------------------------- | ----------------- | ------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Road Detection | Weekly or Monthly | Visual Mosaic | Raster Geotiff | [Analytics API](https://docs.planet.com/develop/apis/analytics.md), [Basemaps API](https://docs.planet.com/develop/apis/basemaps.md), [Tile Services](https://docs.planet.com/develop/apis/tiles.md) | [Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md) |
| Building Detection | Weekly or Monthly | Visual Mosaic | Raster Geotiff | [Analytics API](https://docs.planet.com/develop/apis/analytics.md), [Basemaps API](https://docs.planet.com/develop/apis/basemaps.md), [Tile Services](https://docs.planet.com/develop/apis/tiles.md) | [Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md) |
| Road Change Detection | Weekly or Monthly | Visual Mosaic | Vector Geojson | [Analytics API](https://docs.planet.com/develop/apis/analytics.md) | [Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md) |
| Building Change Detection | Weekly or Monthly | Visual Mosaic | Vector Geojson | [Analytics API](https://docs.planet.com/develop/apis/analytics.md) | [Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md) |
### Methodology
Planet’s Road & Building Change Detection takes a multiple step approach. At a high level, we run a semantic segmentation model on all the PlanetScope imagery published in a given area for a given week or month to assign a probability value (0-255) that the pixel represents a road, building or neither object.
The segmentation model results are aggregated together into a weekly or monthly layer and this process is repeated through time, generating a time-series of pixel values. Using the historical results, we run a predictive time series model to estimate what a given pixel’s value for a given time point should be compared to the actual observed value. When these values differ significantly, we create a change detection polygon indicating road or building development.
### Segmentation Model
Planet’s Road & Building segmentation model is a modified UNET, a deep learning supervised segmentation model, that runs on 4-band (RGBNir) Surface Reflectance assets. It was trained on \~10 thousand Planetscope images paired with labels pulled from Microsoft’s open [roads](https://github.com/microsoft/RoadDetections) and [buildings](https://github.com/microsoft/GlobalMLBuildingFootprints) datasets to mark each pixel into one of 3 classes: Road, Building, or other.
[](/data/analytic-feeds/road-building-change-detection/rb1.mp4)
Planet's Road & Building segmentation model assigns a probability value (0-255) that a pixel represents a road, building, or neither object.
Planet leveraged 80% of the dataset to train the segmentation model, holding out 20% of the labeled dataset for validation to measure the model's performance. By comparing the model's results over this 20% holdout dataset, we are able to calculate the following precision, recall, and F1 measurements:
Global locations of the training data used to train the Road and Building detection segmentation model.
| Class | F1 | Precision | Recall |
| ---------- | ---- | --------- | ------ |
| Road | 0.72 | 0.77 | 0.68 |
| Building | 0.81 | 0.81 | 0.81 |
| Background | 0.99 | 0.99 | 0.99 |
### Result Aggregation
Planet publishes imagery just about everywhere, just about every day. While the model was trained and runs on individual images, we are able to generate even better results when we take advantage of the data density PlanetScope provides. For a given area, we run the segmentation model on all of the published PlanetScope data for a given week and then aggregate those results into a single weekly result. This process removes any noisy detections caused by atmospheric interference, provides the greatest coverage and generally ensures the best possible representation of roads and buildings for the location.
[](/data/analytic-feeds/road-building-change-detection/rb2.mp4)
Daily results are aggregated into weekly or monthly layers, providing a consistent time series to analyze.
### Change Detection
With the segmentation output aggregated to weekly results, we generate time series data that tracks a pixel’s segmentation value through time. Leveraging this information, we are able to run a predictive model that establishes an expectation of what the pixel value should be for any given time point. We then compare this predicted value to the observed value to calculate the number of standard deviations (or “z-score”) between what is expected and the observed value.
[](/data/analytic-feeds/road-building-change-detection/rb3.mp4)
Time series data is analyzed to spot areas of development where pixel values have shifted significantly.
By evaluating this z-score through time, we found that z-scores greater than 10.5 indicated a high likelihood of real change taking place and results under this threshold were predominantly false positives. Because of this, we filter out any detections with a z-score under 10.5. We map the z-score to a “confidence score” between 0.5 and 1.0 that is surfaced in the metadata of the change detection. The higher the z-score, the closer the confidence score gets to 100%. Generally detections will have confidence scores between 50% and 75%.
Our change detection polygons are mapped to a standard 8x8 pixel gridcell, highlighting the area where the change took place.
Measuring the change detection model’s recall is difficult, since there is not a standard ground truth dataset that we can measure against. Any dataset we create would be powered by the change detection model itself, and it is hardly reasonable to measure it against itself. Still, we have been able to measure its precision. Manually validating hundreds of change events sampled across more than 100 regions, we found the model to have a precision of 0.94. While we have done our best to be exhaustive, we strongly suggest running a trial over your area to determine how well it performs to confirm it will work for your use case.
### Delivery Mechanisms
Results are available via the Analytics API and Feed Viewer. For more details please see:
* **[Analytics API](https://docs.planet.com/develop/apis/analytics.md)**
* **[Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md)**
### Full Metadata Reference
#### Feature-level Fields
| Property | Format | Example | Definition |
| -------- | --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| created | ISO 8601 DateTime | "2026-02-03T19:02:45.270966Z" | The timestamp when the feature was created in the system |
| geometry | GeoJSON Geometry | `{"type": "Polygon", "coordinates": [...]}` | The geographic polygon defining the location of the detected change |
| id | UUID | "17f21835-93c4-4664-b2ef-c2f57f5809a5" | The unique identifier for the feature |
| links | Array of Link Objects | `[{"href": "...", "rel": "self", "type": "..."}]` | Array of related resources including visual tiles, quads, process info, and observation data |
| type | String | "Feature" | The GeoJSON feature type |
#### Properties
| Property | Format | Example | Definition |
| -------------------- | ----------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| change\_direction | String | "positive" | The direction of change detected (positive indicates new development) |
| class\_label | String | "road" | The classification label for the type of infrastructure detected (road or building) |
| date | ISO 8601 DateTime | "2026-02-02T00:00:00Z" | The end date of the observation period when the change was detected |
| model\_version | String | "production" | The version of the model used for detection |
| object\_area\_m2 | Float | 461.042850935856 | The area of the detected change in square meters |
| object\_class\_label | String | "positive" | The classification label indicating the type of change |
| observed | ISO 8601 DateTime | "2026-01-26T00:00:00Z" | The start date of the observation period |
| score | Float | 0.5937995365687779 | The model's confidence in the detection accuracy (0.5-1.0 scale, where higher values indicate greater certainty) |
| source\_mosaic\_name | String | "rnb\_weekly\_v2\_2026\_01\_26\_2026\_02\_02" | The name of the source mosaic used for detection |
| source\_quad\_id | String | "1140-1295" | The identifier of the source quad tile |
| visual\_mosaic\_name | String | "ps\_weekly\_visual\_subscription\_2026-01-26\_2026-02-02\_mosaic" | The name of the visual mosaic for imagery display |
| visual\_quad\_id | String | "1140-1295" | The identifier of the visual quad tile |
With Planet Road & Building Change Detection, you gain a robust, persistent, and reliable view of development over the areas you care most about.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/analytic-feeds/vessel-detection/)
# Vessel Detection
Vessel Detection provides automated identification and monitoring of maritime vessels, enabling tracking of shipping activities, maritime surveillance, and ocean management.
## Seeing Beyond the Horizon
The global maritime domain is the lifeblood of our world. It accounts for approximately 90% of international trade, serves as a primary food source for billions of people, and is crucial for global energy production. However, monitoring this vast and complex environment is an immense challenge. With over 100,000 ships at sea at any given time, traditional surveillance methods struggle to keep up.
Governments, maritime agencies, and commercial stakeholders have long relied on cooperative tracking systems, such as the automatic identification system (AIS) and radio frequency (RF) signals. While useful, these systems have a critical flaw: they rely on vessels choosing to broadcast their location.
Nefarious actors, from potentially illicit fishing fleets to smugglers and hostile military vessels, can simply turn off their transponders, becoming dark ships that vanish from conventional monitoring systems. Dark ships leave critical gaps in situational awareness, making it nearly impossible to:
* Detect potentially illegal activity in sovereign waters
* Monitor strategic chokepoints for security threats
* Effectively combat illicit fishing and activities that impact the environment
* Efficiently deploy expensive patrol aircraft and ships
### Persistent, Non-Cooperative Monitoring From Space
Planet addresses this challenge through our automated Vessel Detection product, which provides a foundational layer of truth for Maritime Domain Awareness (MDA). We leverage the unprecedented power of our PlanetScope® constellation — the world's largest fleet of Earth-imaging satellites — to deliver ongoing automated vessel detection over vast ocean areas, on a near-daily basis.
Unlike AIS, satellite image-derived vessel monitoring is non-cooperative. It does not matter if a vessel is broadcasting its location or not. If it is on the surface, we can see it. This capability transforms MDA from a reactive search to a proactive, persistent monitoring mission, enabling users to see the complete picture of activity at sea and focus their resources where they matter most.
Planet's unique ability to scan enormous areas of the ocean on a near-daily basis unlocks critical new capabilities for a wide range of use cases.
### National Security and Border Protection
Navies, coast guards, and border agencies face the challenge of monitoring vast maritime territories, including exclusive economic zones (EEZs). Planet Vessel Detection delivers automated surveillance that spots dark ships and other threats, giving agencies the power to:
* **Detect and track vessels of interest** operating under emissions control (EMCON).
* **Prioritize and cue high-value assets,** such as patrol aircraft and ships, directly to suspicious activity, thereby maximizing their effectiveness and reducing operational costs.
* **Establish a pattern-of-life understanding** in high-interest areas, making it easier to spot anomalies that signal potential threats.
**Planet’s Unique Approach.** No other commercial provider offers near-daily electro-optical coverage at the scale required for meaningful national security monitoring. Our ability to scan over 10 million km² provides the tip-off that other systems miss.
### Illegal, Unreported and Unregulated (IUU) Fishing
IUU fishing is a multi-billion-dollar illicit industry that threatens global food security and marine ecosystems. These operators frequently go dark to avoid detection while engaging in illegal activities like fishing in protected areas or conducting illegal ship-to-ship transfers.
* PlanetScope near-daily imagery and automated detections can pinpoint vessels operating in marine protected areas or regions where fishing is prohibited.
* Our revisit rate allows analysts to identify potential transshipment events at sea, a key indicator of IUU fishing, by detecting vessels loitering in close proximity.
**Planet’s Unique Approach.** The PlanetScope constellation's near-daily revisit and broad area coverage are ideal for the persistent monitoring required to catch fleeting illegal fishing activities in remote ocean regions far from effective patrol routes.
## API Information
| API | Available | Notes |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Data API | ✅ | Customers can use the Data API to query imagery associated with a standard or enhanced vessel detection bundle |
| Orders API | ✅ | Customers can use the Orders API to order imagery associated with a standard or enhanced vessel detection bundle |
| Subscriptions API | ✅ | Customers can use the Subscriptions API to subscribe to imagery associated with a standard or enhanced vessel detection bundle |
| Analytics API | ✅ | The Analytics API is used to query vessel detection results |
| Basemaps API | ❌ | |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/analytic-feeds/vessel-detection/techspec/)
# Technical Specification
Planet’s Vessel Detection and Classification products leverage advanced machine learning and computer vision techniques to identify maritime activity over vast areas of interest. Derived from high-frequency PlanetScope imagery, this solution provides automated, oriented bounding box detections of vessels, enabling customers to monitor maritime domains, secure coastlines, and analyze economic activity with precision.
Planet supports three Vessel Detection offerings:
* **Standard Vessel Detection:** Only provides geojson feature collections containing polygons indicating the location and time vessels were detected along with associated metadata (for example, estimated length/width/heading, confidence score and other relevant information). This is a good fit for users with existing access to maritime data/imagery.
* **Standard Vessel Detection with Open Water Monitoring:** Includes everything for Standard Vessel Detection but also includes open water imagery over the area of interest.
* **Enhanced Vessel Detection with Open Water Monitoring:** Additional metadata is included for vessel classification and bunkering status
| | Standard Vessel Detection | Standard Vessel Detection with Open Water Monitoring | Enhanced Vessel Detection with Open Water Monitoring |
| ----------------------------------------------- | ------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
| Geojson Feature Collection of Vessel Detections | ✅ | ✅ | ✅ |
| Estimated Width, Length, Heading | ✅ | ✅ | ✅ |
| Confidence Score | ✅ | ✅ | ✅ |
| Imagery | ❌ | ✅ | ✅ |
| Vessel Classification | ❌ | ❌ | ✅ |
| Bunkered status | ❌ | ❌ | ✅ |
### Methodology
Our vessel detection model provides reliable, high-quality results that you can trust to drive critical decisions. The process uses a sophisticated deep learning approach.
#### Validated Approach
* **Segmentation:** The model first performs a segmentation step on the PlanetScope imagery. It analyzes the image pixel by pixel to create a probability mask that highlights all areas likely to contain a vessel.
* **Polygonization and feature extraction:** The model then processes this mask to generate a precise, object-oriented bounding box around each probable vessel. During this step, it calculates key metadata for each detection, including the confidence score, estimated length, and heading. This two-step process is highly effective at identifying vessels longer than 25 m while minimizing false positives from other features on the ocean's surface.
* **Classification and Bunkering:** For Enhanced Vessel Detection, we apply a secondary classification step that adds a predicted class property to the result, including Tanker, Cargo, and Military classes. We also add a status indicating if the vessel is closely bunkered with another ship to highlight potential ship-to-ship transfers.
#### Robust Training Data
A model is only as good as the data it is trained on. Planet Vessel Detection is trained on a massive, hand-labeled training dataset curated from our extensive imagery archive. This dataset features a broad geographic and temporal distribution, encompassing thousands of images from different oceans, seasons, and times of day. This diversity ensures the model is robust and performs reliably across a wide variety of real-world conditions, including different sea states, atmospheric haze, sun angles, and vessel types. It is continually updated and expanded to reduce model drift and address issues as they arise.
#### Reliable Performance
Our model is rigorously tested to ensure it meets the demanding needs of our users. Planet leveraged 80% of the above dataset to train the segmentation model, holding out 20% of the labeled dataset for validation to measure the model's performance. By comparing the model's results over this 20% holdout dataset, we can calculate the following precision, recall, and F1 measurements specifically over open water areas for vessels greater than 25 m in length.
* **Precision: 0.87** - This measures the accuracy of our detections. A high precision score means that when we identify a vessel, it is highly likely to be an actual vessel, minimizing false alarms.
* **Recall: 0.85** - This measures the completeness of our detections. A high recall score means we successfully identify a high percentage of the actual vessels present in the imagery.
* **F1-Score: 0.86** - This provides a single, balanced measure of the model's overall accuracy by combining both Precision and Recall.
### Delivery Mechanisms
Results are available via the Analytics API and Feed Viewer. For more details please see:
* **[Analytics API](https://docs.planet.com/develop/apis/analytics.md)**
* **[Feed Viewer](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md)**
### Full Metadata Reference
#### Feature-level Fields
| Property | Format | Example | Definition |
| -------- | --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| created | ISO 8601 DateTime | "2026-02-03T19:02:45.270966Z" | The timestamp when the feature was created in the system |
| geometry | GeoJSON Geometry | `{"type": "Polygon", "coordinates": [...]}` | The geographic polygon defining the location of the detected change |
| id | UUID | "17f21835-93c4-4664-b2ef-c2f57f5809a5" | The unique identifier for the feature |
| links | Array of Link Objects | `[{"href": "...", "rel": "self", "type": "..."}]` | Array of related resources including visual tiles, quads, process info, and observation data |
| type | String | "Feature" | The GeoJSON feature type |
#### Properties
| Property | Format | Example | Definition |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| angle | Float | 106.7 | The mathematical angle of the vessel bounding box in degrees (0-180) |
| area\_m2 | Float | 2543.2 | The area of the detected vessel's bounding box in square meters |
| bunkered | Boolean | false | Indicates whether the vessel is engaged in ship-to-ship transfer activity **Note: only available with Enhanced Vessel Detection** |
| category | String | "vessel" | The category of the detected object |
| diagonal\_m | Float | 115.96416084290871 | The diagonal length of the vessel bounding box in meters |
| heading | Integer | 162 | The estimated heading direction of the vessel in degrees (0-360) |
| length\_m | Float | 113.79 | The estimated length of the vessel in meters |
| model\_id | String | "cresi\_vessel" | The identifier of the detection model used |
| model\_version | String | "cresi2-vessel-ps-v1.2.0" | The version of the detection model used |
| object\_class\_label | String | "tanker" | The classification label assigned to the detected object **Note: only available with Enhanced Vessel Detection** |
| observed | ISO 8601 DateTime | "2025-10-16T07:21:48.627212Z" | The timestamp when the vessel was observed |
| score | Float | 0.943 | The model's confidence in the detection accuracy (0-1 scale, where higher values indicate greater certainty) |
| source\_asset\_type | String | "ortho\_visual" | The type of asset used for detection |
| source\_cloud\_cover | Float | 0.4 | The cloud cover percentage in the source imagery (0-1 scale) |
| source\_extent | WKT Polygon | "POLYGON ((55.9853058746303631 27.2509705260559514, 55.9467120017714379 27.0829579039142487, 56.2625643704127754 27.0239643873469042, 56.3020846152307257 27.1928634710108987, 55.9853058746303631 27.2509705260559514))" | The geographic extent of the source imagery as a polygon |
| source\_image\_mean\_gsd | Float | 3.6 | The mean ground sample distance of the source imagery in meters |
| source\_item\_id | String | "20251016\_072148\_62\_2507" | The unique identifier of the source imagery item |
| source\_item\_type | String | "PSScene" | The type of source imagery item |
| source\_quality\_category | String | "standard" | The quality category of the source imagery |
| source\_sun\_azimuth\_angle | Float | 163.4 | The azimuth angle of the sun in the source imagery in degrees |
| source\_sun\_elevation\_angle | Float | 52.5 | The elevation angle of the sun in the source imagery in degrees |
| width\_m | Float | 22.35 | The estimated width of the vessel in meters |
With Planet Vessel Detection, you gain a robust, persistent, and reliable view of the maritime domain, empowering you to act with speed and confidence.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/)
# Area Monitoring
## What is Area Monitoring
The abundance of [open and commercial multi-spectral and multi-temporal Earth Observation data](https://www.planet.com) provides a unique opportunity to monitor agricultural activities on a large scale. The initial use case is focused on the European Common Agricultural Policy, due to efficient control of subsidies, but the options are plentiful and related to sustainable farming.
## Demo
For learning and demonstration purposes, we have generated signals and markers for 20,280 agricultural parcels, which are displayed in the Area Monitoring app as part of the DEMO\_FR23 scope. The selected area is near Bordeaux, and is also available as [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data/).
Reference data produced by the Agence de Services et de Paiement (ASP) is part of the [Registre Parcellaire Graphique (RPG)](https://geoservices.ign.fr/rpg), a French geographic database providing detailed information on agricultural parcels. This data is used to process agricultural aid applications under the Common Agricultural Policy (CAP) in France. The publicly available RPG data includes:
* Geographic information on agricultural parcels, which are the basic units of land declared by farmers.
* Main crop types associated with each parcel.
The reference data consists mainly of vineyards and permanent grasslands. Below you can see the distribution of the most common crops.
Signals were downloaded from two sources: Sentinel-2 (S2) and Analysis Ready PlanetScope (ARPS) for 2023. Sentinel-2 provides freely available 10m resolution multispectral imagery, while ARPS offers ready-to-use data from PlanetScope satellites, enabling efficient and comprehensive monitoring of agricultural parcels with 3m resolution. Compared to S2, ARPS—with its lower revisit time—produced more valid observations (for example, observations that are cloudless and not outliers), as shown in the image below. This difference was especially noticeable during the cloudy autumn months.
In general, this difference can result in missed events or observations. The overview below for 2023 shows the percentage of FOIs that had at least one valid observation. With ARPS, there were only two weeks—one in January and one in March—when no valid observations were available due to clouds, compared to nine such weeks with Sentinel-2.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/applications/)
# Applications
In this chapter, we will take a look at the following applications:
* [Area Monitoring Application](https://docs.planet.com/data/area-monitoring/applications/area-monitoring-browser.md) for viewing the markers and Traffic Light System (TLS) decisions,
* [Expert Judgement Application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md) for review of the markers and TLS calculations and providing experts' evaluation of the TLS results,
* [Geotagged Photo Application](https://docs.planet.com/data/area-monitoring/applications/geotagged-photo-application.md) for communication between the Paying Agency and the farmer,
* [Admin Application](https://docs.planet.com/data/area-monitoring/applications/admin-application.md) for configuration of area monitoring system and checking of its status.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/applications/admin-application/)
# Admin Application
## Overview
The **Admin Application** provides a centralized place to:
* check the status of the area monitoring system
* create and configure scopes
* configure area monitoring system components (for example, the reference data, the signals, the markers and the traffic light system) for a specific scope.
Therefore, this user guide assumes that:
* you have a solid understanding of the [Area Monitoring](https://docs.planet.com/data/area-monitoring.md).
* you have been granted access to the **Admin Application**.
Once you are logged in you will see the below user interface.
The **Admin Application** user interface consists of the following components:
| Name | Description |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Drop-down arrow** next to the **Scope** | Allows you to view a list of scopes you have access to. Selecting a scope will expose the conditional sections. |
| **Add new** button | Allows you to [create a scope](#create-a-scope). |
| **System overview** section | Shows the following details about the services that are part of Area Monitoring [applications](https://docs.planet.com/data/area-monitoring/applications.md): service name, base URL, version information, build information, API documentation presented as a hyperlink and status information. |
| **Administration** section | Allows you to:
- [provide](#credentials) the credentials that will be used to access to the secured S3 bucket that you created
- [provide](#credentials) the Sentinel Hub **Client ID** and **Client Secret**
- [manage the configurations](#configuration) of different applications and services. |
| **Scope Configuration** section | Shows details about the selected scope. |
| **Reference Data** section | Allows you to [manage the Code lists](#code-lists) listed in this section and to [import the reference data](#import-reference-data-from-a-geopackage-file). |
| **Signal** section | Allows you to [manage the Code lists](#code-lists) listed in this section and to [configure the subscriptions](#subscription) for signals retrieval. |
| **Marker** section | Allows you to [manage the Code list](#code-lists) listed in this section. |
| **Traffic light** section | Allows you to [manage the Code lists](#code-lists) listed in this section. |
## Create a scope
1. Click **Add new**.
2. In the **Scope** field, enter the [scope ID](https://docs.planet.com/data/area-monitoring/common.md#scope).
> The entered scope ID should match the scope specified in the GeoPackage file from which you will import the reference data.
3. In the **SRID** field, enter the SRID (spatial reference identifier) data, which is an EPSG code.
> The entered EPSG code should match the EPSG code specified in the GeoPackage file from which you will import the reference data.
4. Click **Create**.
## Credentials
This feature enables you to provide:
* the S3 credentials that will be used to access the bucket that you created
* the Sentinel Hub **Client ID** and **Client Secret**.
1. Get your Sentinel Hub **Client ID** and **Client Secret**. For more information about how to get your Sentinel Hub **Client ID** and **Client Secret** please check [these instructions](https://docs.planet.com/guides/beginners-guide.md#get-your-client-credentials) or [this part of the tutorial video](https://www.youtube.com/watch?v=CBIlTOl2po4\&t=1760s).
2. Select the appropriate **Scope**.
3. Go to the **Administration** section.
4. Go to the **Credentials** tab.
5. Enter the S3 bucket credentials, the Sentinel Hub **Client ID** and **Client Secret** in JSON format.
6. Click **Save**.
## Configuration
This feature enables you to [create](#create-a-configuration) and [edit](#edit-a-configuration) the configurations of different applications and services.
### Create a configuration
1. Select the appropriate **Scope**.
2. Go to the **Administration** section.
3. Go to the **Configuration** tab.
4. Click **Create**.
5. In the **Key** field, enter a key.
6. Choose a content type from the drop-down menu.
7. In the **Validator** field, specify a validator.
8. Enter the configuration data.
9. Click **Save**.
### Edit a configuration
1. Select the appropriate **Scope**.
2. Go to the **Administration** section.
3. Go to the **Configuration** tab.
4. Click on the details of the desired configuration.
5. Edit any of the other editable fields that display. See [Create a configuration](#create-a-configuration) for an explanation of the fields.
6. Click **Save**.
## Code lists
Managing Code lists include actions such as [adding](#add-code-list-records) records to a Code List, [modifying](#edit-a-code-list-record) the record details and [deleting](#delete-a-code-list-record) records from a Code List.
### Add code list records
You can add records to a Code list using:
* [JSON](#add-a-code-list-record-using-json)
* [templates](#add-code-list-records-using-templates)
* [CSV file](#add-code-list-records-using-a-csv-file)
#### Add a code list record using JSON
1. Select the appropriate **Scope**.
2. Go to the **Reference Data** | **Signal** | **Marker** | **Traffic light** section.
3. In the **Code Lists** tab, click on the desired Code list title.
4. Click **Add new record**.
5. Enter the record data in JSON format and click **Add**.
note
Note that a JSON key represents a header row value in a CSV file (see [Add code list records using a CSV file](#add-code-list-records-using-a-csv-file) for more details).
#### Add code list records using templates
In the sections **Signal** and **Marker** you can use templates to populate in bulk the records of the Code lists with data from predifined Code list templates for each Sentinel Hub (SH) collection.
> Any template from the **Signal** section populates the following dependent Code lists:
* `sh-collection-types` listed in **Code Lists** tab from the **Signal** section
* `signal-types` listed in **Code Lists** tab from the **Signal** section
* `pixelation-types` listed in the **Code Lists** tab from the **Reference Data** section.
> Any template from the **Marker** section populates the `marker-types` Code list listed in the **Code Lists** tab from this section.
1. Select the appropriate **Scope**.
2. Go to the **Signal** | **Marker** section.
3. Go to the **Templates** tab.
4. Choose a collection from the drop-down menu.
> In the drop-down menu from the **Signal** section are listed the collections types which are not included in the `sh-collection-types` Code list.
>
> In the drop-down menu from the **Marker** section will be listed the collections which are included in the `sh-collection-types` Code list.
5. In the **SentinelHub collection source** field, enter the BYOC collection source if this was not auto-populated.
6. Click **Add**.
#### Add code list records using a CSV file
You can use a comma-separated values (CSV) file that contains information about the new Code list records you want to create in bulk.
note
Note that we recommend this method for adding records for the following code lists: `crops`, `agricultural-practice`, `foi-types`, `land-uses`, `schemes`, `soil-types`, `traffic-light-colours`, `decisions`, `event-types`, `judgement-reasons` and `lanes`.
1. Select the appropriate **Scope**.
2. Go to the **Reference Data** | **Signal** | **Marker** | **Traffic light** section.
3. In the **Code Lists** tab, click on the desired Code list title.
4. Click **Import CSV**.
5. In the **Select CSV file** pop-up window, click **Browse**, choose the CSV file and click **Import**.
To successfully import a CSV, the content must adhere to these rules:
* The CSV file must consist of a header row that names the columns and multiple rows of values that are separated by semicolons (;) (or other characters).
* Each row of values is a Code list record.
* Header row values must match the field values listed in the below CSV file requirements that are provided for the Code lists for which the recommended method to add records is via a CSV file.
* Header row values are not required to be in the order listed, just make sure that the column header is over the appropriate information in each respective column.
**The CSV file requirements** for the code lists for which the recommended method to add records is via a CSV file:
| Field | Data type | Required | Description | Code List |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | string | YES | Record's short unique code (use uppercase letters `[A-Z]`, numbers `[0-9]`, `_`, `-`) | `crops`, `agricultural-practice`, `foi-types`, `land-uses`, `schemes`, `soil-types`, `traffic-light-colours`, `decisions`, `event-types`, `judgement-reasons`, `lanes` |
| `names.` | string | NO | - Record's long name in given language
- Change `` in field name with appropriate [ISO 639 Language ID](https://www.localeplanet.com/icu/iso639.html#et) (for example, `names.en`)
- You can add names fields for several different languages (e.g. `names.en`, `names.sl`). | `crops`, `agricultural-practice`, `foi-types`, `land-uses`, `schemes`, `soil-types`, `traffic-light-colours`, `decisions`, `event-types`, `judgement-reasons`, `lanes` |
| `status` | string | YES | Record's status (usually `ACTIVE` but can be `HISTORIC`). | `crops`, `agricultural-practice`, `foi-types`, `land-uses`, `schemes`, `soil-types`, `traffic-light-colours`, `decisions`, `event-types`, `judgement-reasons`, `lanes` |
| `scope` | string | YES | Scope ID of the scope to which the Code list belongs. | `crops`, `agricultural-practice`, `foi-types`, `land-uses`, `schemes`, `soil-types`, `traffic-light-colours`, `decisions`, `event-types`, `judgement-reasons`, `lanes` |
| `has_financial_impact` | bool | YES | Record's financial impact (`True` or `False`) | `schemes` |
| `priority` | int4 | YES | Traffic light colour priority (the default is `0` ) | `traffic_light_colours` |
For example, the content of the CSV file to be used for adding records to the `crops` code list should look like this:
> code;names.en;names.sl;status;scope
1;buckwheat;ajda;ACTIVE;DEMO
2;sugar beet;sladkorna pesa;ACTIVE;DEMO
### Edit a Code list record
1. Select the appropriate **Scope**.
2. Go to the **Reference Data** | **Signal** | **Marker** | **Traffic light** section.
3. In the **Code Lists** tab, click on the desired Code list title.
4. Click the **Edit** button next to the record to be edited.
5. Edit the JSON text and click **Save**.
### Delete a Code list record
1. Select the appropriate **Scope**.
2. Go to the **Reference Data** | **Signal** | **Marker** | **Traffic light** section.
3. In the **Code Lists** tab, click on the desired Code list title.
4. Click the **Delete** button next to the record to be deleted.
5. In the **Delete confirmation** pop-up window, click **Save**.
## Import reference data from a GeoPackage file
This process assumes that:
* you [have populated the appropriate Code lists](#code-lists) from the **Code Lists** tab of the **Reference Data** section:
* `foi-types` (mandatory)
* `crops` (mandatory if in the GeoPackage file is specified the `crop_code`)
* `land-uses` (mandatory if in the GeoPackage file is specified the `land_use_code`)
* the GeoPackage adheres to the specifications
* you have uploaded the GeoPackage to a S3 bucket for which you [provided the credentials](#credentials).
1. Select the appropriate **Scope**.
2. Go to the **Reference Data** section.
3. Go to the **FOI Import** tab.
4. Choose a FOI type from the drop-down menu which lists the `foi-types` Code list records.
5. In the **Geopackage path** field enter the file’s S3 path.
6. In the **Geopackage FOI table name** field enter the name of the GeoPackage table with the reference data to import.
7. In **Geopackage additional attributes** field enter the name of the attribute specified in addition to the attributes from the GeoPackage specifications for the reference data. In case of multiple additional attributes, the names of the columns should be separated by a `,` (comma) for example, Att1, att2, etc.
8. Click **Import**.
## Subscription
This feature enables you to specify the details required for retrieval of signals.
### Create a subscription
This process assumes that:
* you [have imported the reference data](#import-reference-data-from-a-geopackage-file)
* you [have populated the Code lists](#code-lists) from the **Code Lists** tab from the **Signal** section
* you have uploaded to the S3 bucket for which you [provided the credentials](#credentials) the CSV file with the FOI IDs for which you want to retrieve SH collection signals
* the signals will be downloaded to the S3 bucket for which you [provided the credentials](#credentials) .
1. Select the appropriate **Scope**.
2. Go to the **Signal** section.
3. Go to the **Subscriptions** tab.
4. Click **Create new**.
5. Select a SH collection type from the drop-down menu which lists the `sh-collection-types` Code list records.
6. In **FOI filter** field enter the filter criteria if you want to retrieve SH collection signals only for the FOIs that match the entered criteria.
> For the filter criteria refer to the API documentation for the `/refdata/{scope}/fois/search` API endpoint under the `foi-controller` resource that can be accessed from the API documentation hyperlink of the `Reference data service` shown in the **System overview** section.
7. In **FOI ID's CSV path** field enter the file’s S3 path with the FOI IDs for which you want to retrieve the SH collection signals.
8. Enter the time interval for which you want to retrieve the SH collection signals.
9. Select the checkbox next to the SH collection signals you want to compute.
10. In **S3 subscription path** field enter the S3 bucket path where will be downloaded to the retrieved signals.
11. Configure advanced evalscript options such as `mosaicking`, `custom datamasks` and `preProcessScenes`. For more information, see the [Evalscipts](https://docs.planet.com/develop/evalscripts/) section.
12. Click **Save**.
### Edit a subscription
1. Select the appropriate **Scope**.
2. Go to the **Signal** section.
3. Go to the **Subscriptions** tab.
4. Click on the details of the desired subscription.
5. Edit any of the other editable fields that display. When changing the `Interval start` and `Interval end` keep in mind that subscriptions are only incremental in time. That means that if any signals were already downloaded (DONE signal packages exist) that `Interval start` should not be changed and `Interval end` can only be incremented in time. See [Create a subscription](#create-a-subscription) for an explanation of the fields.
6. Click **Save**.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/applications/area-monitoring-browser/)
# Area Monitoring Application
Area Monitoring App is a web application that aggregates data from connected systems in order to provide the ability for viewing the information on markers and Traffic Light System (TLS) decisions of a Feature of Interest (FOI) and is part of the Area Monitoring System.
## Basic navigation
At the left of the interface, you can select the scope (DEMO\_FR23 in this case), limit the timerange of the observations, observations layer and select marker context.
### FOI selection
#### Select one of the suggested FOIs
1. Select the **scope** from the drop-down list.
> Scope defines the geographical data and temporal intervals that will be available for selection and restricts the options in subsequent filters. Note that with the trial access, you will be limited to the `DEMO` scope.
2. Click on the `Suggest FOIs` button  This will open a pop-up window with a list of suggested FOIs.
3. (Optional) Filter the suggested FOIs by FOI type, land use or crop type.
4. Select a **FOI** from the list.
#### Select a FOI with a specific id
1. Select the **scope** from the drop-down list.
2. Select the **FOI type** from the drop-down list.
> FOI type selection is not needed if you provide the full FOI reference Id (for example, `DEMO.FOI.6999931001`) in the input field next to the FOI type drop-down. Note that you have only one type available in the `DEMO` scope, for example, `AP` - agricultural parcel.
3. Enter the **FOI ID**.
4. Press the **Search** button.
### Temporal selection
1. (Optional) Shorten the default timespan and press the **Search** button. When a valid FOI ID is entered, the timespan will be populated automatically and override the user's setting.
2. (Optional) Select the **Marker context** from the drop-down menu.
> Different marker contexts are available in case of several calculations of the markers within the season. Note that with the trial access, you will be limited to one marker context.
All of the information available for the selected FOI is displayed in several widgets.
### Collapse or expand widgets
(Optional) Click on the corresponding section header with a collapse/expand arrow to collapse or expand widgets located within the same section.
## Widgets
### FOI
**FOI** widget shows the general information about the selected FOI.
### Claims
**Claims** widget shows all the claims associated with the selected FOI. The last column shows the latest assigned traffic light decision, if available, and the TLS diagram used to make the decision.
Click on the `Diagram` buttom opens in a new browser tab the TLS diagram used to make the latest traffic light decision assigned to the claim.
To show/hide all the traffic light decisions assigned to a specific claim, click on expand/collapse arrow.
### Markers
The Markers widget group shows the following widgets: `Summary`, `Land cover group`, `Distance`, `Similarity`, `Crop group` and `Pixel Mowing`. Each of these can display information from more than one data source, if available (for example, S2 = Sentinel-2, PF = PlanetFusion).
#### Summary
**Summary** widget displays information for the markers listed below:
* `Land cover group` - predicted land cover group and confidence in the prediction
* `Crop group` - predicted crop group and confidence in the prediction
* `Similarity` - most similar crop type according to the similarity marker and its score (the lower the number, the more similar)
* `Distance` - most similar crop type according to the distance marker and its score (the lower the number, the more similar)
* `Bare soil` - number of bare soil observations within the scope timespan
* `Mowing` - number of detected mowing events within the scope timespan
* `Mowing (pixel level)`
* first three numbers (1 / 6 / 224 on the screenshot above) present:
* largest number of spatially connected pixels with detected mowing events,
* number of all pixels with mowing detected,
* number of full pixels in FOI pixelized geometry.
* the 2 numbers on the right (0.4% / 2.7% on the screenshot above) present:
* largest number of spatially connected pixels with detected mowing events divided by total number of pixels,
* number of all pixels with mowing detected divided by total number of pixels.
* `NDVI mean` - mean NDVI value of all valid observations per FOI within the scope timespan
* `Homogeneity` - predicted homogeneity (or non-homogeneity) and confidence in the prediction
#### Land cover group and Crop group
Under the **Land cover group** widget, classification scores for all land cover classes are presented graphically (see [Marker Scores](https://docs.planet.com/data/area-monitoring/visualizations/marker-scores.md) visualization component for more information). The predicted land cover group is rendered in green. If the declared land cover is not the same as the predicted one, it is rendered in darker blue color. The same principle is in use for presenting classification scores for all crop groups in the **Crop group** widget.
#### Distance and Similarity
Under the **Distance** widget, the scores for all crops are presented graphically (see [Marker Scores](https://docs.planet.com/data/area-monitoring/visualizations/marker-scores.md) visualization component for more information).
The most similar crop is rendered in green. If the declared crop is not the most similar one, it is rendered in darker blue color. The same principle is in use for presenting similarity marker scores in the **Similarity** widget.
### Traffic Lights
In the **Traffic Lights** widget, you can see all traffic light calculations performed for the selected FOI.
Clicking the `Show diagram` button displays the TLS diagram in a new browser tab.
### Observations
In the **Observations** widget, you can see all available image chips for the selected FOI and selected layer (by default, only valid observations are shown).
In the options row, you can choose:
* the desired layer,
* the number of columns used for laying out observation images,
* padding of the image chip around FOI geometry and
* whether images are filtered using the valid signal or not.
 
Clicking the image chip displays it in a new pop-up window that can be dragged or resized.
### Map
In the **Map** Widget, you can see the selected FOI and the neighboring FOIs.
If you move the map around, all available FOIs in the area will be displayed, to a certain zoom level. Clicking on any of the FOIs shown on the map will display the data related to that FOI in all widgets.
In the top right, you can select various `Map options`:
1. Choose if you wish to display the selected **FOI** with a yellow outline (so it stands out compared to other FOIs in the area) or not.
2. Select the background **Layer** - Aerial Photography, S2 True Color, S2 False Color, etc. If a satellite imagery is selected as a background, you can set the timestamp by clicking on the specific date in the `Signals Markers Visualization` widget.
3. Choose how you wish to display the neighbouring **FOIs**: show them or not, colour them by crop type or land use type, display the labels for the crop type or land use type.
4. Set **Filters** to display the FOIs matching the specified criteria with a blue outline so that they stand out compared to other FOIs (white outline) in the area. A filter can be applied to crop type, land use type, number of pixels or to a combination of these properties.
### Timelapse
In the **Timelapse** widget (see [Timelapse](https://docs.planet.com/data/area-monitoring/visualizations/timelapse.md) visualization component for more information), you can see the timelapse of the selected FOI's image chips for the selected layer. You can download the timelapse as a GIF file. You can either play the timelapse or navigate from one image chip to the next one.
### Signals Markers Visualizations
In the **Signals Markers Visualization** widget (see [Signal Marker Visualization](https://docs.planet.com/data/area-monitoring/visualizations/signal-marker-visualization.md) component for more information), you can see the graph of all available and selected signals and markers for the selected FOI and for the marker context in the selected period.
 
Clicking on the `CSV` button downloads all available data in a CSV format.
Clicking on the `JSON` button displays all available data in JSON format in a new browser tab.
Settings are available by clicking on the "Settings" icon in the bottom right. Here you can choose between several options of where the tooltip should be placed when hovering over points in the timeline.
The Legend is below the graph, showing which signals and markers are available. **Left clicking** on a label will toggle on and off the items shown on the graph. If indicated by a colored square, the item is shown on the graph. **Ctrl/cmd + Left clicking** on a label will toggle on and off the items included in the tooltip. If indicated by bold text, the item is included in the tooltip.
## Sentinel 2 visualisations
You can choose between different visualitations of the Sentinel 2 imagery in the `Observations`, `Map` and `Timelapse` widgets.
### S2 True color
True color composite: Sentinel-2 has 13 bands. True color composite uses visible light bands red, green and blue in the corresponding red, green and blue color channels, resulting in a natural colored product, that is a good representation of the Earth as humans would see it naturally.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/true_color/)
### S2 False color v1
False color composite: The false color composite using near infrared, red and green bands is most commonly used to assess plant density and health, since plants reflect near infrared and green light, while they absorb red.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/false_color_infrared/)
### S2 False color v2
False color composite with enhanced contrast: The false color composite using near infrared, red and green bands, but other color channels than the S2 False color v1.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/false_color_infrared/)
### S2 NDVI - Normalized Difference Vegetation Index (NDVI)
The normalized difference vegetation index is a simple, but effective index for quantifying green vegetation. It is a measure of the state of vegetation health based on how plants reflect light at certain wavelengths. The value range of the NDVI is -1 to 1. Negative values of NDVI (values approaching -1) correspond to water. Values close to zero (-0.1to 0.1) generally correspond to barren areas of rock, sand, or snow. Low, positive values represent shrub and grassland (approximately 0.2 to 0.4), while high values indicate temperate and tropical rainforests (values approaching 1).
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/ndvi/)
### S2 CCC - Canopy Chlorophyll Content
CCC (Canopy Chlorophyll Content \[$μg / cm ^ 2$]) is calculated here as the product of the leaf area index (LAI) with the leaf cholrophyll content (Cab). Visualized as an interval from 0-900.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/ccc/)
### S2 EVI - Enhanced Vegetation Index
In areas of dense canopy cover, where leaf area index (LAI) is high, the blue wavelengths can be used to improve the accuracy of NDVI, as it corrects for soil background signals and atmospheric influences. Values description: The range of values for EVI is -1 to 1, with healthy vegetation generally around 0.20 to 0.80.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/evi/)
### S2 LAI - Leaf Area Index
LAI is a dimensionless index measuring the one-sided green leaf area over a unit of land \[$m^2 / m^2$]. Visualized as an interval from 0-3.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/lai/)
### S2 NDWI - Normalized Difference Water Index (NDWI)
The normalized difference water index is most appropriate for water body mapping. Values of water bodies are larger than 0.5. Vegetation has smaller values. Built-up features have positive values between zero and 0.2.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/ndwi/)
### S2 Moisture index (NDMI)
NDMI is a normalized difference moisture index, that uses NIR and SWIR bands to display moisture. In short, NDMI is used to monitor changes in water content of leaves.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/ndmi/)
### S2 NDSI - Normalised Difference Snow Index (NDSI)
The Sentinel-2 normalised difference snow index can be used to differentiate between cloud and snow cover as snow absorbs in the short-wave infrared light, but reflects the visible light, whereas cloud is generally reflective in both wavelengths. Snow cover is represented in bright vivid blue.
[More details](https://custom-scripts.sentinel-hub.com/sentinel-2/ndsi/)
### S2 CL\_GREEN\_V2
S2 CL\_GREEN\_V2 Chlorophyll Index visualisation is tailored for monitoring agricultural areas by visualizing the chlorophyll content in vegetation. Chlorophyll levels are a key indicator of plant health and vitality, making this index valuable for assessing crop conditions. For example, it shows the subtle differences in the state of the vegetation after the area was mowed. The index is mapped to a color gradient that visually represents different levels of chlorophyll content. Dark green colors indicate higher chlorophyll content, suggesting healthier, more vigorous vegetation, while light green colors represent lower chlorophyll levels.
### S2 baresoil mask and S2 built-up mask
We have developed a set of binary land-cover classifiers that are able to give insights into the land-cover of each pixel of a FOI. These are: built-up mask, bare-soil mask, forest mask and water mask. The combination of these binary land-cover classifiers gives us our own proprietary on-demand scene classification map that can be applied to any single Sentinel-2 observation.
Built-up mask (blue pixels)
Baresoil mask (red pixels)
[More details](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application/)
# Expert Judgement Application
Expert Judgement Application allows to organise the work of experts to determine whether agricultural parcels comply with the Common Agricultural Policy (CAP) regulations by analyzing signals, markers, and auxiliary data.
Package bundles are used to organize the work of experts. A package bundle defines a collection of task packages, including the number of task packages in the bundle, the task to be performed, and the associated agricultural parcels. A task package represents the task to be performed on the associated agricultural parcels, which can be assigned to an expert.
Expert Judgement Application supports the following functionalities:
* creation of packages in the administrative module with tasks for:
* collection of the ground truth data,
* marker validation and
* traffic light review module
* insight into the status of the FOIs included in the subsidy applications:
* traffic light calculation results (including markers used in the calculation, model scenarios, model decisions, expert decision results and final traffic light results with transparent history overview)
* review of the auxiliary data (satellite images and signals, orthophoto images, subsidy applications attribute data, etc.),
* reports on several levels (per farm, per application, per marker).
## Administrative module
The administrative module is the central access point for reviewing traffic lights, providing an overview of package bundles and work distribution among users.
Below you can find the user interface.
Besides an overview of created bundles and packages (each user receives assigned packages in their inbox), the administration module allows detailed tracking of progress on FOI, claim, or eligibility criteria levels within the reporting tabs. An example is shown below.
You can easily filter millions of FOIs, check their status, export them, or edit them using the Traffic Light Review module by simply clicking on the FOI ID from the list.
As Expert App plays a central role for Paying Agencies for Traffic light decision making, it also enables creation of tasks for communication with farmers who submit claims. Check out example below. With help of this component, farmers can be notified via e-mail, SMS, or our [Geotagged Photo Application](https://docs.planet.com/data/area-monitoring/applications/geotagged-photo-application.md).
Speaking of Geotagged Photo App - we can also mention that all geotagged photos can be shown in the Expert app providing experts additional information for decission making in examples where claim cannot be checked with remote sensing data.
## Traffic Light Review (TL) module
The Traffic Light (TL) Review module offers a graphical interface for expert analysis of computed signals, markers, and auxiliary data to determine whether agricultural parcels comply with CAP regulations. Based on the expert's decision, a traffic light status is assigned.
*Example of TL review module in the action. FOI was is marked as non-compliant by our [TL model](https://docs.planet.com/data/area-monitoring/traffic-light-system/examples.md) as it is heterogenous with 2 different crops growing on it. Expert decided to confirm TL model decision. 4 different eligibility criterias were check for this claim (shown in the right task table) - agricultural use detection, homogeniety, compliance with non-agricultural land use rules and land use cross-check with tthe one defined in the claim.*
note
Note that all TL changes are transparently shown in TL history table clearly showing exact dates of the change with description of the trigger which caused TL color change.
A detailed description of visualization components which you can see on the screenshot can be found [here](https://docs.planet.com/data/area-monitoring/visualizations.md).
Once you are done with the review of all tasks, simply finish it with a click on a button and proceed with the next one. Results are now saved and you can access them anytime.
# Ground truth collection (GTC) module
In order to have optimal [marker results](https://docs.planet.com/data/area-monitoring/markers.md), ground truth data is of the outmost importance thus GT model idea was born.
In the wizard for package bundle creation, define the labels you want to collect (whether at the observation or FOI level) and immediately start labeling. For observation-level GTC (for example, mowing or bare soil presence on a specific date), use mouse clicks. For FOI-level GTC (useful in land-use assessment), you can label even faster using keyboard shortcuts.
Results of such labeling campaigns can be used as valuable research source in order to fine tune our markers so we could improve results in itterative process.
## Links
[Blog post](https://medium.com/sentinel-hub/expert-judgement-application-67a07f2feac4) about Expert Judgement Application
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/applications/geotagged-photo-application/)
# Geotagged Photo Application
The new CAP allows using a range of modern technologies when carrying out checks for area-based payments. Although area monitoring systems rely heavily on automated analysis of Earth observation data, they often use geotagged photos to support and complement the remote sensing methods when those do not provide conclusive results.
## About the application
Geotagged Photo Application is an Android application that allows farmers to share their photos (geotagged or not) with the paying agency (PA). Since photos can be used as a proof of activity or to clarify the request, it is very important for PA to get as much information about the photo as possible, for example, whether the photo, its location or date of creation have been changed. Photos that have been altered, uploaded from external sources or were not geotagged will be marked differently, so that PA can take this into account in further decisions.
## Short description of the process
The application is task oriented, and the typical usage comprises the following steps:
* tasks are created in advance by the PA using the [Expert Judgement application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md) or ad-hoc by the farmers themselves;
* before the field visit, the farmer synchronizes the data on their mobile device with the central database, storing base maps and any messages, tasks or photos, locally for offline use;
* when in the field, the farmer selects the task to perform;
* the application then guides them to the required location and helps them position the camera to take the photos and thus complete the task;
* later, when the device is online, the data is synchronized again, and the photos, along with any messages, are delivered to the PA;
* the information uploaded by the farmers is subsequently available in the Farmer Application (web application for the farmers to monitor TLS decisions for their agricultural parcels) and in the [Expert Judgement application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md).
## Application walk-through
### Authentication and synchronization
After successfully logging in, the user should select the appropriate scope (enter the holding id and application year) and afterwards, the synchronisation of the data can begin. When the synchronisation is complete, the user can use the application in the offline mode. One can have more than one scopes synchronised and the application can be used by multiple users on the same device allthough, the users cannot see each other's data and photos.
The application can use various authentication services.
The synchronization process takes into account all the associated data, for example, orthophoto, agricultural parcels, tasks and photos. It can be done automatically or manually. Automatic synchronisation is triggered by specific events, for example, at log in and log out, when the device gets connected to a known network and when the user has completed the task.
### Application Layout
The layout of the application consists of three parts:
1. **Toolbar** with buttons to log out, return to the home screen and information about the user and the selected scope.
2. **The navigation bar** shows the user's current location in the application and navigation options.
3. **Main panel** with the content.
### Home screen
When the user opens the application and selects the scope, the home screen is displayed. It has several buttons that are used for in-app navigation. The user can return to the home screen at any time by clicking on the `Home` icon in the toolbar.
### Task list - working with tasks
Tasks play an important role in sharing photos with PA. Photos can be attached to a specific task. Once a task is marked as completed, the photos are included in the synchronisation and sent to PA. The farmer can see them in the Farmer Application (web application for the farmers to monitor TLS decisions for their agricultural parcels), while PA can see them in Farmer Application and also in the [Expert Judgement application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md). Tasks can be prepared in advance by PA in the [Expert Judgement application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md) or by the user in the Geotagged Photo Application using the [Send photos and message](#send-photos-and-message) function.
#### Task preparation by the PA
PA can prepare tasks in the [Expert Judgement application](https://docs.planet.com/data/area-monitoring/applications/expert-judgement-application.md) by clicking on the `Foto` button in the bottom right corner of the application. Click on the button opens the photo task preparation component, which contains basic information about the selected agricultural parcel the task is being prepared for. PA can select a predefined task type from the drop-down menu, add a short description of the task and set the parameters, such as due date, the minimum and maximum number of photos the farmer must provide, type of photos (geotagged or not, authentic or not) and offset tolerance for viewpoint location and camera direction. For each task, PA can specify several preferred viewpoint locations, depending on the required number of photos, and the preferred camera direction for each viewpoint.
#### Task list
Touch on the **Task List** on the Home page opens the list of all tasks currently available on the device. Normally there will only be new or partially completed tasks as the completed tasks are synchronised with the servers as soon as the device gets connected to the preferred network (Wi-FI or, if allowed, a mobile data network).
By default, the list of tasks is sorted by status, with the new tasks at the top, but the user can also sort the list by any other task attribute. Only the basic task information is displayed in the list.
#### Task details
For more details about a specific task and further actions, the user should select the task from the tasks list. Available details are task type, information on the associated agricultural parcel, creation date, due date, minimum and maximum number of photos needed to complete the task, description of the task, and, if the user has already worked on a task, all photos already attached to it.
The user can also "Show task on map" or "Show more details about task parameters". In the task details, there are also buttons for adding photo to task, removing photo from task, rejecting task or finishing task.
#### Manage the task
The core of executing a task is adding photos and, if necessary, additional descriptions (messages). The task type and the parameters set by PA determine the number of photos and information on whether the photos should be geotagged or not. The application can block the completion of the task if the preset requirements are not met, or just notify the user about it. In both cases, the application can display the list of unfulfilled requirements or just generate a report.
The user can add photos to the task from their mobile phone gallery, the [Photo collection](#photo-collection) if they have already taken some, or by taking new photos. If the user chooses the last option to take new photos and the locations of the photos have been specified by PA, the user should first select one of the given viewpoint locations and the application will help them navigate to the selected location. Once the user is at the correct location and the bearing (camera direction) is also determined, the application will help them turn to the exact angle. After that, the user has to frame the picture, press the shutter button and add a picture description (optional).
When all the photos are attached, the user can press the `Finish task` button and add a message to complete the work.
At each step, the user can decide to reject the task by pressing the `Reject task` button and adding the necessary explanation.
#### Send photos and message
The user can send photos and/or messages (by pressing `Send` button) even if PA has not prepared the task beforehand. With this function, the user creates a new task through which they send a photo or a message to PA. Compared to the task prepared by PA, the user must additionally select the task type and the agricultural parcel the photos or messages are referring to. If the connection between the agricultural parcel and the photos has already been established, the user can simply select one or all photos of the selected agricultural parcel and attach them to this task.
### Agricultural parcel list and agricultural parcel details
In the **Agricultural parcels list**, all parcels of the selected farm and their basic attributes are displayed. Similar to the tasks, the user can press the selected agricultural parcel to view its attributes and location on the map. One can attach a photo from the mobile phone gallery, from the [Photo collection](#photo-collection) or take a new photo. The application can also navigate the user to the selected agricultural parcel. The attached photos can be used later when [sending photos and messages](#send-photos-and-message).
### Photo collection
The **Photo collection** holds all photos taken with the in-app photo module as well as photos from other sources. Only the most important properties of the photos are displayed in the list of thumbnails. For more detailed information, including all sensor data, the user has to select and press on the photo. Two important properties are indicated with special icons: geotagged photos with a `Globe` icon and unmodified photos with a `Lock` icon.
For every photo stored in the Photo collection, we can detect a change of the photo itself or its attributes and tag this photo differently. To protect it from editing and other manipulations, it is by default saved only in the Photo collection. Of course, it si also possible to export and share it.
All photos from external sources attached to tasks or agricultural parcels are stored in the Photo collection as well. As the application is not aware of the source of these photos and therefore cannot guarantee they have not been manipulated, they are marked as non-authentic images.
### Map
The map shows all the data needed for the user to be aware of their location on the field and guide them to the predefined viewpoint for taking a photo. These data include the geometries of the farm's agricultural parcels, points representing the photo viewpoint locations required by the tasks, the locations of the geotagged photos stored in [Photo collection](#photo-collection), ortophotos, topographic maps,...
On the map, the user can move around the holding, see the current location, identify attributes of the displayed features and customize the view. The user can switch layers on and off, zoom in to different locations, select features, navigate to the selected features etc.
### Camera
The built-in camera module is used on various occasions, for example, when the user is working on a task, is taking a photo of the agricultural parcel, or is just taking a photo unrelated to a task or a parcel. When the user presses `Camera` on the home screen, the viewfinder appears to help framing the picture. The viewfinder comprises the live preview, mini-map, shutter release button, sensor status indicator and the button for setting the flashlight.
### Other buttons on the home screen
In the **Settings**, the user can set and change the PIN for entering the application, set the warning limits and the compression level for photos, determine whether synchronisation should also take place via the mobile data network and log out.
Via the **Synchronisation** button, the user can view the current status of the synchronisation for all holdings they are authorised for and start synchronisation manually.
When the user presses the **Switch holding ID** button, they return to the **Welcome** screen for entering the application with a different scope.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/common/)
# Common
This page is intended for the description of *properties* that are used across area monitoring system.
## Common properties
### `scope`
The `scope` identifier primarily serves as a reference data differentiator. It can be:
* a country identifier ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) + year of data (for example, `SI22`) or
* internal classifier (for example, `DEMO`), if the country scope is not applicable, that can be constructed of:
* uppercase letters `[A-Z]` *(English alphabet only)*
* numbers `[0-9]`
* underscore `_`
## Common React props objects
### `geometry`
A `geometry` element is a *[GeoJSON](https://geojson.org/) object* (CRS: WGS84). Holes are allowed.
| Property | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `type`\* | `string` | The type of shape to be rendered. The supportive geometry types are `Polygon` or `MultiPolygon`. |
| `coordinates`\* | `array` | The coordinates that set the position of the drawn shape’s outline. |
*\* indicates mandatory properties*
### `style`
A `style` element is an object that defines how [geometry](#geometry) will be displayed.
| Property | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `strokeColor`\* | The color (one of [CSS legal color values](https://www.w3schools.com/cssref/css_colors_legal.asp)) of the shape's outline. |
| `lineWidth`\* | The width of the outline in pixels. |
*\* indicates mandatory properties*
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/marker-service-api/)
# Marker Service API
## API Overview
The Marker service API is a RESTful API interface to various markers. You can browse the reference docs [here](https://am-pilot.sinergise.com/marker/swagger-ui.html).
This chapter describes the structure of the markers data provided by the Markers service API.
## Bare-soil marker
| Key | Description |
| -------------------- | --------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `observationCount` | Count of all FOI's bare-soil observations |
| `markerObservations` | List of bare-soil observations |
| `date` | Signal acquisition date |
| `confidence` | Confidence in the observation being bare-soil (value between 0 and 1) |
### Example response
```
{
"id": "CY22.MARKER.588-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_BARE_SOIL",
"impl": "OBSERVATION",
"inferenceId": "CY22.INFERENCE.588",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"observationCount": 37,
"markerObservations": [
{
"date": "2021-10-08",
"confidence": 0.9277381
},
{
"date": "2021-10-10",
"confidence": 0.97361684
},
{
"date": "2021-10-15",
"confidence": 0.9888286
}
]
}
```
## Ploughing marker
| Key | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `events` | List of ploughing events |
| `start` | Date before a significant rise of baresoil pseudo-probability (BS\_PROBA) was detected |
| `startThreshold` | The first date when the significant rise of BS\_PROBA, compared to `startValue`, was detected |
| `endThreshold` | The first date before `end` when the significant difference of BS\_PROBA value compared to `endValue` was detected |
| `extrema` | Timestamp of the highest BS\_PROBA value within the `start` - `end` interval |
| `end` | Timestamp that marks the end of the ploughing period; has same value as `extrema` |
| `startValue` | BS\_PROBA value at the `start` date |
| `startThresholdValue` | BS\_PROBA value at the `startThreshold` date |
| `endThresholdValue` | BS\_PROBA value at the `endThreshold` date |
| `extremaValue` | BS\_PROBA value at the `extrema` date |
| `endValue` | BS\_PROBA value at the `end` date; has same value as `extremaValue` |
| `numObservations` | Number of valid observations within the `start` - `end` interval |
### Example response
```
{
"id": "RS20.MARKER.71189-112",
"markerTypeId": "RS20.CL_MT.S2L2A_PLOUGHING_MARKER",
"impl": "EVENT",
"inferenceId": "RS20.INFERENCE.71189",
"foiId": "RS20.FOI.112",
"status": "OK",
"events": [
{
"numObservations": 4,
"extremaValue": 0.8879989,
"endValue": 0.8879989,
"start": "2020-06-30",
"end": "2020-07-30",
"extrema": "2020-07-30",
"endThresholdValue": 0.393348,
"startThreshold": "2020-07-30",
"startValue": 0.076752804,
"startThresholdValue": 0.8879989,
"endThreshold": "2020-07-10"
}
]
}
```
## Homogeneity marker
| Key | Description |
| --------------------- | ------------------------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `classificationCode` | `hypothesisCode` with the highest score |
| `classificationScore` | `score` of the most probable assumed `hypothesisCode` (value between 0 and 100) |
| `markerScores` | List of scores per hypothesis |
| `hypothesisCode` | Assumed homogeneity/heterogeneity of a FOI - "homogeneous" or "heterogeneous" |
| `score` | The normalised (\[0, 100]) representation of probability of the hypothesis being true |
### Example response
```
{
"id": "CY22.MARKER.590-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_HOMOGENEITY",
"impl": "CLASSIFICATION",
"inferenceId": "CY22.INFERENCE.590",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"classificationCode": "homogeneous",
"classificationScore": 98,
"markerScores": [
{
"hypothesisCode": "heterogeneous",
"score": 2
},
{
"hypothesisCode": "homogeneous",
"score": 98
}
]
}
```
## Mowing marker (on FOI level)
| Key | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `events` | List of mowing events |
| `start` | The last date before the drop of NDVI was detected |
| `startThreshold` | The first date when the significant drop of NDVI was detected |
| `endThreshold` | The first date when the significant difference of NDVI value compared to `extremaValue` was detected. |
| `extrema` | Timestamp of the lowest NDVI value within the `start` - `end` interval |
| `end` | The first date after the `extrema` when the NDVI value recovered sufficently compared to `extremaValue` |
| `startValue` | NDVI value at the `start` date |
| `startThresholdValue` | NDVI value at the `startThreshold` date |
| `endThresholdValue` | NDVI value at the `endThreshold` date |
| `extremaValue` | Lowest NDVI value within the `start` - `end` interval (at the `extrema`) |
| `endValue` | NDVI value at the `end` date |
| `numObservations` | Number of valid observations within the `start` - `end` interval |
| `probability` | Probability of an event |
### Example response
```
{
"id": "CY22.MARKER.589-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_MOWING",
"impl": "EVENT",
"inferenceId": "CY22.INFERENCE.589",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"events": [
{
"numObservations": 4,
"extremaValue": 0.18152198,
"endValue": 0.30097502,
"probability": 0.011970464,
"start": "2020-08-04",
"end": "2020-09-03",
"extrema": "2020-08-14",
"endThresholdValue": 0.32299966,
"startThreshold": "2020-08-14",
"startValue": 0.32299966,
"startThresholdValue": 0.18152198,
"endThreshold": "2020-08-04"
},
{
"numObservations": 6,
"extremaValue": 0.16239251,
"endValue": 0.3684666,
"probability": 0.030903734,
"start": "2020-09-03",
"extrema": "2020-09-18",
"startThreshold": "2020-09-08",
"end": "2020-10-23",
"endThresholdValue": 0.30097502,
"startValue": 0.30097502,
"startThresholdValue": 0.1874948,
"endThreshold": "2020-09-03"
}
]
}
```
## Pixel-mowing marker
| Key | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `events` | List of partial mowing events |
| `ndviBottom` | Lowest NDVI value within the `eventStart` - `eventEnd` interval |
| `numObservations` | Number of valid observations within the `eventThreshold` - `eventEnd` interval |
| `ndviStart` | NDVI value on the date before the drop of NDVI was detected (at the `eventStart`) |
| `eventStart` | The last date before the drop of NDVI was detected |
| `eventThreshold` | The first date when the drop of NDVI was detected |
| `ndviDrop` | Difference between the `ndviStart` and `ndviBottom` |
| `ndviThreshold` | NDVI value on the first date when the drop of NDVI was detected (at the `eventThreshold`) |
| `daysBetweenStartAndThreshold` | Number of days between `eventStart` and `eventThreshold` |
| `duration` | Number of days between `eventThreshold` and `eventEnd` |
| `eventEnd` | End date of the mowing event |
| `ndviEnd` | NDVI value at the end of the mowing event (at the `eventEnd`) |
| `eventMask` | Boolean raster mask describing which pixels belong to a cluster |
| `bottomTimestamp` | Timestamp of the lowest NDVI value within the `eventStart` - `eventEnd` interval |
### Example response
```
{
"id": "TEST.MARKER.9-7422731001",
"markerTypeId": "TEST.CL_MT.S2L1C_PIXEL_MOWING",
"inferenceId": "TEST.INFERENCE.9",
"foiId": "TEST.FOI.7422731001",
"status": "OK",
"events": [
{
"ndviBottom": 0.6479333,
"numObservations": 7,
"ndviStart": 0.84885,
"eventStart": "2022-06-11",
"eventThreshold": "2022-06-19",
"ndviDrop": 0.20091671,
"ndviThreshold": 0.6937333,
"daysBetweenStartAndThreshold": 8,
"duration": 30,
"eventEnd": "2022-07-19",
"ndviEnd": 0.75409997,
"eventMask": [
[true, false, false],
[false, false, false]
],
"bottomTimestamp": "2022-06-29"
}
]
}
```
## Pixel-mowing aggregation marker
| Key | Description |
| ----------------- | ------------------------------------------------------------------------------------ |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `maxChunkSizePix` | Size (in pixels) of the largest part of FOI with a detected mowing event |
| `maxChunkRatio` | Relative coverage of the largest part of FOI with a detected mowing event |
| `mowingDetected` | Flag that is set to true if a FOI has a mowing detected according to specified query |
| `coverageSizePix` | Count of all pixels with a detected mowing event |
| `data` | Pixel-mask of mowing event counts |
| `numPixels` | Number of source pixels inside the FOI's geometry |
| `coverageRatio` | Relative coverage of all pixels with a detected mowing event |
### Example response
```
{
"id": "TEST.MARKER.8-6820505001",
"markerTypeId": "TEST.CL_MT.S2L1C_PIXEL_MOWING_AGGREGATION",
"inferenceId": "TEST.INFERENCE.8",
"foiId": "TEST.FOI.6820505001",
"status": "OK",
"maxChunkSizePix": 10,
"maxChunkRatio": 0.8333333,
"mowingDetected": true,
"coverageSizePix": 10,
"data": [
[-1, 0, 0, 1],
[-1, 0, 0, 5],
[0, 0, 0, 4]
],
"numPixels": 12,
"coverageRatio": 0.8333333
}
```
## Similarity marker
| Key | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `classificationCode` | Most similar crop type (crop id) |
| `declaredAsCode` | Declared crop type (crop id) |
| `classificationScore` | Score of the most similar crop type (value between 0 and 100) |
| `markerScores` | List of scores per hypothesis |
| `hypothesisCode` | Assumed crop type of the target FOI (based on neighboring FOIs) |
| `score` | The normalised (\[0, 100]) representation of the chi2 value of the NDVI time-series difference between the target FOI and the neighboring FOIs (the lower the score, the more similar) |
### Example response
```
{
"id": "CY22.MARKER.593-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_SIMILARITY",
"impl": "CLASSIFICATION",
"inferenceId": "CY22.INFERENCE.593",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"classificationCode": "238",
"declaredAsCode": "40",
"classificationScore": 20,
"markerScores": [
{
"hypothesisCode": "1",
"score": 64
},
{
"hypothesisCode": "40",
"score": 56
},
{
"hypothesisCode": "111",
"score": 27
},
{
"hypothesisCode": "122",
"score": 100
},
{
"hypothesisCode": "15",
"score": 95
},
{
"hypothesisCode": "238",
"score": 20
},
{
"hypothesisCode": "8",
"score": 100
}
]
}
```
## Euclidian distance marker
| Key | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `classificationCode` | Most similar crop type (crop id) |
| `declaredAsCode` | Declared crop type (crop id) |
| `classificationScore` | Score of the most similar crop type (value between 0 and 100) |
| `markerScores` | List of scores per hypothesis |
| `hypothesisCode` | Assumed crop type of the target FOI (based on neighboring FOIs) |
| `score` | The normalised (\[0, 100]) representation of the Median Euclidean distance between the NDVI time-series of the target FOI and the neighboring FOIs having assumed crop type declared (the lower the score, the more similar) |
| `sameCropCount` | Number of all neighbouring FOIs with the same declared crop type as the target FOI |
### Example response
```
{
"id": "CY22.MARKER.594-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_DISTANCE",
"impl": "CLASSIFICATION",
"inferenceId": "CY22.INFERENCE.594",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"classificationCode": "46",
"declaredAsCode": "40",
"classificationScore": 56,
"markerScores": [
{
"hypothesisCode": "1",
"score": 95
},
{
"hypothesisCode": "111",
"score": 72
},
{
"hypothesisCode": "150",
"score": 100
},
{
"hypothesisCode": "40",
"score": 85
},
{
"hypothesisCode": "46",
"score": 56
},
{
"hypothesisCode": "18",
"score": 89
}
],
"sameCropCount": 3
}
```
## Crop-group marker
| Key | Description |
| --------------------- | ------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `classificationCode` | Assumed crop group with the highest confidence |
| `declaredAsCode` | Declared crop group (mapped from the declared crop type) |
| `classificationScore` | Score of the likeliest assumed crop group (value between 0 and 100) |
| `markerScores` | List of scores per hypothesis |
| `hypothesisCode` | Assumed crop group |
| `score` | Confidence in the assumed crop group (value between 0 and 100) |
### Example response
```
{
"id": "CY22.MARKER.585-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_CROP_GROUP_PREDICTION",
"impl": "CLASSIFICATION",
"inferenceId": "CY22.INFERENCE.585",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"classificationCode": "POTATOES",
"declaredAsCode": "POTATOES",
"classificationScore": 52,
"markerScores": [
{
"hypothesisCode": "BANANAS",
"score": 0
},
{
"hypothesisCode": "BARLEY",
"score": 0
},
{
"hypothesisCode": "CEREALS",
"score": 2
},
{
"hypothesisCode": "GREENHOUSES",
"score": 1
},
{
"hypothesisCode": "LAND LYING FALLOW",
"score": 0
},
{
"hypothesisCode": "LEGUMES",
"score": 4
},
{
"hypothesisCode": "ORCHARD / VARIUS FRUIT TREES/VEGETABLES",
"score": 0
},
{
"hypothesisCode": "PERMANENT GRASSLAND",
"score": 0
},
{
"hypothesisCode": "POTATOES",
"score": 52
},
{
"hypothesisCode": "VARIOUS VEGETABLES",
"score": 13
},
{
"hypothesisCode": "WHEAT",
"score": 2
},
{
"hypothesisCode": "VINEYARDS",
"score": 0
}
]
}
```
## Land-group marker
| Key | Description |
| --------------------- | ----------------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `classificationCode` | Assumed land use group with the highest confidence |
| `declaredAsCode` | Declared land use group (mapped from the declared crop type) |
| `classificationScore` | Score of the likeliest assumed land use group (value between 0 and 100) |
| `markerScores` | List of scores per hypothesis |
| `hypothesisCode` | Assumed land use group |
| `score` | Confidence in the assumed land use group (value between 0 and 100) |
### Example response
```
{
"id": "CY22.MARKER.586-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_LAND_COVER",
"impl": "CLASSIFICATION",
"inferenceId": "CY22.INFERENCE.586",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"classificationCode": "ARABLE LAND",
"declaredAsCode": "ARABLE LAND",
"classificationScore": 100,
"markerScores": [
{
"hypothesisCode": "ARABLE LAND",
"score": 100
},
{
"hypothesisCode": "GRASSLAND (PERMANENT PASTURE)",
"score": 0
},
{
"hypothesisCode": "GREENHOUSE",
"score": 0
},
{
"hypothesisCode": "PERMANENT CROPS",
"score": 0
}
]
}
```
## Mean-NDVI marker
| Key | Description |
| -------------- | ----------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `value` | Mean NDVI value of all valid observations per FOI |
### Example response
```
{
"id": "CY22.MARKER.592-10837450",
"markerTypeId": "CY22.CL_MT.S2L2A_AGGREGATION_MEAN_NDVI",
"impl": "AGGREGATION",
"inferenceId": "CY22.INFERENCE.592",
"foiId": "CY22.FOI.10837450",
"status": "OK",
"value": 0.5653076
}
```
## Greening-harvest marker
| Key | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `impl` | Marker class |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `eventComposites` | List of rise-fall pairs |
| `rise.start` | Date before a significant rise of NDVI was detected; start of the greening period |
| `rise.startThreshold` | The first date when the significant rise of NDVI, compared to `rise.startValue` was detected |
| `rise.endThreshold` | The first date before `rise.end` when the significant difference of NDVI value compared to `rise.endValue` was detected |
| `rise.extrema` | Timestamp within the greening period when the NDVI value is the highest |
| `rise.end` | Timestamp that marks the end of the greening period; has same value as `rise.extrema` |
| `rise.startValue` | NDVI value at the `rise.start` |
| `rise.startThresholdValue` | NDVI value at the `rise.startThreshold` |
| `rise.endThresholdValue` | NDVI value at the `rise.endThreshold` |
| `rise.extremaValue` | NDVI value at the `rise.extrema` |
| `rise.endValue` | NDVI value at the `rise.end`; has same value as `rise.extremaValue` |
| `rise.numObservations` | Number of valid observations between the start and the end of the greening period |
| `fall.start` | Date before a significant NDVI drop was detected; start of the harvest period |
| `fall.startThreshold` | The first date when the significant drop of NDVI, compared to `fall.startValue` was detected |
| `fall.endThreshold` | The first date before `fall.end` when the significant difference of NDVI value compared to `fall.endValue` was detected. |
| `fall.extrema` | Timestamp within the harvest period when the NDVI value is the lowest |
| `fall.end` | Timestamp that marks the end of the harvest period; has same value as `fall.extrema` |
| `fall.startValue` | NDVI value at the `fall.start` |
| `fall.startThresholdValue` | NDVI value at the `fall.startThreshold` |
| `fall.endThresholdValue` | NDVI value at the `fall.endThreshold` |
| `fall.extremaValue` | NDVI value at the `fall.extrema` |
| `fall.endValue` | NDVI value at the `fall.end`; has same value as `fall.extremaValue` |
| `fall.numObservations` | Number of valid observations between the start and the end of the harvest period |
### Example response
```
{
"id": "TEST.MARKER.91-6727959001",
"markerTypeId": "TEST.CL_MT.S2L2A_GREENING_HARVEST",
"impl": "EVENT_COMPOSITE",
"inferenceId": "TEST.INFERENCE.91",
"foiId": "TEST.FOI.6727959001",
"status": "OK",
"eventComposites": [
{
"rise": {
"endValue": 0.83880246,
"endThreshold": "2020-04-01",
"startValue": 0.6217497,
"end": "2020-04-16",
"extrema": "2020-04-16",
"startThreshold": "2020-03-12",
"numObservations": 7,
"endThresholdValue": 0.77352065,
"startThresholdValue": 0.7250762,
"extremaValue": 0.83880246,
"start": "2020-03-02"
},
"fall": {
"extrema": "2020-09-18",
"endThreshold": "2020-09-03",
"end": "2020-09-18",
"endValue": 0.16239251,
"startValue": 0.83880246,
"startThreshold": "2020-07-05",
"start": "2020-04-16",
"startThresholdValue": 0.36374354,
"numObservations": 10,
"endThresholdValue": 0.30097502,
"extremaValue": 0.16239251
}
}
]
}
```
## Evaluation
| Key | Description |
| -------------- | --------------------------------------------------------------- |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `evaluation` | Result of the evaluation of the given condition(s) (true/false) |
### Example response
```
{
"id": "TEST.MARKER.6-4981068",
"markerTypeId": "TEST.CL_MT.S2L1C_EVALUATION",
"inferenceId": "TEST.INFERENCE.6",
"foiId": "TEST.FOI.4981068",
"status": "OK",
"evaluation": true
}
```
## Count aggregattion
| Key | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Marker id |
| `markerTypeId` | Marker type id |
| `inferenceId` | Inference id |
| `foiId` | FOI (Feature Of Interest) id |
| `status` | Marker status ("OK", "NOT\_VALID" or "NOT\_EXECUTED") |
| `count` | Count of valid (according to a given condition) occurences, for example, number of valid observatons, number of observations when the FOI's mean NDVI was above some threshold, etc. |
### Example response
```
{
"id": "TEST.MARKER.90-4105747",
"markerTypeId": "TEST.CL_MT.S2L1C_AGGREGATION_VALID_FULL",
"inferenceId": "TEST.INFERENCE.90",
"foiId": "TEST.FOI.4105747",
"status": "OK",
"count": 10
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/)
# Markers
Markers are translated and interpreted from vast amounts of full-area, multi-temporal indirect “signals” from Sentinel data and are derived over “features of interest”.
An important property of markers is that they can easily be generalized across a large region. Some of them address specific rules directly, and some of them can be used in combination — for example, to detect ineligible areas, which do not have their own marker.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/bare-soil-marker/)
# Bare-Soil Marker
## Basic info
The bare-soil marker identifies all observations with exposed bare soil due to fields being recently ploughed or due to non-photosynthetic vegetation cover. The latter can be a consequence of harvest or vegetation drying up in the field. While the actual events (ploughing or harvesting) cannot be directly detected in satellite imagery, their consequences are clearly observable.
The images below show random Sentinel-2 observations in false color, labeled as either bare soil or vegetated (meaning vegetation covers the area of a Field of Interest - FOI). Exposed bare soil appears brownish or grayish in false color, while the presence of vegetation is indicated by red tones.
**How it works:** The bare-soil marker assigns a probability (0-1 scale) to each valid Sentinel-2 observation indicating the likelihood that the FOI area has exposed bare soil. All observations with bare-soil probability above a user-defined threshold (typically set to 0.8) are classified as bare-soil observations.
| Sentinel-2 observations of FOIs covered with vegetation | Sentinel-2 observations of FOIs with exposed bare soil |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|  |  |
## Marker output
Bare-soil observations are marked with vertical brown lines in the signal time series chart at the bottom, which shows the time-series of NDVI signal in green. The figure on the left shows false color ARPS images, and the figure on the right shows true color S2 images with bare-soil mask overlaid in red. In this case, due to more valid ARPS observations, there is a difference in the number of bare-soil observations when comparing the two different signal sources.
| False color visualization (ARPS) | Bare-soil prediction mask (Sentinel-2) |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|  |  |
## Further info
The timing when a FOI area has exposed bare soil depends on the type of crop being cultivated and the farming practices employed. The results of the bare-soil marker can help reveal these agricultural patterns.
### Cultivation patterns
Let us examine the temporal distribution of detected bare-soil observations for cornfields. In the example above, we can observe that bare soil is detected from the beginning of the year until early June and again in the second half of October. Long periods of exposed bare soil early in the year are very typical for cornfields in Slovenia.
This pattern is illustrated in the figure below, which shows the temporal distribution of all observations in gray and bare-soil observations in brown for all FOIs claiming to grow corn. The blue line shows the fraction of FOIs that have bare soil exposed on any given date. This fraction is high early in the season and at the end of the season, and practically zero during the growing period of corn - between mid-June and early October.
### Crop-specific patterns
Different crop types are sown and harvested at different times, which is reflected in the temporal distribution of detected bare-soil observations. The table below shows the same analysis for winter and summer barley, various vegetables, and permanent meadows:
* **Winter and summer barley**: Winter barley is sown in October of the previous year, while summer barley is sown in early March. This explains why the fraction of FOIs with exposed bare soil is much higher at the beginning of the year for summer barley.
* **Various vegetables**: There are no clear expectations for FOIs claiming to grow vegetables, as different kinds of vegetables can be sown and harvested at different times, often multiple times per season. Bare-soil observations are thus distributed throughout the year without any clear pattern.
* **Permanent meadows**: These are not expected to be ploughed and should not have exposed bare soil. The distribution shown below confirms this expectation.
| Winter barley | Summer barley |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
|  |  |
| **Various vegetables** | **Permanent meadows** |
|  |  |
The above distributions show that the bare-soil marker provides valuable input that can be used not only when assessing whether a FOI was farmed (ploughed) or not, but also whether the declared crop type is consistent with observed patterns.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-bare-soil-marker-608bc95712ae) about Bare-soil marker
[Examples](https://docs.planet.com/data/area-monitoring/markers/bare-soil-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/bare-soil-marker/examples/)
# Bare-Soil Marker Examples
## Misclassified corn field with zero bare-soil detections
### Description
FOI=[92276701](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276701?from=2023-01-01\&to=2023-12-31\&selected=2023-04-17\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) claims to grow corn, but has zero bare-soil detections, which is very atypical for corn fields as shown in the main documentation. Investigation in the Area Monitoring App reveals that corn is definitely not being cultivated on this FOI.
**Key findings:**
* NDVI time-series is not similar to the NDVI profile of other corn fields.
* ARPS and S2 classification marker predicts vineyards group.
* Similarity and distance markers suggest that buffer strip (BTA) or sunflower (TRN) are grown on this FOI.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276701?from=2023-01-01\&to=2023-12-31\&selected=2023-04-17\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Grassland with presence of built-up land cover
### Description
FOI=[92280460](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92280460?cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-25\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), despite being classified as a permanent meadow, consistently shows exposed bare soil in summer observations. Further investigation in the Area Monitoring App reveals that this permanent grassland may have been partly converted to built-up land, with visible structures now present.
**Key findings:**
* No mowing detected.
* Relatively low mean NDVI values - 0.4 with ARPS and 0.33 based on Sentinel-2 signals.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92280460?cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-25\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Winter barley
### Description
FOI=[92273815](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92273815?from=2023-01-01\&to=2023-12-31\&selected=2023-07-25\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) claims to grow winter barley.
**Key findings:**
* NDVI time-series and crop-group classification are consistent with this claim.
* There are bare-soil observations only in July and during October-December. Most probably this FOI had another crop undersown, which started to grow after winter barley was harvested. The bare-soil observations in July are from the time when there was no or very little photosynthetic vegetation present on the FOI.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92273815?from=2023-01-01\&to=2023-12-31\&selected=2023-07-25\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-TRUE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker/)
# Binary Land-Cover Marker
## Basic info
Binary land-cover marker is a set of binary land-cover classifiers that are able to give insights into the land-cover of each pixel of a FOI. These are: built-up, bare-soil, forest and water land-cover binary classifiers. The combination of these binary land-cover classifiers gives us our own proprietary on-demand scene classification map that can be applied to any single Sentinel-2 observation.
## Marker output
Scene classification example can be found in the image below for a medium-sized area in Savinjska valley, Slovenia.
The color coding of pixels is as follows:
* red color - identified as likely built-up / artificial structure
* orange color - identified as likely bare-soil
* green color - identified as likely forest / trees
* blue color - identified as likely water
## Further info
If the reader is interested in more detail about how such a binary land-cover classifier is trained, we refer him to our Medium blog-post on this topic - [Area Monitoring: How to train a binary classifier for built-up areas](https://medium.com/sentinel-hub/area-monitoring-how-to-train-a-binary-classifier-for-built-up-areas-7f2d7114ed1c). This blog-post focuses on training and evaluating the built-up binary land-cover classifier, however the procedures and findings therein can be translated to other classifiers also.
All of these pixel-wise predictions are available also in the Browser-App to help understand the land-cover of specific FOIs. You can view them by choosing them in the drop-down just above the image chips:
As an example, the layer based on the forest classifier probability is shown. You can also choose the layer in the same way in the Timelapse window in the bottom left.
The outputs of these models are also available in the produced signal datasets we use to calculate other markers and can be used to find FOIs where we suspect that the claimed and actual land-covers differ substantially. One option is to calculate the temporal average of one of these signals for a multi-month period. FOIs with even small portions of built-up pixels can stand-out in this approach, since they have a higher average than FOIs without built-up pixels.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-how-to-train-a-binary-classifier-for-built-up-areas-7f2d7114ed1c) about Identifying built-up areas
[Examples](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/binary-land-cover-marker/examples/)
# Binary Land-Cover Marker Examples
## Agricultural field with built-up structures
### Description
The first example, FOI = [92287319](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92287319?from=2023-01-01\&to=2023-12-31\&selected=2023-03-01\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=SENTINEL2-BUILD-UP-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100\&key=NEAREST), is claimed to be an agricultural area. However, using the binary land-cover marker approach outlined above, we have found that part of the FOI is likely covered with artificial surfaces.
**Key findings:**
* The built-up mask (applied to Sentinel-2) clearly shows artificial structures within the agricultural area
* This finding is confirmed by the timelapse component in the bottom right corner of the screen
* External validation through [Roads and building detection](https://www.planet.com/pulse/mapping-all-of-earths-roads-and-buildings-from-space/) corroborates the presence of built-up structures
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92287319?from=2023-01-01\&to=2023-12-31\&selected=2023-03-01\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=SENTINEL2-BUILD-UP-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100\&key=NEAREST)
## Artificial surface with consistently low NDVI
### Description
The second example, FOI = [92288632](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92288632?from=2023-01-01\&to=2023-12-31\&selected=2023-09-06\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=SENTINEL2-BARESOIL-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), is also claimed to be arable land. However, we can clearly see from the example that the FOI is inconsistent with this claim due to consistently low NDVI values throughout the year.
**Key findings:**
* Constantly low NDVI values indicate absence of healthy vegetation
* The temporal pattern is inconsistent with typical agricultural land use
* Visual inspection confirms the presence of artificial surfaces rather than agricultural activity
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92288632?from=2023-01-01\&to=2023-12-31\&selected=2023-09-06\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=SENTINEL2-BARESOIL-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/crop-and-land-use-markers/)
# Crop and Land-Use Markers
## Basic info
The crop- and land-group markers can be used to determine consistency of a agricultural parcel (FOI) with its declared crop and land-use. Both markers use the same architecture, so we will describe the inner workings of both on the example of the **crop-group** marker.
## Further info
### Crop-group marker
Each FOI has a declared crop. The crop defines the behavior of the time-series of signals throughout the year. As an example, below we show the NDVI time-series of two FOIs. The one in blue has an associated crop with ID 005 (corn), while the one in orange has an associated crop with ID 204 (grass).
Clearly, both crops have vastly different behavior and should thus be easily recognizable. However, not all crops are as easily separable. Next we show two FOIs with declared winter wheat (blue) and winter barley (orange).
We can see that, ignoring the secondary crop sown after July, the two crops are pretty much inseparable. There are many such **crop groups** which are difficult to recognize them as separate with remote sensing. For instance winter grains that we show above, grass and grass-like annual crops like alfalfa, summer grains and many more. To achieve more accurate and reliable results, we often take advantage of these natural groupings and treat all crops inside the group as one training/prediction class, however this is not strictly necessary. We could treat each crop as a separate class in hopes of gaining the ability to intra-separate crops in groups, however this usually comes at a relatively drastic cost of performance, especially in confusion of crops within the same group. In Slovenia, there is approximately 200 crops grouped into 31 crop groups. Some of the more populous ones are grasses, winter grains and summer grains.
### Training of the model
The model that we train on the crop-group classes is a Long short-term memory (LSTM) model \[[1](https://arxiv.org/abs/1905.11893), [2](https://arxiv.org/abs/1910.10536)], which is based on the recurrent neural network architecture. This architecture is especially tailored to be able to recognize classes from patterns in time-series like satellite data.
The training data is always based on the desired year agricultural parcel reference data (declarations), however it is possible to include historical data if the reference data is made available. This helps boost the numbers of underrepresented classes, increasing the accuracy of recognizing classes which are rare in a specific year.
Since we use declaration reference data as our target classes, we need to make sure, to have the declarations as reliable as possible, since it is possible that declarations are incorrect. To clean some of the incorrect declaration noise out of the training data we use other markers, if they indicate a discrepancy between the claim and the real state. To be more concrete, we filter the FOIs based on:
* the outliers from the distance marker. As an example we show a FOI that has been declared as a meadow (204), however the distance and similarity markers point to this claim to likely be incorrect.
* the homogeneity marker, since it points-out FOIs that are likely heterogeneous and could thus confuse the model. An example of a FOI that apparently has several crops growing at the same time is shown below.
After the likely incorrect claims are filtered, the marker randomly divides all available FOIs into five folds: A, B, C, D and E. For each of these folds, a separate model is trained on the rest of the folds, after which a prediction is made on the specific fold that is left-out. As an example, when predicting on FOIs from fold A, we use the model trained on folds B-E and equivalent for other left-out folds. In this way, we can get predictions with models that have not seen a FOI during training for all FOIs in our dataset.
### Land-group marker
The basic building blocks of the land-group marker are exactly the same as for the crop-group marker. The only difference is that the declared land-use labels are grouped into land-groups instead of crops and used as training and prediction classes. Alongside agricultural land-uses, we also include non-agricultural ones to augment our training classes. The most prominent and interesting are forests and built-up land-uses.
| Built-up | Forests |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|  |  |
By including these non-agricultural land-uses we can hopefully be able to recognize them if an agricultural parcels land-use has transformed into an non-agricultural ones.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-crop-type-marker-1e70f672bf44) about Crop Type marker
[Examples](https://docs.planet.com/data/area-monitoring/markers/crop-and-land-use-markers/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/crop-and-land-use-markers/examples/)
# Crop and Land-Use Marker Examples
## High confidence in crop group prediction
### Description
The first example, FOI = [92278988](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92278988?from=2023-01-01\&to=2023-12-31\&selected=2023-10-03\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), is declared as wine (vineyard crop group). The classification marker unequivocally agrees with this declaration, showing 100% confidence that the FOI belongs to the vineyards crop group.
**Key findings:**
* Perfect match between declared crop type and predicted crop group
* 100% pseudo-probability score indicates very high model confidence
* Visual inspection confirms vineyard characteristics
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92278988?from=2023-01-01\&to=2023-12-31\&selected=2023-10-03\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Lower confidence in crop group prediction
### Description
The next example is FOI = [92269936](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269936?cropId=DEMO_FR23.CL_CROP.MIS\&from=2023-01-01\&to=2023-12-31\&selected=2023-04-05\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), which is claimed to be corn, belonging to the corn grain and silage (2) crop group. The crop-group marker shows mixed results:
**ARPS crop group classification:**
* Predicts "other oilseeds" with 80% confidence
**Sentinel-2 crop group classification:**
* Predicts "corn grain and silage" with 51% confidence (relatively low)
* Alternative prediction: "other oilseeds" with 44% confidence
**Technical interpretation:** Upon visual inspection, the claim appears correct. The presence of winter crop until late March likely postponed the corn greening period, which may have affected the classification. This example demonstrates the marker's confusion between very similar crops. The confusion between corn and oilseed crops can be attributed to both crop types having high NDVI values during summer, making the classes distinguishable but not trivially separable. Despite the mixed signals, both markers still suggest the claim is reasonable.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269936?cropId=DEMO_FR23.CL_CROP.MIS\&from=2023-01-01\&to=2023-12-31\&selected=2023-04-05\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/field-delineation/)
# Field Delineation
## Basic info
The field delineation marker produces boundaries of the agricultural parcels by clustering the agricultural pixels according to spatial, spectral and temporal properties. The delineated boundaries can aid the farmers speed up the declaration process and the paying agencies to better monitor changes in agricultural use.
| Sentinel-2 | Field delineations |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
|  |  |
The marker automatically outputs polygon vectors defining agricultural parcels based on Sentinel-2 imagery, although the marker can be seamlessly adapted to work with any remote sensing imagery as an input. The marker was developed as part of the NIVA H2020 project, and thus far has been used for generating parcels for paying agencies, insurance companies and research centres for several regions in Europe and North America.
The marker uses state-of-the-art deep learning (DL) algorithms. The codebase is available in a [GitHub repository](https://github.com/sentinel-hub/field-delineation), and a demo version is available on the [Euro Data Cube](https://collections.eurodatacube.com/field-delineation/).
## Further info
The marker can be fine-tuned to the users' needs, for instance using existing GSAA datasets to train a deep learning model, or can be used as an off-the-shell algorithm using a deep learning model pre-trained on a different AOI. The marker can estimate parcel boundaries for each cloudless pixel in a Sentinel-2 imagery, and the user can select the time interval over which estimates are aggregated. This approach allows to monitor changes in parcel boundaries, which reflect agricultural activity during the growing season.
In a nutshell, the following steps to produce boundaries of the agricultural parcels are performed:
* split the AOI into a regular grid to speed up processing through massive parallelization
* download remote sensing imagery for the time period of interest
* *(optional)* if GSAA data is available, train and evaluate the DL model on reference GSAA and remote sensing imagery
* predict and post-process agricultural parcel boundaries on remote sensing imagery for the time period of interest
*In case the reference labels are not available, we can also skip step 3 and employ a pre-trained network on data from a different AOI.*
### Splitting AOI into a grid
The AOI is split into a regular grid. Each cell, for example, EOPatch, of the grid has size as we find appropriate, and overlaps with the neighbouring cell a given amount of pixels. Splitting into cells allows to massively parallelize the processing, and the overlap ensures that the results are merged seamlessly. On the image below: Ukraine split into tiles of 10km x 10km, tiles are in their own UTM zone.
### Data download
For the selected time periods, remote sensing images are downloaded for each EOPatch as well as the cloud masks. Data downloading is executed using Sentinel Hub Batch Processing API.
### Analysis of cloud and snow coverage
Once the remote sensing imagery and cloud masks are available for each EOPatch, statistics over the available months are computed to estimate how many cloudless scenes are available. Our field delineation algorithm produces estimates for each available acquisition, however, only fields estimated for acquisitions with cloud and snow coverage below 5% of area of the EOPatch are typically kept and a consensus generated. This is performed in order to ensure that clouds and other artifacts do not affect the estimation of boundaries. On the image below: invalid observations over a month.
### Reference data and sampling (optional)
GSAA vectors are a great reference data for training of the ML model: for a given year, the majority of the GSAA parcels correctly match the agricultural land cover, with the exception of a minority of incorrect parcels resulting from outdated information or incorrect applications. If available, these vectors can be used to fine-tune the marker to improve its parcel boundary estimation.
The GSAA along with the remote sensing imagery is further sampled into smaller patchlets to speed up the training of the deep learning model. Using sampling, a constraint can be made on the minimal area covered by the reference GSAA in each sample, allowing to control the amount of positive and negative examples the model sees.
### Normalization
As we want our model to perform well over timestamps taken over the whole year, it is very important how the data is normalized. For each individual patchlet timestamp, statistics that could be used for normalization are calculated for each band. As well as computing overall statistics, we evaluate these temporally to establish whether a single or multiple normalization factors for the time period of interest are needed. We look at mean, standard deviation and quantiles for each month.
As mentioned above, in case the reference labels are not available to fine-tune our deep learning algorithm, we use an existing model trained on data in another AOI. In this case, a key factor to achieve meaningful results is to adequately normalize the input reflectance values, so that the input distributions for the area of interest (where the boundaries are predicted) are as aligned as possible to the reflectance distributions the model has seen during training.
### Semantic segmentation
We apply semantic segmentation on each single-scene separately, and combine predictions temporally at a later stage. A model trained this way should learn to be invariant to the time-period of interest. The aim of the parcel delineation in CAP practices is generally to monitor agricultural land cover throughout the growing season, but the beginning of the season is of particular interest as is typically the time the farmers fill in their applications. A model that can generalise to different time periods seems therefore useful in this perspective, and that justifies our choice of training a single-scene model and combining temporally the predictions in a second stage.
### Temporal merging
Once the model estimates field boundaries, for example, extent and boundary masks, for each timestamp for each EOPatch, these are temporally and spatially merged to derive a single probability map, which is then contoured to obtain the final vector polygons. The temporal merging generates a consensus of extent and boundary masks over a given time period (see example on figure below).
### Contouring
The consensus raster extent and boundary masks for the chosen time period are spatially merged and contoured to derive enclosed vector polygons. Parameters for the contouring can be optimised to control the appearance of the final polygons.
### Shape attributes
For each estimated polygon, we compute its area, circumference, shapeness and circumference/area (CA) ratio. Shapeness calculates the Hausdorff distance between the polygon and its minimum rotated rectangle, while the CA ratio provides an indication of the regularity of the polygon. These attributes can be used to further filter out polygons which are likely not cultivated, for example, with large areas and large values of shapeness (see some examples in the figure below).
### Dynamic analysis
The field delineation marker can be computed for different time periods, and the resulting polygons can be used to track and monitor agricultural activity. For instance, estimated parcels derived early in the season can be compared to parcels estimated at peak growing season, providing insights into whether the field boundaries changed or not.
The figures below show such a comparison, and the quantitative metrics that quantify changes in field contours, that can be further used to monitor agricultural activity.
 
The quantitative metrics can be computed for each estimated field, and used to derive overall insights into the performance of the marker, as well as into the changes due agricultural activity, as shown below. These plots show that parcels tend to change more at the beginning and end of the growing season, for example, from March to May and from August to October, due to ploughing and harvesting activities which can reduce the visibility of boundaries. Estimated parcels show less changes and are possibly more accurate at the peak of the growing season, for example, from May to July.
| | |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
|  |  |
## Links
[Webinar](https://www.youtube.com/watch?v=czRCApJCYIo): Automated Agricultural Field Delineation Tool
[Blog post](https://medium.com/sentinel-hub/parcel-boundary-detection-for-cap-2a316a77d2f6) about Parcel boundary detection for CAP
[Interactive interface](http://parcelio.sentinel-hub.com/) for viewing delineated fields in Lithuania for June 2020
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/greening-harvest-marker/)
# Greening and Harvest Marker
## Basic info
The greening and harvest marker identifies greening and harvest phases in the FOI's NDVI time series and combines them into a single period that signifies the life cycle of a crop. It can be a very useful tool for detecting presence of **catch crops** or **green cover** and **nitrogen-fixing crops**, for example, the management practices under the [EFA obligation](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=COM%3A2017%3A152%3AFIN) of which the main objective is to safeguard and improve biodiversity on farms. The greening and harvest marker can give answers to the following questions:
* When was the main crop sown and when harvested?
* After the harvest of the main crop, when did the second crop start developing?
* Until when was the second crop present on the field, for example, when was it harvested?
If greening and harvest marker is fused with bare-soil marker results, then the combined results can provide answers to questions like:
* How was the soil prepared before sowing of the main crop - was the field ploughed or not?
* Was the second crop established with undersowing?
* Before sowing of the second crop, was the field ploughed or did the farmer use some light cultivation techniques? Was the stubble left in the field after the harvest of the main crop?
The greening phase starts when the crop emerges from the soil (NDVI value is low) and ends when it fully matures (NDVI will reach a plateau). In between, NDVI values will steadily increase. When crop is harvested, plants are partially or entirely removed from the field. This activity is reflected in a sudden drop of NDVI value, often (but not necessarily) followed by a period when bare soil is detected. Harvest phase typically does not last long. Its detection is triggered by an abrupt and significant drop of the NDVI value.
The greening and harvest marker output can be visually presented with a plot, for example, like below for FOI, where we observe 2 greening periods and one harvest period in between.
The greening and harvest marker is a means to identify changes in the NDVI time series that indicate agricultural activity on a FOI. The greening/harvest phase reflects the duration of the change in the NDVI time series and therefore the period within which we expect the activity to have taken place.
* Light green strip corresponds to an extended greening phase, dark green strip to the "actual" greening phase.
* Similarly, light red strip corresponds to an extended harvest phase and dark red strip to the "actual" harvest phase. The distinction between the extended and "actual" phase becomes important when we condition the eligibility with, for example, the start of the greening phase or harvesting of the crop within a required or forbidden period. If we take a look at the harvest period and imagine a potential rule that the main crop should not be harvested before June 15th: the "actual" harvest period starts when we, for the first time, notice the consequence of the harvest, for example, a significant drop of the NDVI value, and this happened after June 15th. If we were validating the eligibility based on the start of the extended harvest phase, FOI would be found harvested before the June 15th and therefore ineligible.
* Observation marks enclosed in red diamonds indicate when bare soil was detected. We can, for example, mathematically describe a requirement for presence of baresoil observations before the greening or after the harvest phase, within a specified number of days. For undersown crops, the bare-soil before the greening phase is not required. However, for some practices, for example, for non-winter crops sown after the main crop, bare-soil might be mandatory.
* Black arrow indicates the total duration of one greening-harvest cycle.
The changes in vegetation cover are best visible in the Sentinel-2 False colour time series visualisation. In the image below, the green stripe on top of the images marks the greening phase, where we can observe the intensifying of the red colour within the FOI's boundary, indicating vegetation growth. After the vegetation reaches full maturity (and the NDVI value plateaus), we can observe the beginning of the harvest phase (marked with the yellow strip) as the intensity of the red false colour starts fading towards a more brownish colour, indicating the underlying soil, exposed after the vegetation removal. We can also see that towards the end of the harvest period, there are observations of exposed bare soil (marked with the brown icon). After harvest, we observe a new greening phase as the vegetation picks up again in late summer/early autumn.
## Marker output
In the [Area Monitoring App](https://docs.planet.com/data/area-monitoring/applications/area-monitoring-browser.md), the greening and harvest periods are marked with reddish stripes in the `Signals Markers Visualization` component at the bottom. The green stripe marks the greening phase and the red one indicates the harvest phase.
See example FOI = [92273921](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92273921?refId=\&cropId=DEMO_FR23.CL_CROP.MID\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-15\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Further info
For a detailed description of the greening and harvest marker output, check the [Marker Service API documentation](https://docs.planet.com/data/area-monitoring/marker-service-api.md#greening-harvest-marker).
## Links
[Examples](https://docs.planet.com/data/area-monitoring/markers/greening-harvest-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/greening-harvest-marker/examples/)
# Greening and Harvest Marker Examples
## Bare soil between harvest of the main crop and second crop
### Description
FOI = [92274649](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92274649?refId=\&cropId=DEMO_FR23.CL_CROP.ORP\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-13\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) had a spring barley (*Hordeum vulgare L.*) claim for the main crop. This NDVI time series indicates development of the main crop early in spring and harvest in mid-summer (see Area Monitoring App screenshot below).
**Key observations:**
* Greening phase detected early in spring
* Harvest detected in mid-summer as expected for spring barley
* Bare soil detected after harvest (marked with vertical brown lines in Signal component)
* Bare soil indicates agricultural practices that removed vegetation and exposed soil, such as ploughing
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92274649?refId=\&cropId=DEMO_FR23.CL_CROP.ORP\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-13\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Continuous vegetation cover indicating undersown second crop
### Description
FOI = [92276226](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276226?refId=\&cropId=DEMO_FR23.CL_CROP.ORP\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-28\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) had a spring barley (*Hordeum vulgare L.*) claim for the main crop. The NDVI time series indicates development of the main crop early in spring and harvest in mid-summer.
**Key observations:**
* Greening phase detected early in spring
* Harvest detected in mid-summer as expected for spring barley
* No bare soil detected after harvest
* The absence of bare soil after harvest indicates that a second crop might have been undersown
**Technical interpretation:** The continuous vegetation cover suggests that the second crop was planted before or shortly after the main crop harvest, maintaining soil coverage throughout the growing season.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276226?refId=\&cropId=DEMO_FR23.CL_CROP.ORP\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-28\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Gradual NDVI decline during harvest period
### Description
FOI = [92283161](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92283161?refId=\&cropId=DEMO_FR23.CL_CROP.POT\&from=2023-01-01\&to=2023-12-31\&selected=2023-08-04\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) had a summer squash (*Cucurbita pepo*) claim. The Signal component shows bare soil observations before and at the beginning of the greening phase. The harvest phase was detected in early autumn, as expected for this crop.
**Key observations:**
* Bare soil detected before and at the beginning of the greening phase
* Harvest phase detected in early autumn (appropriate timing for summer squash)
* Gradual NDVI decline during harvest period
**Technical interpretation:** During the harvest period, the NDVI decline was gradual, which could indicate that crop residues after harvest were left in the field to dry out rather than being immediately removed. This pattern is typical when harvest operations are spread over time or when plant material is allowed to desiccate naturally.
### Link
[See in Area Monitoring App](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92283161?refId=\&cropId=DEMO_FR23.CL_CROP.POT\&from=2023-01-01\&to=2023-12-31\&selected=2023-08-04\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/homogeneity-marker/)
# Homogeneity Marker
## Basic info
The homogeneity marker serves to identify fields (FOIs) on which several crops are being grown. It identifies heterogeneities on the scale of the FOIs declared primary crop's season and is not applicable to individual observations. That is the case, because a FOI could be heterogeneous in individual observations for many reasons.
Some of the most common short-period heterogeneities are the consequences of:
* farming practices like partial mowing, which is especially common on large meadows.
* intrinsic properties of the field, like intra-FOI differences of soil quality, moisture or many others.
Fast-growing crops are especially susceptible to such heterogeneities.
To eliminate the influence of such short-term heterogeneities, we evaluate heterogeneity of a FOI on a season time-frame by aggregating relevant signals into season-spanning features.
## Marker output
The most relevant signals include:
**Statistical measures:**
* Standard deviations and percentiles over the FOI's pixels for various signals (bands like B02, B03, or indices such as NDVI and NBSI)
**Land-cover classifiers:**
* We have developed land-cover classifiers that can determine the ratio of a FOI's pixels belonging to a certain land-cover type for each observation
* Examples include bare-soil (left) and built-up pixel masks (right)
* Red-colored pixels represent bare-soil and blue-colored pixels represent built-up land cover
* For some types of heterogeneities, FOIs are expected to have pixels that are consistently different in terms of their predicted land-cover class
| FOI = [92276534](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276534?from=2023-01-01\&to=2023-12-31\&selected=2023-02-12\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=SENTINEL2-BARESOIL-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) | FOI = [92287687](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92287687?refId=\&cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-05-01\&to=2023-08-01\&selected=2023-06-14\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=SENTINEL2-BUILD-UP-MASK\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
## Further info
The signals like the one listed above are aggregated into multi-month features for each signal inside a desired time-frame. For Slovenia, the most important averaging time-frame that has been identified is the 3-month averaging interval from 1st of May to 1st of August, since it coincides with the growing season of most crops. Below we show the distribution of `NDVI_std_3M_MAY`, which represents the feature we get by performing a three-month average of the `NDVI_std` from 1st of May to 1st of August. FOIs that are known to be homogeneous or heterogeneous are shown in orange and blue respectively.
Clearly, heterogeneous FOIs have higher `NDVI_std_3M_MAY` (similar for other features), which allows us to distinguish between homogeneous and heterogeneous FOIs. The homogeneity marker uses many such engineered features to assign a probability of a FOI being homogeneous. If the probability is larger than 35 (on a scale of 0-100) we classify the FOI as homogeneous, while for probabilities lower than 35 a heterogeneous classification is assigned.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-homogeneity-marker-742047b834dc) about Homogeneity marker
[Examples](https://docs.planet.com/data/area-monitoring/markers/homogeneity-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/homogeneity-marker/examples/)
# Homogeneity Marker Examples
## Persistent heterogeneity from multiple crops
Heterogeneities in the next example persist for long periods of time because several crops are being grown on this field. This represents a clear case of mixed-crop cultivation within a single declared agricultural area.
**Key characteristics:**
* Visible differences in vegetation patterns across the field
* Persistent heterogeneity throughout the growing season
* Multiple distinct crop areas within a single FOI
* Clear boundaries between different crop zones
| FOI = [92286354](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92286354?from=2023-05-01\&to=2023-11-01\&selected=2023-06-03\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) | FOI = [92275101](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92275101?from=2023-05-01\&to=2023-11-01\&selected=2023-06-03\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
### Links
See in Area Monitoring App: [left example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92278770?refId=\&from=2023-01-01\&to=2023-12-31\&selected=2023-04-06\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), [right example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92288301?refId=\&from=2023-01-01\&to=2023-12-31\&selected=2023-02-28\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Temporary heterogeneity from farming practices
Heterogeneities may also occur only for short periods of time due to farming practices such as partial mowing, which is especially common on large meadows. Unlike the persistent heterogeneity from multiple crops, this type of heterogeneity is temporary and related to agricultural management practices rather than mixed cultivation.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/mowing-marker/)
# Mowing Marker
## Basic info
The mowing marker identifies all observations where mowing events lead to a drop and subsequent recovery in the time series of vegetation index signals, such as the Normalized Difference Vegetation Index (NDVI). The algorithm works on any signal where mowing events introduce detectable changes in vegetation patterns.
## Further info
Mowing causes vegetation indices like NDVI to drop, as can be seen in the figure below showing NDVI time series around a labeled mowing event averaged over close to ten thousand events. For producing this image, NDVI time series of each FOI was shifted in time so that the observation with the minimal NDVI value during the mowing event is at day zero. The figure shows that NDVI drops on average by around 0.15 and that it takes around 20 days on average for NDVI to recover to values prior to the mowing event. The mowing marker algorithm searches for such drops and recoveries in NDVI time series.
Two versions of the marker are available:
**FOI-level marker:** Mowing detection is executed on a time series of a vegetation index, such as NDVI, aggregated over all pixels within a FOI.
**Pixel-level marker:** Mowing detection algorithm is executed on a time series of a vegetation index, such as NDVI, of each pixel within a FOI. Pixel-level mowing marker results are then aggregated over all pixels within a FOI into quantities like area of FOI that has been mowed at least once, largest connected area that has been mowed, etc. Such FOI-level information can later be used in the decision-making process.
**FOIs with detected FOI-level mowing event**
FOI = [92275267](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92275267?refId=\&cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-27\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) is declared as permanent meadow. The mowing marker detected one mowing event indicated with a vertical green band in the Signal component of the shown Area Monitoring App screenshot. True color ARPS images from the time period around the detected mowing event confirm that the FOI has been mowed.
**FOIs with detected pixel-level mowing event**
This FOI is declared as permanent meadow. The FOI-level mowing event detection finds no events. However, the pixel-level mowing marker finds that the eastern part of the FOI was mowed. Visual inspection shows that the western part of the FOI was also mowed during a second partial mowing event towards the end of the season.
**FOIs without a detected mowing event**
There can be many reasons why no mowing event is detected. For example:
* **Grazing instead of mowing:** A FOI is not mowed but is grazed. Grazing does not introduce such large sudden drops in the time series of vegetation indices, so grazing is typically difficult to detect.
* **Insufficient valid observations:** There are not enough valid observations available around the time the mowing event occurred. If Sentinel-2 observations are not available for a longer period due to cloud cover, then mowing events can't be detected with Sentinel-2. When this happens we can use alternative sources, such as Analysis Ready Planet Scope or Sentinel-1 to make an independent check if an area of a FOI was mowed or not.
* **Cloud obstruction:** An observation where evidence of mowing events is seen but partially obscured by a cloud or cloud shadow can be identified as invalid. The mowing marker algorithm can thus miss detecting such an event; however, an expert can correctly interpret the imagery and confirm that a FOI has been mowed.
* **Threshold limitations:** NDVI drop or recovery is just below the threshold applied by the algorithm. An expert can correctly interpret the imagery and confirm that a FOI has been mowed.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-mowing-marker-e99cff0c2d08) about Mowing marker
[Examples](https://docs.planet.com/data/area-monitoring/markers/mowing-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/mowing-marker/examples/)
# Mowing Marker Examples
## FOI-level mowing events
FOI = [92269889](https://area-monitoring.planet.com/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269889?refId=\&cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-27\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) is declared as permanent grassland. The analysis shown in the Area Monitoring App confirms this classification:
**Key observations:**
* From the beginning of the season in January until mid-July, all observations show vegetation (grass) present, indicated by high NDVI values in the Signals component
* The mowing marker detects 1 event at the end of July (one can observe clear NDVI drop and recovery pattern visible in the time series)
* Visual confirmation of mowing activity in satellite imagery
### Link
[See in Area Monitoring App](https://area-monitoring.planet.com/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269889?refId=\&cropId=DEMO_FR23.CL_CROP.PPH\&from=2023-01-01\&to=2023-12-31\&selected=2023-07-27\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&baseLayer=Satellite\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Partial mowing events
This FOI is declared as permanent meadow. The area of this FOI was mowed with several partial mowing events. Evidence of mowing in the middle part of the FOI is visible in the Sentinel-2 observations from June 29. Previous observations show evidence of mowing in the southern part.
**Key observations:**
* Multiple partial mowing events detected across different parts of the field
* Temporal sequence of mowing visible: southern area mowed first, followed by middle section
* Each mowing event affects only a portion of the total FOI area
* Pixel-level detection is more effective than FOI-level for partial mowing scenarios
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/ploughing-marker/)
# Ploughing Marker
## Basic info
Among the key indicators of effective agricultural land management is the detection of ploughing activity. The ploughing marker plays a critical role in confirming field maintenance and ensuring compliance with regulations, especially as subsidies shift towards more environmentally conscious practices. In regulatory scenarios, it is important to determine whether fields are ploughed during restricted periods when such activity is prohibited.
The ploughing marker serves the crucial purpose of identifying periods when a field has been ploughed, resulting in exposed bare soil. While ploughing activity may not be directly observable in satellite imagery such as Sentinel-2 or Analysis Ready Planet Scope data, its effects manifest over time and can be detected through careful analysis of signal values.
## Further info
Ploughing induces a rapid transition from vegetated to bare soil surfaces, a transformation that registers in signal values as a notable increase in bare-soil probability. The higher this probability, the more confidently we can infer the presence of freshly ploughed soil. By observing a sharp and substantial rise in this probability, we can determine when ploughing occurred. The start of the ploughing interval is marked by the onset of this increase, while its end is signified by a plateauing of the probability value.
**Signal relationships:** It is worth noting the inverse relationship between bare-soil probability and NDVI (Normalized Difference Vegetation Index) values, which reflect vegetation vigor. When bare-soil probability is high, NDVI values tend to be low, indicating diminished vegetation cover.
**Example case:** The wheat field [92276773](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92276773?from=2023-01-01\&to=2023-12-31\&selected=2023-08-21\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&validSignal=true\&layer=SENTINEL2-FALSE-COLOR\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100) shown below was vegetated until the end of May and had exposed bare soil between August and October. In this same period, we observe a distinct increase in the bare-soil probability and drop in NDVI value, which indicates the field was ploughed.
## Marker output
The output of the marker consists of ploughing events, defined by distinct dates during the period when the bare-soil probability significantly increased, and corresponding bare-soil probabilities on these dates. Users can control the number of false positive and false negative events by setting marker parameters, such as the required magnitude of rise in bare-soil probability for an event to be valid.
For a detailed description of the ploughing marker output, check the [Marker Service API documentation](https://docs.planet.com/data/area-monitoring/marker-service-api.md#ploughing-marker).
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-bare-soil-marker-608bc95712ae) about Bare-soil marker
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/similarity-and-euclidian-distance-marker/)
# Similarity and Euclidian Distance Marker
## Basic info
Similarity and Euclidean distance markers belong to the group of crop classification markers. Output of both markers can be used to check validity of a FOI's claim. In their essence both markers compare signal time series of a FOI to signal time series of neighboring FOIs. The way the comparison is made is different between the two markers and will be described below. Similarity and Euclidean distance markers perform statistical comparison and do not require any model training, which is their biggest advantage.
### FOI's neighborhood
Both markers compare a FOI's signal time series to other FOIs in its neighborhood. Area of interest (for example, Slovenia in this demo) is divided into smaller hexagons as shown in the Figure below. Each FOI is assigned to exactly one such hexagon based on location of FOI's centroid. Distance between the opposite edges of a hexagon is 7.7 kilometers. Neighboring FOIs are pooled among FOIs that are located within the same hexagon, or the same hexagon plus a ring of 6 neighboring hexagons, depending on marker configuration.
## Further info
### Similarity score
Similarity marker evaluates how *similar* a FOI is to other FOIs from its neighborhood having the same (or different) claim based on time series of a signal. Typically we use Normalized Difference Vegetation Index (NDVI) for easier interpretation. For example, how similar is a cornfield to other cornfields in its vicinity? Similarity is calculated by comparing a FOI's NDVI time series to an average NDVI time series of FOIs from its vicinity having the same (or different) claim. Comparison is therefore between a FOI and average of many other FOIs that are located near this FOI.
The process of calculating the similarity score for this "target" FOI is the following (we use winter wheat as an example):
1. Identify up to 100 (configurable) FOIs within the neighborhood of the target FOI that claim to cultivate the same crop.
2. Calculate average and standard deviation of the NDVI time series of the identified neighboring FOIs. This average and standard deviation are used as a reference NDVI time series in the calculation of the similarity score. They illustrate how the NDVI of winter wheat should evolve over the season.
3. Calculate similarity score for crop $X$, which is defined as:
$$sim(FOI_A, CROP = X) = \sum_{i}^{\mathrm{valid}\,\mathrm{obs.}} \left( \frac{ P_A^i(NDVI) - \bar{P}^{i}_{\mathrm{neighbors\ with\ crop}=X}(NDVI) }{ \sigma^{i}_{\mathrm{neighbors\ with\ crop}=X} } \right)^2 \Big/ n_{\mathrm{valid}\,\mathrm{observations}}\,.$$
where the sum runs over all valid observations of a FOI with index $A$, $P_A^i(NDVI)$ represents the NDVI value of FOI $A$ on date $i$, and $\bar{P}^{i}_{\mathrm{neighbors\ with\ crop}=X}(NDVI)$ and $\sigma^{i}_{\mathrm{neighbors\ with\ crop}=X}$ represent the average and standard deviation of NDVI over neighboring FOIs with claimed crop $X$ on date $i$. $n_{\mathrm{valid}\,\mathrm{observations}}$ represents the number of all valid observations.
Figure below shows the comparison of NDVI time series of a FOI claimed to grow winter wheat and an average of 100 neighboring FOIs with the same claim. Numerator in the above equation, $P_A^i (NDVI) - \bar{P}^{i}_{neighbors~with~crop = X} (NDVI))$, is shown in the figure with red arrows and the denominator, $\sigma_{neighbors~with~crop = X}^I$, is shown with blue arrows. The figure nicely illustrates that the shorter the red arrows are, the more similar the FOI is to its neighboring FOIs with a given claimed crop.
We often refer to crop $X$ as hypothesis. For every FOI we can calculate as many similarity scores as there are different crop types - hypotheses. By doing this we can not only answer questions like "*Is signal of a FOI similar to signals of other FOIs with the same claim?*", but also "*What is the crop type of FOIs to which signal of a FOI is most similar to?*".
Values of the similarity score, $sim(FOI_A, CROP = X)$, are difficult to interpret. To make the interpretation easier we transform the scores in a such a way that a similarity score distribution for crop $X$ of all FOIs with a claim to grow crop $X$ is a flat distribution between 0 and 100. In other words, we transform the value of each score to a corresponding percentile.
Figure below shows the transformed similarity score distributions for winter wheat hypothesis for FOIs claiming to grow:
* winter wheat, $sim(FOI(\rm{winter~wheat}), CROP = \rm{winter~wheat})$,
* grass, $sim(FOI(\rm{grass}), CROP = \rm{winter~wheat})$,
* and corn, $sim(FOI(\rm{corn}), CROP = \rm{winter~wheat})$,
As it can be seen the distribution of $sim(FOI(\rm{winter~wheat}), CROP = \rm{winter~wheat})$ is a flat distribution, but $sim(FOI(\rm{grass}), CROP = \rm{winter~wheat})$, and $sim(FOI(\rm{corn}), CROP = \rm{winter~wheat})$ peak towards 100. These distributions show, that if a FOI claims to grow winter wheat, but in reality is growing corn, then its similarity score for winter wheat hypothesis will be high, close to 100. On the other hand if a FOI claims to grow winter wheat, but in reality it grows grass, then its similarity score for winter wheat hypothesis will be high, but not as high as in the case of corn. The reason is that NDVI time-series of FOIs growing grass are in average more similar to FOIs growing winter wheat than FOIs growing corn.
### Euclidean distance
Euclidean distance or distance marker evaluates how *near* in Euclidean distance metric space a FOI is to other nearby FOIs. The distance is evaluated in the feature space defined by a FOIs' NDVI time-series, but in principle any other signal can be used. Marker evaluates the Euclidean distance between signals of two FOIs $A$ and $B$ using the following equation:
$$dist(P_A, P_B) = \frac{\sqrt{\sum_{i} \big(P_A^i (NDVI) - P_B^i (NDVI) \big)^2}}{n_{\rm observations}}$$
where $P_A^i(NDVI)$ and $P_B^i(NDVI)$ represent NDVI values for FOIs $A$ and $B$ on date $i$, respectively. The sum runs over all available valid values within crop specific time interval, which is denoted as $n_{\rm observations}$. If the claim is corn, for example, then the sum runs over all valid values between May 15 and September 15, and if in the case of winter wheat, claim the sum runs over all valid values between April 15 and August 15. These intervals were optimized to maximize the differences between different crop types. Left (right) figure below illustrates calculation of a distance between a FOI with a claim to grow corn and another FOI from its neighborhood with a claim to grow corn (winter wheat). The red arrows show in both figures the difference between NDVI values, $P_A^i(NDVI)-P_B^i(NDVI)$, for all dates that enter the calculation of the distance between these pairs of FOIs. The shorter the red arrows are, the shorter the Euclidean distance between the pair of FOIs.
| Distance between a FOI(corn) and a FOI(corn) | Distance between a FOI(corn) and a FOI(winter wheat) |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|  |  |
The above explanation describes how Euclidean distance metric between NDVI signals of pair of FOIs is calculated. The distance marker score of a target FOI for crop hypothesis $X$ is calculated in the following way:
1. Identify up to 500 (configurable) FOIs claimed to grow crop $X$ in the neighborhood of target FOI. Neighborhood is limited to the same hexagon or hexagon plus a ring of neighboring hexagons as described above. This is configurable.
2. Calculate Euclidean distances as described above for all pairs of target FOI and a neighboring FOI with crop claim X.
3. Calculate average distance between the target FOI and neighboring FOIs with crop claim X. Average distance represents the distance marker score and is calculated for all possible crop hypothesis.
4. Transform distance marker scores in such a way that a distance score distribution for crop $X$ of all FOIs with a claim to grow crop $X$ is a flat distribution between 0 and 100. This is done in the same way as in the case of similarity marker.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-similarity-score-72e5cbfb33b6) about Similarity and Euclidian distance marker
[Examples](https://docs.planet.com/data/area-monitoring/markers/similarity-and-euclidian-distance-marker/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/markers/similarity-and-euclidian-distance-marker/examples/)
# Similarity and Euclidian Distance Marker Examples
## Similarity marker examples
The Area Monitoring App screenshots below show two FOIs, both claiming to grow winter barley. The example on the left is found to be consistent with this claim according to the low similarity marker score, while the example on the right shows high similarity score and therefore inconsistency with the claimed crops as demonstrated in the similarity marker scores bar chart.
| Consistent with winter barley claim (FOI = [92275442](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92275442?cropId=DEMO_FR23.CL_CROP.ORH\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-17\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)) | Not consistent with winter barley claim (FOI = [92274515](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92274515?from=2023-01-01\&to=2023-12-31\&selected=2023-08-24\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)) |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  |  |
### Links
See in Area Monitoring App: [left example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92275442?cropId=DEMO_FR23.CL_CROP.ORH\&from=2023-01-01\&to=2023-12-31\&selected=2023-05-17\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), [right example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92274515?from=2023-01-01\&to=2023-12-31\&selected=2023-08-24\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
## Euclidean distance marker examples
The Area Monitoring App screenshots below show two FOIs, both with a temporary prairie claim. The example on the left is found to be consistent with this claim according to the low distance marker score, while the example on the right with the high distance score is not. The latter is more similar to FOIs that claim to grow potato (PTC).
| Consistent with temporary prairie claim (FOI = [92269340](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269340?cropId=DEMO_FR23.CL_CROP.PTR\&from=2023-01-01\&to=2023-12-31\&selected=2023-08-09\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)) | Not consistent with temporary prairie claim (FOI = [92281419](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92281419?from=2023-01-01\&to=2023-12-31\&selected=2023-06-02\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
### Links
See in Area Monitoring App: [left example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92269340?cropId=DEMO_FR23.CL_CROP.PTR\&from=2023-01-01\&to=2023-12-31\&selected=2023-08-09\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100), [right example](https://am-pilot.sinergise.com/phoenix/scopes/DEMO_FR23/foi-view/DEMO_FR23.FOI.92281419?from=2023-01-01\&to=2023-12-31\&selected=2023-06-02\&markerContext=DEMO_FR23.MARKER_CONTEXT.1429\&upsampling=NEAREST\&validSignal=true\&layer=ARPS-NDVI\&displayByWeek=false\&observationsPerRow=6\&padding=10\&overlays=%5B%22FOI%22%2C%22FOIs%22%5D\&pageIndex=0\&pageSize=100)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/references/)
# References
## Slovenia
### Agency for agricultural markets and rural development
We have been running an automated and continuous Checks-by-Monitoring (CbM) process with the Slovenian Paying Agency. Starting the activity in 2020 in prototyping mode, we completed the first run of our production-ready application in 2021, performing analysis using all available observations on more than 800 000 parcels, a process now continued in this and coming years.
We provide, on bi-weekly basis, the following services:
* signal processing of the Sentinel-2 and Analysis Ready Planet Scope data (as an additional data source for small and inconclusive parcels),
* training of the crop- and land-classification models,
* computation of the markers,
* producing the Traffic Light System results for the basic payment scheme which was covered by eleven different scenarios tailored for specific land-use or crop types and
* provide these results to operators (using Expert Judgement Application) and farm holders (using Application for communication with farmers and a Geo-tagged photo app).
With the experience and confidence gained over the first year, we are now expanding the monitoring in Slovenia to winter & non-winter crops, and adding numerous new payment schemes. This requires developing new markers and improving the accuracy of existing ones.
### Statistical office of the Republic of Slovenia
Together with partners from Research Centre of the Slovenian Academy of Sciences and Arts, and University of Ljubljana, Faculty for Civil and Geodetic Engineering, we are working on markers for long-term monitoring of grasslands and meadows at the country scale. Due to requirements to look up to 20 years back in time there is a need to use a combination of Sentinel-1, Sentinel-2 as well as Landsat missions. Our focus is on:
* identifying the yearly pixel-level counts of mowing events, and
* detecting the yearly pixel-level bare soil presence, used for determining the age of permanent meadows.
The output of the project, in addition to marker results themselves, will be a Python package, which will be available to all statistical offices across Europe, to be able to perform these kinds of analyses at continental scale.
The project is co-funded by Eurostat.
## Lithuania
### National paying agency
Automatic agricultural field delineation tool was tested as a part of "Prefilled Application", aiming to benefit the farmers by using preliminary information on parcel boundaries and their attributes in order to reduce the time spent filling applications and the number of farmers' errors (part of H2020 NIVA project).
Within H2020 DIONE project we have been providing the area monitoring markers service for the Lithuanian agricultural parcels for two consecutive years. The Agency has validated the markers' outputs based on the in-situ data, focusing on crop group classification and mowing events detection.
## Cyprus
### Cyprus agricultural payments organization
Within H2020 DIONE project we have been providing area monitoring markers service for Cyprus Agricultural Payments Organization (CAPO) for years 2020, 2021 and 2022. We have closely cooperated in combining the markers' outputs into Traffic Light decisions.
## Estonia
### The agricultural registers and information board
We performed a country-wide feasibility study to check the applicability of the existing methodology and tools in the Estonian landscape to identify the required steps toward a fully operational Area Monitoring System.
We designed a Traffic Light System decision logic to identify:
* the presence of ineligible areas - in particular permanent structures, buildings, roads etc.,
* the presence of ineligible land use - overgrown areas where agricultural activity is not possible,
* inconsistency between the declared land use category (permanent crop, permanent grassland, arable land) and state in the field.
In addition to Sentinel-2, tests were performed using Planet Fusion and Sentinel-1 6-day coherence signals.
## Ukraine
As a part of the EO4UA initiative we have, in cooperation with Joint Research Centre, automatically delineated agriculture parcels for each of the years from 2016 to 2022. The data are being used to assess the impact of the war to agriculture in Ukraine.
## Italy, Veneto
### Paying agency of the Veneto region
In 2021 we performed an Area Monitoring feasibility study for a subset of municipalities in the Veneto region. We produced the markers for the selected areas for 2020, and the Agency validated them using the existing in-situ data.
## European Union
### Österreichische Hagelversicherung VVaG
Automatic field delineation and early season crop type classification pilot was performed to assist the insurance company with assessment of yield losses due to natural disasters.
Main challenges tackled were related to the lack of ground truth data (several countries in European Union do not have publicly accessible LPIS data) and differentiation of various winter grain varieties early in the season.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/signal-processing/)
# Signal Processing
## Basic info
Area Monitoring system depends on the vast amount of full-area, multi-temporal indirect signals from the remote sensing data, which are translated into interpretable markers and scenarios, derived over features of interest (FOI). The initial inputs of the Area Monitoring system are therefore farmers’ data from the Geospatial Aid Application (GSAA) dataset, providing information about parcel boundaries, attributes and measures, and the available satellite imagery. We extract the reflectance values from the imagery pixels that are completely within FOIs boundaries. The figure below shows a true-colour visualisation from four different Sentinel-2 observations for a typical FOI with corn. The FOI’s boundaries are shown in yellow and the boundary of all non-border Sentinel-2 pixels within it is shown in red.
The reflectances are then converted to vegetation indices, which are statistically summarised (obtaining mean, standard deviation, minimum and maximum) per FOI. Furthermore, we need to apply an appropriate data filtering to obtain high-quality data for detecting changes triggered by agricultural activities. The filtering includes removal of the cloudy observations and of other invalid observations.
Time-series of mean Normalized Difference Vegetation Index (NDVI) for the same FOI as mentioned above is shown as a green dashed and solid line in the figure below. Sudden drops of NDVI are due to invalid observations, which were identified and filtered out with Sentinel Hub’s s2cloudless cloud masking algorithm and observation outlier detection algorithm. The red vertical line on the time-series plot corresponds to the first Sentinel 2 image on the left. The green dots indicate all remaining valid observations which are used for the calculation of the markers.
*Copernicus Sentinel data are, due to their radiometric characteristics, multi-temporal richness and affordability over large areas, the main data source for the Area Monitoring. The Sentinel-2 can be used for monitoring of the majority of the agricultural area and this is why the following sections describe the processing its data. We also use a commercial very-high resolution Analysis Ready Planet Scope or Planet Fusion data, for the parcels not monitorable with the Sentinel-2. You can read more about the challenges of small parcels in this [blog post](https://medium.com/sentinel-hub/area-monitoring-the-challenge-of-small-parcels-96121e169e5b).*
## Further info
### Download and processing of satellite images over large areas
If we want to obtain the signals from the satellite images over larger areas, for example, for the whole country, for several months, we need to do this efficiently. For this purpose, we are using the `Sentinel Hub’s Batch Processing API`, which splits the area of interest in managable smaller chunks, downloads various indices and raw bands for each available date, then creates a harmonized time-series feature by filtering out cloudy data and interpolating values to get uniform temporal periods. The outputs of a batch processing are stored to the object storage. On the image below, workflow overview of the Batch Processing commands, and the different statuses that can be triggered.
### Cloud detection
Cloud detection is the most crucial step during the pre-processing of optical satellite images. Failure to mask out the clouds from the image will have a significant negative impact on any subsequent analyses. We are using pixel-based cloud mask on Sentinel-2 imagery computed with the in-house developed machine learning algorithm, [s2cloudless](https://github.com/sentinel-hub/sentinel2-cloud-detector), which has also become one of the state-of-the-art algorithms for cloud detection. `s2cloudless` assigns each pixel a cloud probability based on the pixel’s ten Sentinel-2 band values. Cloud probabilities and masks are available through the Sentinel Hub services when requesting L1C or L2A data for the entire Sentinel-2 archive. Below, a screenshot from EO Browser with a simple custom script for masking out the clouds using the cloud mask information from the Sentinel Hub service.
### Outlier detection
Once the cloudy observations have been filtered out, we are left with a mixture of valid observations and a set of undetected anomalous observations. The latter are mostly caused by cloud shadows, snow and haze. Below, see some examples of outliers.
We have developed a supervised machine learning model, which was trained on hand-labeled data of agricultural parcels over Slovenia, collected in 2019. The output of the model is binary: an observation is classified as an outlier if the pseudo-probability is above some threshold. Below, the NDVI time-series of a FOI with filtered out outlier observations - the marked observations correspond to the outlier examples from the previous image.
## Links
[Blog post](https://medium.com/sentinel-hub/large-scale-data-preparation-introducing-batch-processing-b3a58755b8a1) about large-scale data preparation
[Blog post](https://medium.com/sentinel-hub/area-monitoring-data-handling-c255b215364f) about data handling
[Blog post](https://medium.com/sentinel-hub/improving-cloud-detection-with-machine-learning-c09dc5d7cf13) about about development of the cloud detection algorithm
[Blog post](https://medium.com/sentinel-hub/cloud-masks-at-your-service-6e5b2cb2ce8a) about cloud masks available on Sentinel Hub
[Blog post](https://medium.com/sentinel-hub/area-monitoring-observation-outlier-detection-34f86b7cc63) about observation outlier detection
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/traffic-light-system/)
# Traffic Light System
The Traffic Light System (TLS) evaluates logical rules that compare observed conditions with criteria for compliance to a particular scheme/measure. It assigns one of the following codes to each Field of Interest (FOI):
* **Green**: FOI assessed and confirmed as compliant
* **Yellow**: FOI assessed but there is insufficient evidence neither to confirm nor reject explicitly the declared scheme / measure
* **Red**: FOI assessed and confirmed as definitely non-compliant
The TLS for the basic payment scheme for Slovenia covers eleven different scenarios, where each scenario incorporates the use of markers and rules and is specially tailored for a specific land-use or crop type.
## Further info
Within the basic payment scheme, it is more important to distinguish whether or not parcels are actually managed with some definite agricultural activity, rather than provide evidence that the crop claimed is actually the one grown. Hence, if evidence of any farming activity is found among markers and signals for a FOI, then this FOI is assigned a Green, even if, for example, corn is cultivated on an FOI claimed as winter wheat. Thus, the TLS searches for evidence of presence or absence of farming activity using the following markers:
* **Mowing marker** searches for evidence that a FOI has been mowed.
* **Bare-soil marker** searches for evidence that a FOI has been ploughed.
* Consistency of a claim is checked with **crop-group classification marker, similarity marker**, and **Euclidian distance marker**. If signals of a FOI are found to be consistent with signals of other FOIs with the same claim, then this serves as indirect evidence of farming activity. Corn, winter wheat, or vegetables, for example, do not grow by themselves without any farming activity, such as ploughing, sowing, and harvest.
* Consistency of a claim of permanent crop, for example, hops, fruit trees, etc., is checked with **land-use marker**, **similarity marker**, and **Euclidian distance marker**.
* **Homogeneity marker** identifies FOIs with heterogeneous land use that produces noisy signals which cannot confidently be assessed by the above markers.
* **Mean-NDVI marker** identifies FOIs with very little vegetation cover. A FOI can lose vegetation cover, for example, when it is turned into a built-up area.
Scenarios are adjustable to business rules of each country’s Paying Agency. The marker system and the TLS are configurable and the Expert App, as well as supporting manual evaluation, enables and supports detailed review phases to check and optimise algorithms and decision thresholds.
Scenarios 5 (Arable Land/Annual crops) and 6 (Meadows and Grasses) are probably the most important ones in most countries. In Slovenia they represent over 90% of all FOIs. In the accompanying two documents we will go through the decision logic of these two scenarios with detailed examples for some of possible decisions.
## Links
[Blog post](https://medium.com/sentinel-hub/area-monitoring-traffic-light-system-4a1348481c40) about Traffic Light System
[Examples](https://docs.planet.com/data/area-monitoring/traffic-light-system/examples.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/traffic-light-system/examples/)
# Traffic Light System Examples
## Slovenia use-case
### Arable land
The decision tree for FOIs growing annual crops on arable land is visualized below. The decision tree utilizes information provided by the following markers: *mean NDVI*, *bare soil*, *homogeneity*, *crop-group classification*, *similarity*, *distance*, and *mowing* marker. The tree consists of internal (decision) and end leaf (decision taken) nodes. The latter are colored Green or Yellow, depending on whether markers provide evidence of farming activity or not. Each end node has a unique numeric identifier assigned, which is specific to the Slovenian project but irrelevant for understanding how TLS works and what value it provides. At the moment Red is not automatically assigned, but this will change in the future. Each internal node poses a question, where results of a marker are used to test a FOI's compliance with the rules. Numbers written next to the lines or branches that connect the nodes represent the number of FOIs that pass through this branch. From the diagram below, we can read that 171,365 FOIs fall under this scenario and 155,856 of them get a green assignment because the predicted crop group is consistent with the claimed one.
In the rest of the document, we will walk through the diagram, describing in short the motivation for each decision node, and give a few example FOIs for some of the end nodes.
#### Scenario input
Input to this scenario are all FOIs claiming to cultivate annual crops on arable land. There were 171,365 such FOIs monitored with Sentinel-2 in Slovenia 2021. The query written in the topmost box selects FOIs that belong to this scenario based on their claimed land use and crop group types.
#### FOIs without or low fraction of valid observations
A very small number of FOIs have no or very few valid Sentinel-2 observations. These cannot be confidently processed with the markers and are tagged as Yellow in end nodes `00-00-03` and `10-10-0`, respectively.
#### FOIs with low mean NDVI
This node checks if NDVI averaged over all FOI's valid observations between the growing season of most plants (May 1 and October 15) is above a threshold. Vegetation should cover the area of a FOI for at least a fraction of the time, and if vegetation is present only shortly or not at all, then perhaps the area was not used for farming. One such example is a FOI (see screenshot below) that claims to grow corn. Signals and markers suggest that this FOI had exposed bare soil for most of the season, except for a short period in August. The data suggests that no crop was sown on the field.
#### Large and not homogenous FOIs
Next we check with the help of homogeneity marker if an area of a FOI represents homogenous land use or crop type. In the node *Large and not homogeneous* we declare all FOIs as heterogenous if they contain at least 9 Sentinel-2 pixels and have homogeneity marker output below a threshold. An example heterogeneous FOI in the screenshot below claims to grow corn. The NDVI of this FOI (green points) do not follow average NDVI signal of other FOIs growing corn in its neighborhood (blue line and blue band). We can see why this is from the Sentinel-2 observations. The left half of the FOI is used to cultivate a crop in the beginning of the season, which is harvested around end of June. The right half of the FOI is bare in the beginning of the season. Vegetation begins to appear in June. This is most likely corn, which is cultivated only on the right half of the FOI.
#### Consistent with claimed crop group
Consistency with claimed crop group is checked by crop-group classification, similarity and distance markers. These markers are used as proxy for detecting farming activity, since annual crops do not grow by themselves. Below we give a few example FOIs that are given a Green assignment in this node. If a FOI fails at this node, it still does not get assigned a Yellow, since the main basic payment scheme requirement is that farmland is farmed. It is not important what kind of crop is cultivated on arable land, as long as it is being farmed. In the remaining nodes of this tree we check if signals provide any evidence of farming activity. If the answer is yes, then a FOI that fails crop-group consistency check can still get a Green assignment.
| Consistent with claimed winter wheat | Consistent with claimed corn |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|  |  |
| Consistent with claimed summer oat | Consistent with claimed winter barley |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|  |  |
#### Crop group prediction consistent with grassland
FOIs that reach this node are inconsistent with the claimed crop group. This means that the signals suggest that something else is cultivated on a FOI. This can be another type of annual crop cultivated on arable land or it can be grassland growing on arable land, or even permanent meadow. In this node we divide FOIs with wrong claims into two groups: the first one (following the YES branch) consists of FOIs that are predicted to grow grass, clover, grass-clover mixtures, or are permanent meadows. The second one (following the NO branch) consists of FOIs that are predicted to grow some other annual crop on arable land. FOIs need to be divided into two groups because the farming activity expected for these two groups is different. FOIs from the first group are expected to be mowed, while the FOIs from the second one are expected to be ploughed. We therefore look for mowing events on the right-hand side and bare-soil observations on the left-hand side of the decision tree below this node.
#### (Pixel) Mowing detected
As explained above, FOIs that go through the right-hand part of the decision tree are most likely growing grass, clover, grass-clover mixture or are permanent meadows according to the crop-group classification marker. The expected farming activity on these FOIs is mowing. If mowing event is detected, then these FOIs get assigned green. An example FOI below is claimed to grow winter wheat. Crop-group classification and similarity markers disagree. Both of them suggest that a grass-like crop is growing on this FOI. The mowing marker detects three mowing events: one in June, one in July, and one in August. The bare-soil marker identifies no bare-soil observations.
#### Confident in other crop group
Business rules for Basic Payment Scheme in Slovenia do not require that claimed crop is being cultivated. What matters is that land is being farmed. This means that if a crop-group classification marker is confident that some other crop is cultivated on a FOI and not the crop being claimed, then such FOI still needs to get a Green assignment. The reasoning being the same as in the case of *Consistent with claimed crop group* node described above. Below we show a few example FOIs for which the predicted crop group differs from the claimed one, but signals and markers confirm that FOI is being farmed.
| Claimed annual herbs; predicted winter wheat | Claimed winter barley; predicted corn |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
| NDVI time series is not consistent with NDVI time series of other herbs. Found to be consistent with time series of winter wheat and other similar crops. Bare-soil observations identified after harvest, followed by raise of NDVI and again bare soil. The latter suggest that secondary crop was cultivated on the FOI after the winter wheat, which was used as green manure at the end of September. | NDVI time series not consistent with NDVI time series of winter barley. Found to be consistent with corn. Bare-soil observations found before corn was sown and after the harvest as expected for corn fields. |
| Claimed vegetables; predicted winter barley | Claimed winter barley; predicted winter wheat |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
| NDVI time series of this FOI is consistent with that of winter barley. Bare-soil observations are identified during the summer, after the harvest, after which some other crop is growing on a FOI. | Winter barley and winter wheat have similar NDVI time series. Crop-group classification model often predicts winter wheat where winter barley is claimed and vice versa. This FOI shows that perhaps it does not make sense to have separate crop groups for winter wheat and barley in the case of Basic Payment Scheme. If these two crops would be in the same group, then this FOI would get an assignment of Green in the *Consistent with claimed group* node. |
#### Bare-soil detected
The last node in both parallel branches of the tree checks, if bare-soil has been detected, which indicates that a FOI has been ploughed and thus is being farmed.
Example below claims to grow triticale. Crop-group classification marker is not convinced in its prediction. Nevertheless, two bare-soil observations have been identified at the beginning of June. NDVI raises quickly after that, indicating that some crop has been sowed in the beginning of the summer. Signals and markers suggest that this FOI is being farmed.
The next example gets assigned Yellow by this node. This FOI claims to grow corn, which is not supported by the signals and markers as shown in the screenshot below. It seems that vegetation never really develops on this FOI and bare soil is also not detected. Since no evidence of farming is found the FOI is assigned Yellow.
### Grassland
The decision tree for grassland FOIs is visualized below. Grassland FOIs in Slovenia consist of FOIs on arable land growing grass, clover, grass-clover mixtures up to five years, and of permanent meadows. The decision tree utilizes information provided by the following markers: *mean NDVI*, *bare soil*, *homogeneity*, *crop-group classification*, *similarity*, *distance*, and *mowing* marker. From the diagram below, we can read that 394,739 FOIs fall under this scenario and over 360 thousand of them are found to be consistent with the claimed crop group and have at least one mowing event detected with regular or pixel mowing markers.
In the rest of the document, we will walk through the diagram, describing in short the motivation for each decision node, and give a few example FOIs for some of the end nodes.
#### Scenario input
Input to this scenario are grassland FOIs claiming to cultivate grass, clover, or grass-clover mixtures on arable land and permanent meadows. There were 394,739 such FOIs monitored with Sentinel-2 in Slovenia 2021. More than half of all monitored FOIs in Slovenia go through this scenario. The query written in the topmost box selects FOIs that belong to this scenario based on their claimed crop group types.
#### FOIs with low mean NDVI
Grassland FOIs are expected to be vegetated throughout the season, especially during the summer. If a FOI claimed as grassland has an extremely low mean NDVI value, then this strongly suggests that in fact it is not a grassland FOI. At the moment such FOIs are assigned Yellow, but in the future they will get assignment Red. Below we show an example FOI that ends in this node. Sentinel-2 imagery and signals suggest that a permanent meadow has turned into a construction site in April and at the end of October a bright built-up area is seen.
#### Large and not homogeneous FOIs
In the node *Large and not homogeneous* we declare all FOIs as heterogeneous if they contain at least 9 Sentinel-2 pixels and have homogeneity marker output below a threshold. Below we show 4 example FOIs identified to be heterogeneous (not homogeneous) by the homogeneity marker.
| Construction site | Multiple land uses |
| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
| The S2 imagery, signals, and markers suggest that the northeast part of the FOI has been turned into a construction site. | S2 imagery suggests that part of the FOI has consistently high NDVI values, while the other part shows evidence of mowing. Orthophoto imagery suggests that this FOI covers multiple land uses. |
| Arable land part on permanent meadow | Multiple crops grown on one field |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
| The northern half of the FOI seems to be arable land and the southern part is permanent meadow as declared. The northern part has bare-soil observations at the end of the season. | FOI is declared as arable land with grass-clover mixture. Like the case of the FOI to the left, this one also has bare-soil detected at the beginning and at the end of the season indicating that some other crop is being cultivated as well. |
#### Crop-group prediction consistent with grassland crop groups
FOIs that are found to be consistent with the claim by crop-group classification, similarity or distance markers do not get a green assignment yet. An additional requirement is that they are mowed as well. Since claims can and are wrong, and among FOIs that enter this scenario are also fields cultivating annual crops, where mowing is not expected, we need to split FOIs into two groups. The first group (follows the YES branch) consists of FOIs that are predicted to grow grass, clover, grass-clover mixtures, or are permanent meadows. The second one (following the NO branch) consists of FOIs that are predicted to grow some other annual crop on arable land.
#### (Pixel) Mowing detected
These two nodes are the most important nodes of this scenario. Grassland FOIs are required to be mowed at least once per year in the specified time interval. Example FOIs below have detected either FOI-level or pixel-level mowing.
| Partially mowed in 5 steps | Alfalfa field mowed 3 times from May to August |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  |  |
| An interesting mowing pattern. Grass is cut on this FOI over a period of two weeks. First evidence of mowing on a small part can be seen on June 9. The rest of the FOI is mowed in 4 steps. Each observation shows a slightly larger area that has been mowed until the FOI has been completely mowed by June 24. | Grassland FOIs on arable land are typically more intensively mowed than permanent meadows. This FOI claims to cultivate alfalfa. In total three mowing events were detected: in May, June, and August. |
| Partially mowed, with exception of the northern part | Entire area of the FOI has been mowed, in parts |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  |  |
| FOI-level mowing marker did not detect any mowing event. Pixel-level mowing marker results suggest that this FOI has been mowed almost completely. Everything except the northern part of the FOI has been mowed. Vegetation in the northern part of the FOI does not seem to develop. | Evidence of mowing in the northwest (largest) part of the FOI is seen on Sentinel-2 observation from July 19. Pixel mowing map confirms that the entire area of the FOI has been mowed during the entire season. |
#### Consistent with annual crop
Business rules for Basic Payment Scheme in Slovenia do not require that the claimed crop is being cultivated. What matters is that land is being farmed. This means that if the crop-group classification marker is confident that some other crop is cultivated on a FOI and not the crop being claimed, then such FOI still needs to get a Green assignment. FOIs within this scenario have a claim to cultivate grass, clover, or grass-clover mixtures on arable land. But this is sometimes not true, for example, corn is cultivated on the field. Such FOIs are diverted into the left-hand branch of the scenario's decision tree. In this branch the requirement of at least one detected mowing event does not make sense. Instead the presence of other evidence of farming activity needs to be tested. As in the case of annual crops on arable land scenario we use crop-group classification, similarity and distance markers as a proxy for detecting farming activity. An example below is declared as permanent meadow, which however cannot be confirmed by signals and markers. The area of the FOI was vegetated in the beginning of the year, which is consistent with the claim. In May, however, the FOI was ploughed and annual crop has been sown. Based on NDVI time series, results of crop-group classification marker and similarity marker it seems that corn has been sown.
#### Bare-soil detected
The aim of this condition is to assign Green to all FOIs that are being farmed, even if the claim is erroneous and any of the previous markers failed to provide evidence of farming activity. All FOIs reaching this point are assigned Green, if bare soil is detected within the specified time interval. The example below is similar to the one above. The main difference is that neither the crop-group classification nor the similarity marker provide high confidence about what is really growing on this FOI. However, regardless of what crop type is truly growing on this FOI, because the bare-soil marker makes conclusive bare-soil observations, there is sufficient evidence of farming activity to assign green.
#### FOIs without evidence of farming activity
FOIs that end up at the very end node of this decision tree are those for which marker results provide no strong evidence of farming activity. These are typically FOIs that are consistent with the claimed group, but no conclusive evidence of mowing or ploughing is seen in satellite-derived signals and markers. An example below was claimed as meadow. Crop-group classification, similarity and Euclidean distance markers suggest that this is really a meadow, however the mowing marker does not detect any events. NDVI time series and Sentinel-2 imagery also do not provide any evidence that this FOI has been mowed or ploughed.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/videos/)
# Videos
* [CAP Area Monitoring System - Lessons from Slovenia](https://learn.planet.com/cap-area-monitoring-system-webinar-recording.html)
* [Automated Agricultural Field Delineation Tool webinar](https://www.youtube.com/watch?v=czRCApJCYIo)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/)
# Visualizations
The Area Monitoring system has a collection of visualizations intended to visualize area monitoring results and facilitate the development of area monitoring [applications](https://docs.planet.com/data/area-monitoring/applications.md). Visualizations are available as [React components](#react-components) or through [visualization service](#visualization-service).
## React components
* [Signal Marker Visualization](https://docs.planet.com/data/area-monitoring/visualizations/signal-marker-visualization.md)
* [Marker Scores](https://docs.planet.com/data/area-monitoring/visualizations/marker-scores.md)
* [Markers Summary](https://docs.planet.com/data/area-monitoring/visualizations/markers-summary.md)
* [Timelapse](https://docs.planet.com/data/area-monitoring/visualizations/timelapse.md)
* [Observation](https://docs.planet.com/data/area-monitoring/visualizations/observation.md)
* [Communication](https://docs.planet.com/data/area-monitoring/visualizations/communication.md)
* [Photo Task Creator](https://docs.planet.com/data/area-monitoring/visualizations/photo-task-creator.md)
## Visualization service
* [Pixel Mowing](https://docs.planet.com/data/area-monitoring/visualizations/pixel-mowing.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/communication/)
# Communication
Communication *React* component displays a communication thread regarding selected agricultural parcel between the farmer/holding and the agency.
## User interactions
In communication thread, the user can see sent (*on the right*) and delivered (*on the left*) messages with their attachments and [add a new message](#adding-new-message). Users with appropriate user rights can also delete messages by clicking on 🗑️ button on the right side of the message.
Messages are ordered from the oldest to the newest. When the communication component is displayed, the display is set to the newest message.
### Adding new message
By clicking on `Add new message` button new window displays:
* `(1)` *text area input field* for the user to write a message
* `(2)` message attachments can be added by clicking the Add attachment button. User browses file to be uploaded from local drive.
* `(3)` already uploaded files can be removed from attachments by clicking the ❌ button
* `(4)` adding a new message can be canceled by clicking the Cancel button
* `(5)` new message is added by clicking the Send message button
### Limitations
Certain limitations apply to the communication component and sending a message.
| Limitation | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text length | The length of the written text in *text area input field* is limited to **2000 characters**. |
| File format | Attachment files **supported formats**: *bmp*, *csv*, *dcx*, *djvu*, *doc*, *docx*, *gif*, *htm*, *html*, *jpeg*, *jpg*, *jpm*, *mpp*, *odp*, *ods*, *odt*, *pcx*, *pdf*, *png*, *pnm*, *ppt*, *pptx*, *rtf*, *tif*, *tiff*, *txt*, *vsd*, *xls*, *xlsx*, *xml* |
| File size | Attachment file size is limited to **20 MB**. |
| Max attachments | Max number of attachments per message is **10**. |
| Empty message | It is not allowed to send an empty message. |
## Communication API
### Usage
```
keycloak.token}
holdingId="500611"
apId="6514199"
isMessageFormActive={isMessageFormActive}
onCancel={onCancel}
onDelete={onDelete}
onBeforePost={onBeforePost}
messagePosted={messagePosted}
messageDeleted={messageDeleted}
messageStatusUpdated={messageStatusUpdated}
language="en"
/>
```
### Component name
The component name `Communication` should be used when providing the [*props*](#props).
### Props
The *props* of the Communication *React* component are described in the table below.
| Name | Type | Default | Description |
| ----------------------- | -------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`\* | `string` | | Reference data differentiator (for example, `SI22`). For more details see [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `farmerServiceUrl`\* | `string` | | The base URL (for example, `https://am-pilot.sinergise.com/farmer/`) at which the endpoints for farmer service are. |
| `amServicesAuthToken`\* | `string` or callback `(() => string)` | | AM services authentication token. Either as a string or a function that returns a string. |
| `holdingId`\* | `string` | | Holding reference ID (for example, `500611`). |
| `apId`\* | `string` | | Agricultural parcel (type of FOI) reference ID (for example, `6514199`) |
| `language` | `string` | `en` | The selected language. Available options: `sl` - Slovenian, `en` - English, `de` - German |
| `dateFormat` | `string` | | Date format (for example, `d. m. yyyy`). If not present and `language` is present, it will take the default selected language format. If both are not present defaults to `enUS`. See the accepted format guide [here](https://date-fns.org/v2.29.2/docs/format). |
| `width` | `number` or `string` | `100%` | Width (for example, `300`) of the component in pixels. |
| `height` | `number` or `string` | `100%` | Height (for example, `300`) of the component in pixels. |
| `isMessageFormActive` | callback `((value: boolean) => void)` | | Callback that receives a *boolean* value depending on if the active form has any attachments or text. See the example in [isMessageFormActive](#ismessageformactive). |
| `onCancel` | callback `(() => Promise)` | | Callback that returns a *boolean* promise. Functions as an interceptor for any logic you want to do before a cancel form click is either confirmed or denied. See the example in [onCancel](#oncancel). |
| `onDelete` | callback `(() => Promise)` | | Callback that returns a *boolean* promise. Functions as an interceptor for any logic you want to do before a delete message click is either confirmed or denied. See the example in [onDelete](#ondelete). |
| `onBeforePost` | callback `(() => Promise)` | | Callback that returns a *boolean* promise. Functions as an interceptor for any logic you want to do before a post message click is either confirmed or denied and invalid attachments are removed. See the example in [onBeforePost](#onbeforepost). |
| `messagePosted` | callback `((value: MessagePosted) => void)` | | Callback that receives an object with posted message and updated messages array. See the example in [messagePosted](#messageposted). |
| `messageDeleted` | callback `((value: messageDeleted) => void)` | | Callback that receives an object with deleted message ID and updated messages array. See the example in [messageDeleted](#messagedeleted). |
| `messageStatusUpdated` | callback `((value: messageStatusUpdated) => void)` | | Callback that receives an object with updated message ID, updated message status, updated message status array, updated message, and updated messages array. See the example in [messageStatusUpdated](#messagestatusupdated). |
| `getMessagesInfo` | callback `((value: getMessagesInfo) => void)` | | Callback that receives an object with the number of total messages and the number of unread messages. See the example in [getMessagesInfo](#getmessagesinfo). |
*\* indicates mandatory props*
#### `isMessageFormActive`
**Example** for `isMessageFormActive`:
```
const isMessageFormActive = (value: boolean) => {
console.log('IS_MESSAGE_FORM_ACTIVE', value);
};
```
#### `onCancel`
**Example** for `onCancel`:
```
const deferredAction = () => {
let resolve: ((value: boolean | PromiseLike) => void) | null = null;
const promise = new Promise((res) => {
resolve = res;
});
return { promise, resolve };
};
const onCancel = async (): Promise => {
console.log('ON_CANCEL');
const proceed = await deferredAction();
console.log('ON_CANCEL_FINISHED', proceed);
return proceed;
};
```
#### `onDelete`
**Example** for `onDelete`:
```
const deferredAction = () => {
let resolve: ((value: boolean | PromiseLike) => void) | null = null;
const promise = new Promise((res) => {
resolve = res;
});
return { promise, resolve };
};
const onDelete = async (): Promise => {
console.log('ON_DELETE');
const proceed = await deferredAction();
console.log('ON_DELETE_FINISHED', proceed);
return proceed;
};
```
#### `onBeforePost`
**Example** for `onBeforePost`:
```
const deferredAction = () => {
let resolve: ((value: boolean | PromiseLike) => void) | null = null;
const promise = new Promise((res) => {
resolve = res;
});
return { promise, resolve };
};
const onBeforePost = async (): Promise => {
console.log('ON_BEFORE_POST');
const proceed = await deferredAction();
console.log('ON_BEFORE_POST_FINISHED', proceed);
return proceed;
};
```
#### `messagePosted`
**Example** for `messagePosted`:
```
{
message: Message;
messages: Message[];
}
const messagePosted = (value: MessagePosted) => {
console.log('MESSAGE_POSTED', value);
}
```
#### `messageDeleted`
**Example** for `messageDeleted`:
```
{
messageId: number;
messages: Message[];
}
const messageDeleted = (value: MessageDeleted) => {
console.log('MESSAGE_DELETED', value);
}
```
#### `messageStatusUpdated`
**Example** for `messageStatusUpdated`:
```
{
messageId: number;
status: Status;
statuses: Status[];
message: Message;
messages: Message[];
}
const messageStatusUpdated = (value: MessageStatusUpdated) => {
console.log('MESSAGE_STATUS_UPDATED', value);
}
```
#### `getMessagesInfo`
**Example** for `getMessagesInfo`:
```
{
totalMessages: number;
unreadMessages: number;
}
const getMessagesInfo = (value: MessagesInfo) => {
console.log('GET_MESSAGES_INFO', value);
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/marker-scores/)
# Marker Scores
Marker Scores *React* component displays a histogram of provided classification marker type scores (for example, *similarity*, *distance*, *crop group*, *land cover group*) for selected FOI.
## Marker scores API
### Usage
```
```
### Component name
The component name `MarkerScores` should be used when providing the [*props*](#props).
### Props
The *props* of the Marker Scores *React* component are described in the table below.
| Name | Type | Default | Description |
| ----------------------- | ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`\* | `string` | | Reference data differentiator (for example, `SI22`). For more details see the [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `amServicesAuthToken`\* | `string` or callback `(() => string)` | | AM services authentication token. Either as a string or a function that returns a string. |
| `markerServiceUrl`\* | `string` | | The (base) URL (for example, `https://am-pilot.sinergise.com/marker/`) at which the endpoints for marker service are. |
| `inferenceId`\* | `string` | | Inference ID (for example, `SI19.INFERENCE.65`) of classification marker type. |
| `markerIdmarkerId`\* | `string` | | Marker ID (for example, `SI19.MARKER.65-4088911`) for which we want to display scores. |
| `width` | `number` or `string` | `100%` | Width (for example, `300`) of the component in pixels. |
| `height` | `number` or `string` | `100%` | Height (for example, `300`) of the component in pixels. |
| `language` | `string` | `en` | The selected language. Available options: `sl` - Slovenian, `en` - English, `de` - German |
| `title` | `string` | | Title of the component displayed above chart. If not provided no title is shown. |
| `chartOptions` | `object` | | Definition of chart options. For more details see [chart options API in the marker scores API component](#chart-options-api-in-the-marker-scores-api-component). |
| `barColors` | `object` | | Definition of histogram bars colors. For more details see [the bar colors API in the marker scores API component](#bar-colors-api-in-the-marker-scores-api-component). |
*\* indicates mandatory props*
### Chart options API in the marker scores API component
The `chartOptions` prop is an object that defines chart options.
| Property | Type | Description |
| ------------------ | --------- | --------------------------------------------------- |
| `showDataLabels`\* | `boolean` | Indicates if labels should be shown inside the bar. |
*\* indicates mandatory properties*
**Example** `chartOptions`:
```
{
showDataLabels: true;
}
```
### Bar colors API in the marker scores API component
The `barColors` prop is an object that defines histogram bars colors.
| Property | Type | Description |
| ------------------ | -------- | ----------------------------------------------------------------------------------------- |
| `classification`\* | `object` | Color of bar representing a marker score with the same classification as provided marker. |
| `declaredAs`\* | `object` | Color of bar representing a marker score with the same `declaredAs` as a provided marker. |
| `default`\* | `object` | Color of bars representing the remainder of marker scores. |
\*\_ indicates mandatory properties\_
**Example** `barColors`:
```
{
classification: {
fill: '#bbbf3690',
},
declaredAs: {
fill: '#2e80b990',
},
default: {
fill: '#bbd5e890',
},
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/markers-summary/)
# Markers Summary
The Markers Summary *React* component is used to display a summary of markers (for example, crop group, land cover group, distance, similarity, homogeneity, bare soil, mowing, pixel mowing, mean NDVI) for selected Feature of Interest (FOI) and marker context, that can be filtered by Sentinel Hub (SH) collection type.
## Markers summary API
### Usage
```
```
### Component name
The component name `MarkersSummary` should be used when providing the *props*.
### Import
```
import { MarkersSummary } from '@area-monitoring/react-components';
import '@area-monitoring/react-components/style/all.css';
```
### Props
The *props* of the Markers Summary *React* component are described in the table below.
| Prop | Type | Default | Description |
| -------------------------------------------------------- | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amServicesAuthToken`\* | `string` or callback `(() => string)` | | The AM services authentication token. Either as a string or a function that returns a string. |
| `markerServiceUrl`\* | `string` | | The (base) URL at which the endpoints for markers are. |
| `scope`\* | `string` | | The reference data differentiator. For more details see the [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `foiId`\* | `string` | | The fully qualified ID of a FOI. |
| `markerContextId`\* | `string` | | The fully qualified ID of a marker context. |
| `shCollectionTypeId` | `string` | | The fully qualified ID of a SH collection type. If provided used to filter shown marker summaries by SH collection type. |
| `width` | `number` | `100%` | The width of the component in pixels.
Takes as input the number `100` or `"100"` number as a string. If the input is empty or wrong the component will default to `100%` css style and infer its size in pixels on its own. |
| `height` | `number` | `100%` | The height of the component in pixels.
Takes as input the number `100` or `"100"` number as a string. If the input is empty or wrong the component will default to `100%` css style and infer its size in pixels on its own. |
| `language` | `string` | `en` | The selected language at the time of rendering.
Options are: `sl` - Slovenian, `en` - English, `de` - German. |
| `markerTypeGroups`\* (if `markerTypeIds` is not defined) | `array` | | The array of marker type groups. The shown markers. |
| `markerTypeIds`\* (if `markerTypeGroups` is not defined) | `array` | | The array of marker type IDs. The shown markers. |
*\* indicates mandatory props*
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/observation/)
# Observation
The Observation *React* component displays the satellite image chip with drawn shapes on top. It also re-fetches the image chip when the image chip is resized to the specified height and width.
## Observation API
### Usage
```
console.log('CLICK!')}
language="sl"
/>
```
### Component name
The component name `Observation` should be used when providing the *props*.
### Props
The *props* of the Observation *React* component are described in the table below.
| Prop | Type | Default | Description |
| ----------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`\* | `string` | | An OGC WMS compatible base URL address (for example, `https://services.sentinel-hub.com/ogc/wms/`). The address needs to support `GetCapabilities` call. |
| `layerId`\* | `string` | | The layer unique identifier that must be available at the `baseUrl` specified. |
| `date`\* | `string` | | The date used for the background image in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DD`), in UTC. The date should be valid for the supplied layer ID. |
| `geometries`\* | `array` | | The shape type drawn on top of the satellite image, its position, outline color, and width.
For more details see [the geometries API in React observation API component](#geometries-api-in-react-observation-api-component). |
| `shAuthToken` | `string` | | The Sentinel Hub authentication token.
Either as a string or a function that returns a string. If using [sentinelhub-js](https://github.com/sentinel-hub/sentinelhub-js/), it can be obtained using `requestAuthToken` function. |
| `width` | `number` or `string` | | The width (for example, `300`) of the component (and thus images) in pixels. If no value is present, it defaults to 100% of the width of the parent container. |
| `height` | `number` or `string` | | The height (for example, `300`) of the component (and thus images) in pixels. If no value is present, it defaults to 100% of the height of the parent container. |
| `paddingXPercent` | `number` | `10` | The percent of padding in the horizontal direction. |
| `paddingYPercent` | `number` | `10` | The percent of padding in the vertical direction. |
| `upsampling` | `string` | | The upsampling interpolator for the image chip.
Options are: `BILINEAR`, `BICUBIC`, `NEAREST`. |
| `downsampling` | `string` | | The downsampling interpolator for the image chip.
Options are: `BILINEAR`, `BICUBIC`, `NEAREST`. |
| `onClick` | callback `(() => void)` | | When the image chip is clicked, the function given in the `onClick` prop is called. |
| `language` | `string` | `en` | The selected language at the time of rendering.
Options are: `sl` - Slovenian, `en` - English, `de` - German. |
| `cacheDuration` | `number` or `string` | `300` | The cache duration in seconds. |
*\* indicates mandatory props*
### Geometries API in React observation API component
The `geometries` prop contains an array of objects.
Every object in the array contains properties described in the table below.
| Property | Type | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geometry` | `object` | Geometry to be displayed in the observation component. See [Geometry](https://docs.planet.com/data/area-monitoring/common.md#geometry) for more details. |
| `style` | `object` | Style in which geometry is to be displayed in the observation component. See [Style](https://docs.planet.com/data/area-monitoring/common.md#style) for more details. |
**Example**:
```
geometries={[
{
geometry: {
type: 'MultiPolygon',
coordinates: [
[
[
[11.02, 45.01],
[11.02, 45.02],
[11.03, 45.02],
[11.03, 45.01],
[11.02, 45.01],
],
],
],
},
style: {
strokeColor: 'white',
lineWidth: 2,
},
},
]}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/photo-task-creator/)
# Photo Task Creator
Photo Task Creator *React* component displays a UI for defining of a new task for the farmer to collect photos of the agricultural parcel.
## User interactions
Photo Task Creator has several elements for the definition of the required capturing of geotagged photos:
* `(1)` Basic information of agricultural parcel for which photos are required
* `(2)` Basic information about the photo task:
* User selects task type from *drop-down list* and writes task description in the *text input area*
* `(3)` Additional parameters of photo task:
* The user defines parameters (for example, number of photos required) and marks the level of obligation from the *drop-down list*
* `(4)` Prescribed photo location(s)
* The user can add suggested photo-capturing location(s) and delete already created ones
* For each photo, user defines the prescribed location and direction by manually writing longitude and latitude in the *text box* or clicking on digital map `(5)`
* `(5)` Map display of agricultural parcel (and prescribed photo locations)
* By default digital orthophoto is displayed as a base layer
* `(6)` Cancel button to cancel photo task creation
* `(7)` Submit task button to submit photo task and send it to the farmer
## Photo task creator API
### Usage
```
```
### Component name
The component name `PhotoTaskCreator` should be used when providing the [*props*](#props).
### Props
The *props* of the Photo Task Creator *React* component are described in the table below.
| Name | Type | Default | Description |
| ----------------------- | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`\* | `string` | | Reference data differentiator (for example, `SI22`). For more details see the [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `baseUrl`\* | `string` | | The (base) URL (for example, `https://am-test.sinergise.com/photo`) at which the endpoints for photo service are. It can include the trailing slash or not. |
| `amServicesAuthToken`\* | `string` or callback `(() => string)` | | AM services authentication token. Either as a string or a function that returns a string. |
| `customerId`\* | `string` | | Customer ID (for example, `68746bcc-5cc3-11ec-8b8f-002b6781cd11`) for photo-service context. |
| `holdingId`\* | `string` | | Holding reference ID (for example, `500611`). |
| `agriParcelId`\* | `string` | | Agricultural parcel (type of FOI) reference ID (for example, `6514199`) |
| `onClose`\* | callback `() => void` | | Callback that is executed after close button click. |
*\* indicates mandatory props*
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/pixel-mowing/)
# Pixel Mowing
## Aggregated Pixel Mowing
The aggregated pixel mowing (REST) API is the visualization service endpoint that returns the imagery of a FOI (feature of interest) and the number of mowing events detected in each FOI pixel.
### REST API
#### Basic info
* visualization service **base URL**: `https://am-pilot.sinergise.com/visualization`
* pixel mowing **endpoint** `/markers/agg-pixel-mowing`
* **HTTP method**: `GET`
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `inferenceId`\* | `string` | Inference ID of pixel mowing marker. |
| `markerId`\* | `string` | Marker ID for which to display the imagery of the FOI and the number of mowing events detected in each FOI pixel. |
*\* indicates a mandatory parameter*
#### Response
Responses can include one of the following status codes, in addition to content data.
| Status Code | Content Type |
| --------------------------- | ------------------ |
| `200 OK` | `image/svg+xml` |
| `401 Unauthorized` | `application/json` |
| `403 Forbidden` | `application/json` |
| `404 Not Found` | `application/json` |
| `500 Internal Server Error` | `text/plain` |
#### Example
Below cURL command demonstrates the usage of the endpoint request.
```
curl --request GET \
--url https://am-pilot.sinergise.com/visualization/markers/agg-pixel-mowing?inferenceId=DEMO.INFERENCE.461&markerId=DEMO.MARKER.461-6184252001 \
--header 'Authorization: Bearer '
```
## Event Pixel Mowing
The event pixel mowing (REST) API is a visualization service endpoint that returns the imagery of the FOI and the FOI pixel for the requested mowing event.
### REST API
#### Basic info
* visualization service **base URL**: `https://am-pilot.sinergise.com/visualization`
* pixel mowing **endpoint** `/markers/event-pixel-mowing`
* **HTTP method**: `GET`
#### Parameters
| Parameter | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `inferenceId`\* | `string` | Inference ID of pixel mowing marker. |
| `markerId`\* | `string` | Marker ID for which to display the imagery of the FOI and the FOI pixel for the requested mowing event. |
| `eventIndex`\* | `string` | Mowing event index for which to display the imagery of the FOI and the FOI pixel. |
*\* indicates a mandatory parameter*
#### Response
For information about the response codes, see [Response](#response).
#### Example
Below cURL command demonstrates the usage of the endpoint request.
```
curl --request GET \
--url https://am-pilot.sinergise.com/visualization/markers/event-pixel-mowing?inferenceId=DEMO.INFERENCE.461&markerId=DEMO.MARKER.461-6184252001&eventIndex=0 \
--header 'Authorization: Bearer '
```
## Links
* [Mowing marker](https://docs.planet.com/data/area-monitoring/markers/mowing-marker.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/signal-marker-visualization/)
# Signal Marker Visualization
The Signal Marker Visualization *React* component is used to represent the graphs of all available and selected signals and markers for the selected FOI and the marker context in the selected period.
## User Interactions
If the user hovers a mouse over the graph, a tooltip displays details about the data points that are closer to the mouse position.
### Legend
The Legend is below the graph, showing which signals and markers are available.
#### Show on graph
Left clicking on a label will toggle on and off shown items on the graph. Indicated by a colored square if the item is shown on the graph. The selection will persist between instances.
#### Include in tooltip
Ctrl/cmd + Left clicking on a label will toggle on and off included items in the tooltip. If the item is included in the tooltip, it will be indicated by bold text. The selection will remain the same between instances.
### Settings
Settings are available by clicking on the cog icon in the bottom right.
#### Tooltip position
Here you can chose between several options of where the tooltip should be. The selection will persist between instances.
## Signal marker visualization API
### Usage
```
console.log('external onDateClick function:', date)}
selectedDateColor={'orange'}
/>
```
### Component name
The component name `SignalMarkerVisualization` should be used when providing the *props*.
### Props
The *props* of the Signal Marker Visualization *React* component are described in the table below.
| Prop | Type | Default | Description |
| --------------------- | ----------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `number` | | The width of the component in pixels. |
| `height` | `number` | | The height of the component in pixels. |
| `scope`\* | `string` | | Reference data differentiator (for example, `SI22`). For more details see the [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `timespan`\* | `object` | | The object represents a time interval. It has the `from` and `to` properties of type `string` which represent a date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (for example, `{ from: '2020-01-01', to: '2020-01-31' }`). |
| `amServicesAuthToken` | `string` | | The AM services authentication token. |
| `signalServiceUrl` | `string` | | The (base) URL at which the endpoints for signals are (for example, `https://am-test.sinergise.com/signal/`). It can include the trailing slash or not.
An error is displayed if it is not provided and the `signalTypes` prop contains elements with `signalTypeId` that **do not contain word `custom`**. |
| `signalTypes`\* | `array` | | The array of objects with properties needed to get the data for correct signal types and if they are displayed or not, and how.
For more details see [signal types API in the signal marker visualization API component](#signal-types-api-in-the-signal-marker-visualization-api-component). |
| `customSignalsData` | `object` | | For more details see [custom signals data API in the signal marker visualization API component](#custom-signals-data-api-in-the-signal-marker-visualization-api-component).
An error is displayed if it is not provided and the `signalTypes` prop contains elements with `signalTypeId` that **do contain word `custom`**. |
| `markerServiceUrl` | `string` | | The (base) URL at which the endpoints for markers are (for example, `https://am-test.sinergise.com/marker/`). It can include the trailing slash, but it is not required.
It must be provided if `markers` prop is provided otherwise, an error is displayed. |
| `markers` | `array` | | The array of objects with properties needed to get the correct markers and to know if they need to be displayed or not.
For more details see [markers API in the signal marker visualization API component](#markers-api-in-the-signal-marker-visualization-api-component). |
| `onDateSelect` | callback `((onDateSelectEvent: OnDateSelectEvent) => void)` | | Callback that receives an object with a `value` of the selected date in `ISOString` format and `isExternal` with a `boolean` value (`true` value meaning that the event was triggered from outside by changing `selectedDate` prop). |
| `selectedDate` | `string` | | The date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (for example, `YYYY-MM-DD`). |
| `selectedDateColor` | `string` | `#ff0000` | The color of the vertical line that denotes the selected date.
Possible formats: `hex`, `rgb()`, `rgba()`, HTML color name/keyword. |
| `language` | `string` | | The selected language at the time of rendering.
Options are: `sl` - Slovenian, `en` - English. |
| `dateFormat` | `string` | | If not present and `language` is present will take the default selected language format. If both are not present defaults to `enUS` (for example, `d. m. yyyy`). For more details, see the [accepted format guide](https://date-fns.org/v2.29.2/docs/format). |
*\* indicates mandatory props*
### Signal types API in the signal marker visualization API component
The `signalTypes` prop contains an array of objects with properties needed to get the data for correct signal types and if they are displayed or not, and how they are displayed.
It can contain elements for signal types from:
* signal service (provided by `signalServiceUrl` parameter)
* `customSignalsData` parameter
The properties of an object in the array are listed in the table below.
| Property | Type | Default | Description |
| ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signalTypeId`\* | `string` | | The fully qualified ID of a signal type. |
| `shown`\* | `string` | | Shows (the value is `true`) or hides (the value is `false`) the signal on component load. |
| `foiId`\* | `string` | | The fully qualified ID of a FOI (feature of interest; for example, `DEMO.FOI.7025947001`). |
| `validSignalTypeId` | `string` | | The fully qualified ID.
If provided it will be used instead of the default `validSignalTypeId` resolution from the signal code list. |
| `label` | `string` | | The alternative text for the label in the legend and tooltips. |
| `lineColor` | `string` | | The default color for the signal line.
Possible formats: `hex`, `rgb()`, `rgba()`, HTML color name/keyword. |
| `bandColor` | `string` | | The color of the mean+-stDev band around the signal line.
Possible formats: `hex`, `rgb()`, `rgba()`, HTML color name/keyword.
If not provided, the `lineColor` is used. |
| `bandOpacity` | `number` | `0.3` | The opacity of the mean+-stDev band around the signal line.
Possible value: number between `0` and `1`. |
| `validColor` | `string` | | The color for the signal line between valid dates.
Possible formats: `hex`, `rgb()`, `rgba()`, HTML color name/keyword. If not provided, the `lineColor` is used. |
*\* indicates mandatory properties*
When multiple signals of the same `signalTypeGroup` are provided, the first one from the array will be used to remember the selection between different instances/sessions.
### Custom signals data API in the signal marker visualization API component
The `customSignalsData` prop contains `signalTypes` and `signals` arrays.
The `signalTypes` array must be formatted similarly to the response from the signal service (provided by `signalServiceUrl` parameter).
Every element in the `signalTypes` array must contain the fields listed in the table below. Other fields in the element are ignored.
| Field | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`\* | `string` | Must contain word *"custom"*. |
| `code`\* | `string` | Custom signal type code. |
| `names` | `array` | It is needed if the `label` is not defined for the signal type in `signalTypes` prop. |
| `signalClass`\* | `string` | For correct visualization - valid/invalid or mean +/- stDev. |
| `validSignalTypeId` | `string` | It is needed for the visualization of valid/invalid signal data points.
If `validSignalTypeId` in `signalTypes` prop is defined for the signal type, this one is ignored. |
*\* indicates mandatory fields*
The `signals` array must be formatted similarly to the response from the signal service (provided by `signalServiceUrl` parameter).
Every element in the `signals` array must contain the fields listed in the table below. Other fields in the element are ignored.
| Field | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------------- |
| `id`\* | `string` | Must be the same as `id` in the element in the `signalTypes` array of `customSignalsData` prop. |
| `code`\* | `string` | Must be the same as `code` in the element in the `signalTypes` array of `customSignalsData` prop. |
| `values`\* | `array` | List of signal values. |
*\* indicates mandatory fields*
Every element in the `values` array must contain the fields listed in the table below. Other fields in the element are ignored.
| Field | Type | Description |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `time`\* | `string` | Date of the signal. |
| `mean`\* | `number` | Mean value of the signal. |
| `stDev`\* | `number` | It is needed for the signal types that are not used for the validation of data points. |
| `value` | `number` | It is needed for the signal types that are not used for the validation of data points.
If it is not provided, the `mean` will be used. |
*\* indicates mandatory fields*
### Markers API in the signal marker visualization API component
The `markers` prop contains an array of objects with properties needed to get the correct markers and to know if they need to be displayed or not.
The properties of an object in the array are listed in the table below.
| Property | Type | Default | Description |
| --------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `inferenceId`\* | `string` | | The fully qualified ID of an inference. Previously `markerTypeId` was used to get the marker data. |
| `shown`\* | `string` | | Shows (the value is `true`) or hides (the value is `false`) the marker on component load. |
| `foiId`\* | `string` | | The fully qualified ID of a FOI (feature of interest; for example, `DEMO.FOI.7025947001`). |
| `label` | `string` | | The alternative text for the label in the legend and tooltips. |
| `color` | `string` | | Possible formats: `hex`, `rgb()`, `rgba()`, HTML color name / keyword. |
| `opacity` | `number` | `0.2` | Possible value: number between `0` and `1`. |
*\* indicates mandatory properties*
If there is no object defined for a marker type, the component will choose a random color.
When multiple markers of the same markerTypeGroup are provided, the first one from the array will be used to remember the selection between different instances/sessions.
**Example**:
```
[
{
label: 'Inference 26 LABEL', // mandatory
inferenceId: 'SI19.INFERENCE.26', // mandatory
foiId: 'SI19.FOI.CROP_4106574', // mandatory
shown: 'true', // mandatory
color: '#396478', // optional
opacity: 0.4, // optional
},
];
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/area-monitoring/visualizations/timelapse/)
# Timelapse
Timelapse *React* component displays the timelapse of the selected FOI image chips for the selected layer. Timelapse can either play through image chips automatically with a defined speed or the user can navigate it image chip by image chip.
## User interactions
The timelapse component has several elements with which the user can control it:
* `(1)` drop-down list of layers to select a layer to be displayed in the timelapse component
* `(2)` check-box list of FOI geometry types (original, pixelated) to be displayed in timelapse component
* `(3)` button to generate and download timelapse GIF animation through all image chips
* `(4)` date of the currently displayed image chip in the timelapse component
* `(5)`/`(6)` button to manually navigate the timelapse component to the previous/next image chip
* `(7)` button to play/pause timelapse animation through all image chips
* `(8)` slider to manually navigate timelapse component through image chips
* `(9)` sequence number of current image chip and number of all image chips
* `(10)` button to control the speed of timelapse animation
## Timelapse API
### Usage
```
console.log('Date was selected:', date)}
geometries={[
{
geometry: geoJSONGeometry1,
style: {
strokeColor: 'white',
lineWidth: 1,
},
id: 'field',
label: 'Field',
},
{
geometry: geoJSONGeometry2,
style: {
strokeColor: 'red',
lineWidth: 1,
},
id: 'pixelated',
label: 'Pixelated field',
},
]}
autoplay={true}
paddingXPercent={10}
paddingYPercent={10}
width={450}
height={350}
enableGifExport={true}
language="sl"
dateFormat="DD/MM/YYYY"
upsampling="BICUBIC"
downsampling="BICUBIC"
cacheDuration={300}
/>
```
### Component name
The component name `Timelapse` should be used when providing the [*props*](#props).
### Props
The *props* of the Timelapse *React* component are described in the table below.
| Name | Type | Default | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`\* | `string` | | Contains an OGC WMS compatible base URL address (for example, `https://services.sentinel-hub.com/ogc/wms/`). The address needs to support `GetCapabilities` call. |
| `layers`\* | `array` | | Defines layers that can be displayed. For more details see [layers API in the timelapse API component](#layers-api-in-the-timelapse-api-component). |
| `geometries`\* | `array` | | Defines geometries to be displayed. For more details see [the geometries API in the timelapse API component](#geometries-api-in-the-timelapse-api-component). |
| `shAuthToken`\* | `string` or callback `(() => string)` | | Sentinel Hub authentication token. Either as a string or a function that returns a string. If using [sentinelhub-js](https://github.com/sentinel-hub/sentinelhub-js/), it can be obtained using `requestAuthToken` function. |
| `amServicesAuthToken`\* | `string` or callback `(() => string)` | | AM services authentication token. Either as a string or a function that returns a string. |
| `signalServiceUrl`\* | `string` | | The (base) AM signal service URL at which the endpoints for signals are (for example, `https://am-test.sinergise.com/signal/`). |
| `scope`\* | `string` | | Reference data differentiator (for example, `SI22`). For more details see the [scope](https://docs.planet.com/data/area-monitoring/common.md#scope). |
| `foiId`\* | `string` | | Fully qualified ID of a FOI (feature of interest; for example, `DEMO.FOI.7025947001`). |
| `defaultTimespan`\* | `object` | | The default date range. Only used until a change is saved to `localStorage`. Fields `from` and `to` are strings that represent a date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (for example, `{ from: '2020-01-01', to: '2020-01-31' }`). |
| `width` | `number` or `string` | `100%` | Width (for example, `300`) of the component (and thus images) in pixels. |
| `height` | `number` or `string` | `100%` | Height (for example, `300`) of the component (and thus images) in pixels. |
| `paddingXPercent` | `number` or `string` | `10` | Percent of padding in the horizontal direction (for example, `10`). |
| `paddingYPercent` | `number` or `string` | `10` | Percent of padding in the vertical direction (for example, `10`). |
| `dateFormat` | `string` | | Date format (for example, `d. m. yyyy`). If not present and `language` is present, it will take the default selected language format. If both are not present defaults to `enUS`. See the accepted format guide [here](https://date-fns.org/v2.29.2/docs/format). |
| `upsampling` | `string` | | Upsampling interpolator for image chip. Available options: `BILINEAR`, `BICUBIC`, `NEAREST` |
| `downsampling` | `string` | | Downsampling interpolator for image chip. Available options: `BILINEAR`, `BICUBIC`, `NEAREST` |
| `selectedDate` | `string` - compatible with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DD`) | | Contains the UTC date (for example, `2021-03-31`) that is used for the background image. If no image is available for this date then it will show the closest available image. |
| `onDateSelect` | callback `((value: string \| null) => void)` | | Callback that receives a string or null value. |
| `useValidSignal` | `boolean` (`true`/`false`) | | Indicator if all or only valid image chips should be displayed. For more details see [useValidSignal](#usevalidsignal). |
| `autoplay` | `boolean` (`true`/`false`) | | Initial timelapse animation playing state setting when the component mounts for the first time. On subsequent loads, this setting is loaded from the browser's local storage. |
| `lazyLoading` | `boolean` (`true`/`false`) | | If not present or if it is `false`, the timelapse will try to download all images. If it is `true`, timelapse will download only the first image, other images will be downloaded when the left/right arrow is pressed or when the animation is started by clicking the *play* button. |
| `enableGifExport` | `boolean` (`true`/`false`) | | If `true`, it shows the button for exporting the timelapse animation as GIF. If `false` or not set, the button is not shown. |
| `gifFilename` | `string` | | If provided, the exported GIF file will have that name (for example, `my_animation.gif`). If not provided, the exported GIF file will be named `timelapse.gif`. |
| `language` | `string` | `en` | The selected language. Available options: `sl` - Slovenian, `en` - English, `de` - German |
| `cacheDuration` | `number` or `string` | `300` | Cache duration in seconds (for example, `500`). |
*\* indicates mandatory props*
#### `useValidSignal`
If not present or if it is `false`, the Timelapse will show images for all available dates from Sentinel Hub for the selected layer and area (around geometries) within the selected time range.
If it is `true`, the Timelapse will filter out images for the dates that are marked as invalid in the response to AM signal service. The remaining dates will be the images for the dates that are not present in the response from AM signal service or are present and marked as valid.
### Layers API in the timelapse API component
The `layers` prop contains an array of objects. The sort order of this array is not important, objects are sorted by `layerId` (alphabetically).
Every object in the array contains properties described in the table below.
| Property | Type | Description |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layerId`\* | `string` | Layer ID. Must be available at the `baseUrl` specified (unknown `layerId` is silently ignored - not available for selection in the component drop-down list). |
| `validSignalTypeId` | `string` | Valid signal type ID in fully qualified identifier form. Must be available at the `signalServiceUrl` specified (unknown `validSignalTypeId` is silently ignored - invalid dates will not be filtered out). |
| `geometryIds` | `array` | Contain the same `id`s as in `geometries` prop, the order is not important:
- if not present, all geometries in `geometries` will be rendered
- if `undefined`, `null` or `[]` (empty array), no geometries will be rendered
- if containing correct geometry IDs, the geometries with those IDs will be rendered
- if containing one or more IDs that no geometry in `geometries` parameter has, an error will be shown |
*\* indicates mandatory properties*
note
Note that while there is no requirement that layer and valid signal type from the same object use the same collection, the dates for a valid signal type are only valid for a specific collection. In practice, the layer and valid signal type from the same object should be using the same collection.
**Example** `layers`:
```
layers={[
{
layerId: 'MY_LAYER_1',
validSignalTypeId: 'VALID_SIGNAL_1',
geometryIds: [ 'field', 'pixelated' ],
},
{ layerId: 'MY_LAYER_2',
validSignalTypeId: 'VALID_SIGNAL_2',
geometryIds: [ 'field' ],
},
]}
```
### Geometries API in the timelapse API component
The `geometries` prop contains an array of objects.
Every object in the array contains properties described in the table below.
| Property | Type | Description |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geometry`\* | `object` | Geometry to be displayed in the timelapse component. See [Geometry](https://docs.planet.com/data/area-monitoring/common.md#geometry) for more details. |
| `style`\* | `object` | Style in which geometry is to be displayed in the timelapse component. See [Style](https://docs.planet.com/data/area-monitoring/common.md#style) for more details. |
| `id`\* | `string` | Geometry ID. Allows the user to show/hide geometries. Note that the shown IDs are saved globally, so if another component is mounted with a different set of geometry `id`s, they will be hidden (until selected through settings). |
| `label`\* | `string` | Geometry label. |
*\* indicates mandatory properties*
**Example** `geometries`:
```
geometries={[
{
geometry: {
type: 'MultiPolygon',
coordinates: [
[
[
[11.02, 45.01],
[11.02, 45.02],
[11.03, 45.02],
[11.03, 45.01],
[11.02, 45.01],
],
],
],
},
style: {
strokeColor: 'white',
lineWidth: 2,
},
id: "field",
label: "Field",
},
...
]}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/)
# Planet Imagery
[](https://docs.planet.com/data/imagery/arps.md)
### [Analysis-Ready PlanetScope](https://docs.planet.com/data/imagery/arps.md)
[Information about Analysis-Ready PlanetScope](https://docs.planet.com/data/imagery/arps.md)
[](https://docs.planet.com/data/imagery/mosaics.md)
### [Mosaics](https://docs.planet.com/data/imagery/mosaics.md)
[Information about Mosaics](https://docs.planet.com/data/imagery/mosaics.md)
[](https://docs.planet.com/data/imagery/pelican.md)
### [Pelican](https://docs.planet.com/data/imagery/pelican.md)
[Information about the Pelican Constellation](https://docs.planet.com/data/imagery/pelican.md)
[](https://docs.planet.com/data/imagery/planetscope.md)
### [PlanetScope](https://docs.planet.com/data/imagery/planetscope.md)
[Information about the PlanetScope Constellation](https://docs.planet.com/data/imagery/planetscope.md)
[](https://docs.planet.com/data/imagery/rapideye.md)
### [RapidEye](https://docs.planet.com/data/imagery/rapideye.md)
[Information about the RapidEye Constellation](https://docs.planet.com/data/imagery/rapideye.md)
[](https://docs.planet.com/data/imagery/skysat.md)
### [SkySat](https://docs.planet.com/data/imagery/skysat.md)
[Information about the SkySat Constellation](https://docs.planet.com/data/imagery/skysat.md)
[](https://docs.planet.com/data/imagery/superres.md)
### [SuperRes](https://docs.planet.com/data/imagery/superres.md)
[Information about SuperRes imagery.](https://docs.planet.com/data/imagery/superres.md)
[](https://docs.planet.com/data/imagery/tanager.md)
### [Tanager](https://docs.planet.com/data/imagery/tanager.md)
[Information about the Tanager Constellation](https://docs.planet.com/data/imagery/tanager.md)
[](https://docs.planet.com/data/imagery/udm.md)
### [Usable Data Mask](https://docs.planet.com/data/imagery/udm.md)
[Information about UDM data](https://docs.planet.com/data/imagery/udm.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/arps/)
# Analysis-Ready PlanetScope
## About Analysis-Ready PlanetScope
This product includes derived imagery from [PlanetScope](https://docs.planet.com/data/imagery/planetscope.md) sensors.
Analysis-Ready PlanetScope combines data from the three available PlanetScope sensors (Dove Classic, Dove-R, and SuperDove) while enhancing temporal and spatial consistency with trusted, third-party data sources (Landsat, Sentinel-2, MODIS, VIIRS). This is accomplished with a proprietary algorithm that creates pre-processed, harmonized, and spatially consistent near-daily stacks of images that enable time-series analysis and machine learning applications. It delivers four surface reflectance bands: blue, green, red, and near-infrared.
The earliest Analysis-Ready PlanetScope imagery is available on January 01, 2017. The product is produced on demand when a subscription is initiated.
## Product Overview
Planet offers Analysis-Ready PlanetScope (ARPS) imagery as a 3 m orthorectified (corrected for terrain distortions) surface reflectance product (ARP-SR). The data is stored in 16-bit integer format (with a multiplication factor of 10,000) as cloud-optimized geotiffs compressed using LZW compression. During processing and harmonization, 4-band PS TOA Reflectance (PS-TOAR) (converted from the radiances) are transformed into surface reflectances, ensuring radiometric consistency with FORCE-processed Sentinel-2 and Landsat. As a result, the spectral bands and spectral response functions of ARPS data will be equivalent to the blue (B2), green (B3), red (B4), and narrow NIR (B8a) bands of Sentinel-2 (ESA 2024). The surface reflectance data represent Normalized BRDF Adjusted Reflectances (NBAR) as the Landsat 8/9 and Sentinel-2 data used for cross-calibration have been normalized to the nadir view. Enhanced geometric performance includes temporal positional accuracy of <4m RMSE PCTL90.
The surface reflectance product is accompanied by a Quality Assurance product (ARP-QA) in GeoTIFF format. The QA product is a 2-layer thematic raster using the same spatial grid as the corresponding Analysis-Ready PlanetScope spectral data. Layer 1, Cloud and shadow mask, contains information denoting usable data using seven classifications that allow users to remove pixels that are not useful after they download the image. Layer 2, Pixel provenance has integers that can be mapped to PlanetScope scene IDs using the information in the QA raster's metadata header.
Analysis-Ready PlanetScope products are projected in the UTM zone intersected by their extent using the WGS-84 horizontal datum.
### Available IDs
Analysis-Ready PlanetScope can be requested using the Subscriptions API. The following products can be requested with the associated ID. Please note that at this time, Analysis-Ready PlanetScope does not support MultiPolygon geometry. Subscriptions can only be created using Polygon geometry. For more details on how to subscribe to Analysis-Ready PlanetScope, please visit the [Subscriptions API](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types) documentation.
Loading resource data...
Loading...
## Available Bands and Data
This section explains the bands and data which can be set in the evalscript input object. Any string listed in the **Name** column can be an element of the `input.bands` array in your evalscript.
Analysis-Ready PlanetScope data is delivered with two assets: surface reflectance (SR) and quality assurance (QA).
| Name | Description | Resolution |
| ----------- | ------------------------------------------------ | ---------- |
| blue | Blue band | 3 m |
| green | Green band | 3 m |
| red | Red band | 3 m |
| nir | Near-infrared band | 3 m |
| cloud\_mask | Cloud and shadow mask | 3 m |
| scene\_mask | Pixel provenance (maps to PlanetScope scene IDs) | 3 m |
## Units
The data values for each band in your evalscript are provided in the units specified below.
Surface reflectance bands are stored as 16-bit integers with a multiplication factor of 10,000. To convert digital numbers (DN) to reflectance values, use the following formula:
```
reflectance = DN / 10000
```
For example, a DN value of 2500 corresponds to a reflectance of 0.25.
| Band | Physical Quantity (units) | Data Type | No Data Value | Typical Range |
| ------------------------------------- | ----------------------------- | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Optical bands (blue, green, red, nir) | Scaled reflectance (unitless) | int16 | 0 | 0 - 4000. Highly reflective pixels can have values up to 10000. |
| cloud\_mask | Cloud mask (unitless) | int16 | -999 | 1 - clear
2 - bright cloud
3 - cloud shadows
4 - haze
5 - adjacent clouds or cloud shadows
6 - additional haze or cloud elements
7 - contamination including snow |
| scene\_mask | Pixel provenance (unitless) | int16 | -999 | 0 - 1000 |
## Examples
For Processing API request examples, including true color, false color, NDVI calculations, and GeoTIFF exports, see [Processing API Examples - ARPS](https://docs.planet.com/develop/apis/processing/examples.md#analysis-ready-planetscope-examples).
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/arps/sandbox/)
# Analysis-Ready PlanetScope Sandbox Data
This Planet Sandbox Data collection for Analysis-Ready PlanetScope provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| ------------------ | ------------------------------------------------ | ----------------------------------------- | ----------------------- |
| PS\_ARD\_SR\_DAILY | Planet Sandbox Data - Analysis Ready PlanetScope | BYOC-3f605f75-86c4-411a-b4ae-01c896f0e54e | 2021-01-01 - 2023-12-31 |
## Planet Sandbox Data Areas
This collection includes 22 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 22 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Arizona, United States | 576 | 2022-01-01 – 2023-12-31 | 32.86, -111.86 |
| Alberta, Canada | 576 | 2022-01-01 – 2023-12-31 | 50.15, -111.78 |
| Iowa, United States | 2306 | 2021-01-02 – 2023-12-30 | 41.19, -93.81 |
| Cusco, Province of Chumbivilcas, Peru | 575 | 2021-01-04 – 2023-12-31 | -14.56, -71.75 |
| Pará, North Region, Brazil | 576 | 2021-01-01 – 2023-12-29 | -6.77, -52.38 |
| Goiás, Central-West Region, Brazil | 576 | 2022-01-02 – 2023-12-30 | -16.52, -48.83 |
| Autonomous Community of the Basque Country, Spain | 576 | 2022-01-01 – 2023-12-31 | 42.81, -2.51 |
| Nouvelle-Aquitaine, Metropolitan France, France | 2304 | 2021-01-01 – 2023-12-27 | 44.84, -0.52 |
| Flevoland, Netherlands | 576 | 2022-01-03 – 2023-12-01 | 52.50, 5.71 |
| Groningen, Netherlands | 1000 | 2022-01-03 – 2023-12-30 | 53.14, 6.24 |
| Emilia-Romagna, Italy | 576 | 2022-01-01 – 2023-12-25 | 44.97, 9.81 |
| Brandenburg, Germany | 576 | 2021-01-14 – 2023-12-30 | 52.30, 13.47 |
| Epirus and Western Macedonia, Greece | 576 | 2022-01-01 – 2023-12-30 | 40.65, 21.76 |
| Attica, Greece | 576 | 2022-01-01 – 2023-12-31 | 38.02, 23.92 |
| Al Qalyubiya, Egypt | 576 | 2021-01-01 – 2023-12-31 | 30.25, 31.17 |
| Kitui County, Kenya | 576 | 2022-01-01 – 2023-12-31 | -1.34, 37.85 |
| Al Jawf Region, Saudi Arabia | 576 | 2022-01-01 – 2023-12-27 | 30.05, 38.42 |
| Haryana, India | 576 | 2022-01-01 – 2023-12-26 | 27.86, 77.36 |
| Hưng Yên Province, Vietnam | 576 | 2022-01-02 – 2023-12-31 | 20.51, 106.30 |
| Guizhou, Tongren, China | 576 | 2022-01-11 – 2023-12-30 | 28.09, 109.21 |
| Western Australia, Australia | 576 | 2021-01-01 – 2023-12-31 | -31.92, 116.15 |
| New South Wales, Australia | 576 | 2022-01-02 – 2023-12-31 | -34.52, 146.13 |
[Download GeoJSON](https://docs.planet.com/data/imagery/arps/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=41.3\&lng=-93.9558\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-19T00%3A00%3A00.000Z\&toTime=2023-04-19T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
Des Moines, United States
2021-01-01 - 2023-12-31
576km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=41.3\&lng=-93.9558\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-19T00%3A00%3A00.000Z\&toTime=2023-04-19T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=44.73491\&lng=-0.67566\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-18T00%3A00%3A00.000Z\&toTime=2023-04-18T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
Bordeaux, France
22021-01-01 - 2023-12-31
576km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=44.73491\&lng=-0.67566\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-18T00%3A00%3A00.000Z\&toTime=2023-04-18T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=-31.9137\&lng=116.1481\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-29T00%3A00%3A00.000Z\&toTime=2023-04-29T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
Perth, Australia
2021-01-01 - 2023-12-31
576km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=-31.9137\&lng=116.1481\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F23b2442b-a5bb-42b5-87cd-916e28c34a5e\&datasetId=3f605f75-86c4-411a-b4ae-01c896f0e54e\&fromTime=2023-04-29T00%3A00%3A00.000Z\&toTime=2023-04-29T23%3A59%3A59.999Z\&layerId=0_TRUE-COLOR-CLOUDMASKED\&demSource3D=%22MAPZEN%22)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/arps/techspec/v1-0-0/)
# Technical Specification v1.0
note
This is the **v1.0 technical specification**, applicable to customers who received ARPS data produced with pipeline versions 1.0.0 and 1.0.1. The current specification is [Technical Specification](https://docs.planet.com/data/imagery/arps/techspec/v1-1-0.md) (v1.1.0).
**SURFACE REFLECTANCE**
v1.0.0, October 2024
## 1. Analysis-Ready Planetscope Overview
The PlanetScope (PS) constellation of 180+ CubeSats in low earth orbits represents a novel observational resource, which when combined with advances in conventional spaceborne sensing has resulted in a proliferation of satellite sensor data with unprecedented spatial, temporal, and spectral resolution. This constitutes a revolution in the ability to derive time-critical, location-specific insights about dynamic land surface processes. However, the potential for these systems to support decision making is often limited by sensor interoperability issues ([Figure 1](#kz1mqwbgovxc)), cross-calibration challenges, and atmospheric contamination. These obstacles can stand in the way of realizing the full potential of these rich datasets.
*Figure 1: Sources of interoperability issues. Left: The reflectance field of the same observation target can appear very different at the point of the satellite sensor due to differences in satellite viewing and sun illumination angles augmented by shadow effects and non-lambertian surface characteristics (For example, as described by the Bidirectional Reflectance Distribution Function; BRDF). Right: Differences in spectral bands and spectral response functions can result in poor sensor interoperability. This is particularly pronounced when comparing Dove-C (For example, first generation PlanetScope) with public sensor sources (For example, L8).*
Planet implemented and improved a rigorous methodology to enhance, harmonize, inter-calibrate, and fuse cross-sensor data streams. The CubeSat-Enabled Spatio-Temporal Enhancement Method (CESTEM) ([Houborg and McCabe 2018a](#8gfufoj8ok4f), [2018b](#xr6pcawhkolt)) leverages rigorously calibrated publicly accessible multispectral satellites (For example, Sentinel, Landsat, MODIS, VIIRS) to work in concert with the higher spatial and temporal resolution data provided by the Planet Dove CubeSats. The result is a next-generation, analysis-ready, harmonized Level-3 data product, which delivers a clean (For example, clouds and cloud shadows clearly labeled), temporally consistent, and radiometrically accurate 4-band surface reflectance (SR) data product.
Analysis-Ready PlanetScope (ARPS) combines distributed observations from the hundreds of individual sensors that make up the PlanetScope constellation (using three generations of hardware). These observations are radiometrically and geometrically harmonized with each other while ensuring radiometric consistency with a suite of widely used reference satellite platforms. The result is a highly temporally consistent stack of PlanetScope data. This next-generation Analysis Ready Data (ARD) product is suitable for analytic and data science purposes. Analysis-Ready PlanetScope involves significant processing and novel methodology in the attempt to create a unique surface reflectance product enhanced in resolution, quality, and interoperability ([Figure 2](#xu3wgds3r48h)), as the pathway to useability and meaningful remote sensing driven insights.
*Figure 2: Normalized Difference Vegetation Index (NDVI) time series over a crop field near Lincoln (NE) over the course of two years (July 2021 - July 2023). The ARPS processing translates original PlanetScope Top Of Atmosphere (TOA) reflectance inputs into Surface Reflectances (SR) consistent with Landsat 8/9 and Sentinel-2 clear-sky observations. Note the increased harmonization amongst ARPS observations and FORCE as compared to PlanetScope SR.*
The unique features of Analysis-Ready PlanetScope can be summarized as:
* **Advanced radiometric harmonization which leverages rigorously calibrated third-party sensors (MODIS/VIIRS, Landsat 8/9, and Sentinel-2) for full fleet interoperability**
* **Rigorous, temporally driven, cloud and cloud shadow detection**
* **Cleaned (For example, with cloud mask included) Surface Reflectance values delivered with a 48 hour latency**
* **CubeSats with near-nadir field of view result in minimal BRDF variation effects**
* **Designed to provide high radiometric accuracy and spatio-temporal consistency**
* **Geometric harmonization with sub-pixel co-registration/alignment of disparate image sources**
* **Includes pixel traceability information to identify source imagery for every data point**
## 2. Analysis-Ready Planetscope Inputs
[Table 1](#eayvkhwt1aol) lists the data sources currently used in Analysis-Ready PlanetScope (ARPS) production.
The Planet collection of 180+ CubeSats operates in sun synchronous orbits (altitude \~475 km) with a midmorning equatorial overpass time (9:30–11:30 a.m., local solar time) providing global near-nadir (\~4° field of view) imaging on a near-daily basis ([Roy et al., 2021](#nfg7qgvzajyq)). Three generations of "Doves" (collectively referred to as "PlanetScope" in this document) are used as input to ARPS products; the Dove-Classic constellation (2016-2022) is characterized by broad and partly overlapping spectral bands in the visible and near-infrared (NIR) spectrum ([Figure 1](#kz1mqwbgovxc)), whereas the Dove-R (2019-2022) and SuperDove (2020-) constellations are improved to be directly interoperable with the visible and narrow NIR bands of Sentinel-2. The nominal ortho scene size (at 475 km altitude) is also larger for Dove-R (\~25 km x 23 km) and SuperDove (\~32.5 km x 19.6 km) relative to Dove-Classic (\~25 km x 11.5 km). PlanetScope Top Of Atmosphere (TOA) Radiance inputs contribute the bulk of the observations used to make ARPS, and they are derived from 4-band Orthorectified Scene Products that have a resampled pixel size of 3 m (the ground sampling distance depends on the altitude and generation of each satellite and ranges from 3.7 to 4.2 m). While the SuperDove is an 8-band sensor (For example, it adds bands in the visible and red-edge domain compared to previous generations of Doves), currently only the blue, green, red, and NIR bands are used in ARPS production.
[]()
**Table 1: List of inputs currently used in Analysis-Ready PlanetScope production.**
| Product | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PS-TOA | Scene-based PlanetScope Top Of Atmosphere (TOA) Radiance (4-band, resampled to 3 m pixels) () |
| MCD43A4, MCD43A4N | Tile-based MODIS Surface Reflectance (SR) normalized to a nadir view direction and local solar noon (daily, 500 m) () |
| VNP43IA4, VNP43IA4N | Tile-based SR (VIIRS imagery bands) normalized to a nadir view direction and local solar noon (daily, 500 m) () |
| VNP43MA4, VNP43MA4N | Tile-based SR (VIIRS moderate bands) normalized to a nadir view direction and local solar noon (daily, 1000 m) () |
| FLS-SR | In-house implementation for tile-based generation of Nadir BRDF Adjusted Reflectances (NBAR) from Landsat 8/9 and Sentinel-2 data (4-band, 30 m). The Landsat 8/9 data have been spectrally adjusted to match Sentinel-2 spectral band passes. Based on the Framework for Operational Radiometric Correction for Environmental Monitoring (FORCE) () |
Planet uses a scalable implementation of the Framework for Operational Radiometric Correction for Environmental Monitoring (FORCE version 3.7.10; [Frantz 2019a](#q93ufohcogsk)) for generating a combined Landsat 8/9 (L8/9) and Sentinel-2 (S-2) surface reflectance product (FLS-SR) to be used as the "gold reference" during the radiometric calibration and normalization of ARPS products. FORCE includes state-of-the-art atmospheric correction, topography/terrain correction, cloud and cloud shadow detection, spatial co-registration, and view angle normalization ([Frantz 2019a](#q93ufohcogsk)). FORCE infers surface reflectance from L8/9 and S-2 imagery using an implementation of the 5S (Simulation of the Satellite Signal in the Solar Spectrum) code ([Tanre et al., 1990](#4890nor5vtfe)). The aerosol optical depth is estimated from the imagery using a dark object based approach whereas the water vapor content is either estimated on a pixel-specific basis (S-2) or derived from a global MODIS-based database (L8/9) ([Frantz et al., 2019b](#wwy60iiky9or)). Clouds and cloud shadows are detected using a modified version of Fmask ([Zhu and Woodcock, 2012](#9896bortvtge)) that exploits parallax effects to improve detections for S-2 images ([Frantz et al., 2018](#6romhalczsxf)). However the FORCE derived cloud masks may be further refined as part of ARPS processing ([Section 4.3](#43-cloud-and-cloud-shadow-masking)). A global assessment of the FORCE atmospheric correction approach has been conducted as part of the Atmospheric Correction Inter-comparison Exercises (ACIX, ACIX-II) ([Doxani et al., 2018](#ivg7i1vy0qw2) & [2023](#trot904uc2nr)).
Our FORCE implementation maps the L8/9 and S-2 data onto a common grid (For example, the UTM-based Military Grid Reference System) to produce 30 m resolution L8/9 and S-2 data with a 2 - 3 day frequency. A spectral bandpass adjustment ([Claverie et al. 2018](#dim35cgaa27y)) is applied to L8/9 to align with S-2 radiometry. Only the blue (center wl: 0.490 µm, bandwidth: 0.065 µm), green (center wl: 0.560 µm, bandwidth: 0.035 µm), red (center wl: 0.665 µm, bandwidth: 0.030 µm), and narrow NIR (center wl: 0.865 µm, bandwidth: 0.021 µm) bands (S-2 radiometry) are currently used for ARPS production. The reported bandwidths are the values measured at Full Width Half Maximum (FWHM).
MODIS or VIIRS surface reflectance (SR) data normalized to nadir view and local solar noon is a required input to the ARPS reference sampling and calibration process ([Section 4.4](#44-reference-sampling-and-radiometric-harmonization)). ARPS uses the version 6.1 combined (For example, Terra and Aqua) MCD43A4 product that provides daily 500 m SR in 7 bands corrected for reflectance anisotropy (MODIS has a \~110° field of view) using a semiempirical bidirectional reflectance distribution function (BRDF) ([Schaaf et al. 2002](#6j563z3v2wig)). The BRDF utilizes the best observations from both Terra and Aqua sensors collected over a 16-day period centered on the day of interest where observations at the day of interest are emphasized in the daily retrieval. Only the blue (0.459 - 0.479 µm), green (0.545 - 0.565 µm), red (0.62 - 0.67 µm), and NIR (0.841 - 0.876 µm) bands are ingested for ARPS processing. The near real-time product version (MCD43A4N) is used when the standard product is not available (For example, as dictated by a 9 days latency). The VIIRS products (VNP43IA4/VNP43IA4N, VNP43MA4/VNP43MA4N) have been designed to ensure continuity of MCD43 and are used as a backup should MCD43A4/MCD43A4N become unavailable. The VIIRS-based processing ingests the red (0.60 - 0.68 µm) and NIR (0.85 - 0.88 µm) Imagery bands (500 m) in addition to the blue (0.478 - 0.488 µm) and green (0.545 - 0.565 µm) Moderate bands (1000 m). Since the two latter bands are provided at a coarser spatial resolution (1000 m), the finer resolution (500 m) red band is used to super-resolve the 1000 m band data for consistency.
## 3. Analysis-Ready Planetscope Products
The Analysis-Ready PlanetScope product line (ARPS) is outlined in [Table 2](#zercfubc5ciy). The ARPS products are provided at a near-daily cadence and orthorectified onto a fixed grid (see [Section 3.3](#33-delivery-projection-and-gridding)) with a 3 m pixel size. The products can be produced starting from January 1, 2017 and up till present, deliverable with a 48 hour latency (For example, data requested for Monday will typically be delivered Wednesday).
[]()
**Table 2: Overview descriptions of the Analysis-Ready PlanetScope (ARPS) products.**
| Product key | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| ARPS-SR | ARPS Surface Reflectance (SR) product. PS TOA Reflectance radiometrically harmonized to 4-band FLS-SR using the CESTEM methodology. |
| ARPS-QA | ARPS Quality Assurance (QA) product |
### 3.1. Surface Reflectance Product (ARPS-SR)
The Analysis-Ready PlanetScope Surface Reflectance product (ARPS-SR) records gridded (3 m), radiometrically and geometrically corrected orthorectified PlanetScope data in four spectral bands (blue, green, red, NIR) at a near-daily interval. The data is stored in 16-bit integer format (with a multiplication factor of 10,000) as cloud optimized geotiffs compressed using LZW compression. During ARPS processing and harmonization, 4-band PS TOA Reflectance (PS-TOAR) (converted from the radiances) are transformed into surface reflectances ensuring radiometric consistency with Sentinel-2. As a result the spectral bands and spectral response functions of ARPS data ([Table 3](#o023kp6ilo0e)) will be equivalent to the blue (B2), green (B3), red (B4), and narrow NIR (B8a) bands of Sentinel-2 ([ESA 2024](#c5vrv0vt2fwb)).
The ARPS-SR data represents Normalized BRDF Adjusted Reflectances (NBAR) as the Landsat 8/9 and Sentinel-2 data used for cross-calibration have been normalized to nadir view ([Roy et al. 2016](#hygf64l76qgv), [2017](#37ck249ixdf9)). As the ARPS cross-calibration adopts a multi-temporal reference sampling approach (see [Section 4.4](#44-reference-sampling-and-radiometric-harmonization)), the significant uncertainties related to the L8/L9/S-2-based BRDF normalization ([Roy et al. 2017](#37ck249ixdf9)) are likely to cancel out. In addition, in contrast to L8/9 (\~15° field of view) and particularly S-2 (\~21° field of view), the PlanetScope sensors are nadir viewing natively (\~4° field of view), which will act to further reduce view angle BRDF effects.
[]()
**Table 3: ARPS-SR data format specifications providing the band-specific center wavelengths and bandwidths (bw). The bandwidths are the values measured at FWHM.**
| Layer | Description | Date Type | Valid range | Scale factor |
| ------ | --------------------------------------------- | --------------------- | ----------- | ------------ |
| Band 1 | Blue band (0.490 µm, bw: 0.065 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 2 | Green band (0.560 µm, bw: 0.035 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 3 | Red band (0.665 µm, bw: 0.030 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 4 | NIR band (0.865 µm, bw: 0.021 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
### 3.2. Quality Assurance Product (ARPS-QA)
The Analysis-Ready PlanetScope Quality Assurance product (ARPS-QA) is a 2 layer thematic raster using the same spatial grid as the corresponding ARPS-SR product. It contains information denoting cloud and cloud shadow detection (layer 1) and pixel traceability/provenance (layer 2) ([Table 4](#8leouj2apj)).
[]()
**Table 4: ARPS-QA data format specifications. Note that additional metadata have been embedded in the tiff file, as described in the table and listed separately in [Table 5](#lpfw7cjfqo8i)**
| Layer | Description | Date Type | Valid range | Scale factor | Offset |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------- | ------------ | ------ |
| Layer 1 | Cloud and cloud shadow mask 1 = Clear 2 = Bright Clouds 3 = Cloud shadows 4 = Haze 5 = Adjacent clouds/clouds shadows 6 = Additional cloud/shadow/haze elements based on a cross-scene correlation detection approach 7 = Other contamination, including snow -999 = Scene data not available | 16-bit signed integer | 1 - 7, and -999 | 1 | 0 |
| Layer 2 | Pixel traceability/provenance mask (*see embedded metadata for scene IDs*) -999 = Scene data not available | 16-bit signed integer | 1 - 599, and -999 | 1 | 0 |
[Figure 3](#dcrzarok9z9m) depicts the cloud and cloud shadow mask from QA layer 1.
*Figure 3: QA layer 1 (cloud and cloud shadow mask) and input PS-TOAR product.*
A pixel traceability/provenance mask is also provided in QA layer 2 ([Figure 4](#6aqvlipijlmp)). This raster layer identifies the footprints of the PlanetScope scenes used to produce any given tile image (cloudy or clear). Each domain is associated with a unique integer value that is linked to a scene identifier (For example, Itemtype/sceneID) embedded as metadata in the QA geotiff. The scene identifier (For example, PSScene/20190701\*172222\_104e) provides the information needed to locate and access the source data through Planet's API. The embedded metadata may be displayed using GDAL (For example, `gdalinfo name_of_file.tif`). Note that the scene identifier is formatted as `**\_`. This provides information on the time of acquisition for each pixel in the image.
*Figure 4: QA layer 2 (pixel traceability mask) for the tile in Figure 3 (8000 x 8000 pixels) on July 1, 2019. In this case, a total of 10 PS ortho scenes from three separate strips were used to construct the tile image. The associated scene identifiers were extracted from the ARPS-QA embedded metadata. The visible seam lines in the PS-TOAR product result from merging Dove-R (reddish strip) and Dove-C (greenish strip) scene data with quite different spectral bands and Relative Spectral Response (RSR). Note that these transitions are not visible in the final ARPS-SR output.*
The QA product includes several pieces of non-raster metadata embedded in the tiff header. These are described in [Table 5](#lpfw7cjfqo8i).
[]()
**Table 5: List of metadata embedded in the header of PF-QA tiff files**
| Name | Description | Example |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CREATED | Timestamp of the product creation, corresponding to the time at which contributing satellite observations were gathered. | 2024-09-20T17:19:27Z |
| PERCENTAGE\_CLEAR | Fraction of pixels in the raster marked as class 1, "clear", in the QA layer 1 cloud mask | 86.68 |
| PERCENTAGE\_STANDARD\_QUALITY | Fraction of observed pixels in the tile which came from "standard" (as opposed to "test" quality PlanetScope images, see [Roy et al., 2021](#nfg7qgvzajyq)) | 100 |
| PIPELINE\_VERSION | Version identifier for the image processing pipeline used to create that day's data | 1.0.0 |
| RUN\_TYPE | Designates whether the data were produced in "backfill" or "forwardfill" mode. (See [Section 4.6](#46-backfill-versus-forward-fill-operation)) | backfill |
| SCENE\_IDS\[LAYER\_2\_VALUE] | Newline-separated scene IDs corresponding to integer references numbers in QA layer 2. See the layer 2 description above for more information. | PSScene/20210708\_131909\_101b\[9] PSScene/20210708\_131910\_101b\[10] PSScene/20210708\_131911\_101b\[11] PSScene/20210708\_131912\_101b\[12] PSScene/20210708\_134254\_06\_2406\[218] None\[-999] |
| SCENE\_SOLAR\_AZIMUTH\[LAYER\_2\_VALUE] | The solar azimuth in degrees for each PlanetScope scene in the layer 2 scene provenance raster | 40.30\[9] 40.20\[10] 40.20\[11] 40.20\[12] 35.00\[218] None\[-999] |
| SCENE\_SOLAR\_ELEVATION\[LAYER\_2\_VALUE] | The solar elevation in degrees for each PlanetScope scene in the layer 2 scene provenance raster | 38.60\[9] 38.50\[10] 38.50\[11] 38.40\[12] 41.90\[218] None\[-999] |
### 3.3. Delivery, Projection, and Gridding
Analysis-Ready PlanetScope products are delivered through the [Planet Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md), clipped to a provided Area of Interest (AOI). Each Subscription will receive 2 files (ARPS-SR and ARPS-QA) for each day in which at least some PlanetScope imagery intersects the requested AOI. If no PlanetScope surface reflectance data are available for a given day over the requested AOI, no files will be provided for that day. The AOI-clipped data have a 3 m pixel size and are projected in the UTM zone intersected by their extent using the WGS-84 horizontal datum.
## 4. Analysis-Ready Planetscope Methodology
*Figure 5: A generalized overview of Analysis-Ready PlanetScope processing modules for any given ARPS tile and TOI. The diagram highlights the key intermediate and final product artifacts, the associated pixel resolution (3 or 30 m) and processing features (For example, cloud masking, radiometric and geometric harmonization, time-series processing).*
The overall methodological elements of Analysis-Ready PlanetScope surface reflectance processing are diagrammed in [Figure 5](#bu6ydmlsd1u3). ARPS products are based on an implementation of the CubeSat-Enabled Spatio-Temporal Enhancement Method (CESTEM), which has been described in detail in [Houborg and McCabe 2018a](#8gfufoj8ok4f)/[2018b](#xr6pcawhkolt)). ARPS processing includes significant refinements and additional functionality related to geometric harmonization, topographic correction, and cloud masking. Key elements of the approach and processing specifics are outlined below.
While ARPS data are delivered as clipped AOIs, they are processed in units of tiles (as described in [Section 3.3](#33-delivery-projection-and-gridding)).
### 4.1. Tile (Quadrant)-Level Stacking
*Figure 6: Visualization of an ARPS tile with contributing PlanetScope scenes. ARPS processing is done on slightly overlapping quadrants (12.18 x 12.18 km) that are merged and clipped to produce a full tile (24 x 24 km).*
After identifying the source imagery (PS-TOA, FLS-SR, PSMOD) that intersect with a given ARPS tile over a specified Time Of Interest (TOI) (step 1, [Figure 5](#bu6ydmlsd1u3)), the respective input streams are stacked and re-gridded to the ARPS tiling system ([Section 3.3](#33-delivery-projection-and-gridding), [Figure 6](#vt0iehfmo0i4)) with either a 3 m or 30 m pixel resolution (step 2/3/4, [Figure 5](#bu6ydmlsd1u3)).
In the case of the scene-based PlanetScope TOA reflectance (PS-TOAR) data, several scenes from multiple sensors may be overlapping with parts of the tile domain ([Figure 4](#6aqvlipijlmp), [6](#vt0iehfmo0i4)). In order to retain the best data possible for the tile domain, priority is determined as a function of image quality category (prioritizing "standard" over "test" quality) (for more details on the image quality categorization see: [Roy et al., 2021](#nfg7qgvzajyq)), initial cloud percentage (prioritizing scenes with the lowest cloud percentages over land), sun elevation (prioritizing scenes with the highest sun elevation), and scene overlap with the tile domain. The scene to tile conversion will also prioritize merging of scenes acquired from a single satellite in a single pass (For example, strips) to reduce seam lines and spatial discontinuities introduced by cross-sensor inconsistencies. A phase correlation technique ([Section 4.5](#45-geometric-harmonization)) is used to help ensure that the PlanetScope scenes are geometrically aligned/co-registered (with sub-pixel precision) before compositing the tile. In addition, the re-aligned PS-TOAR scenes are brightness harmonized across the tile domain to facilitate a seamless surface reflectance calibration ([Section 4.4](#44-reference-sampling-and-radiometric-harmonization)). The brightness harmonization utilizes the clear-sky overlap between scenes to derive band-specific regression coefficients that are used to normalize the reflectance magnitudes across the scenes.
A 30 m resolution stack of MODIS/VIIRS Surface Reflectance-calibrated PlanetScope imagery (PSMOD) is also produced (step 2/4, [Figure 5](#bu6ydmlsd1u3)). The MODIS/VIIRS calibration is performed at the PlanetScope scene level using day-coincident MCD43/VNP43 NBAR products ([Table 1](#eayvkhwt1aol)) as the radiometric reference, translating PS-TOAR into MODIS/VIIRS-consistent SR data ([Houborg and McCabe 2018a](#8gfufoj8ok4f), [2018b](#xr6pcawhkolt)) (step 2, [Figure 5](#bu6ydmlsd1u3)). The scenes are prioritized as described above for PS-TOAR when producing the tile. This also involves co-registration of the 30 m PSMOD scenes prior to merging and tile composition.
The FORCE-based Surface Reflectance tiles (FLS-SR) are mapped onto the ARPS tiling grid in a similar way.
Analysis-Ready PlanetScope processing is done on slightly overlapping (For example, a buffer of 90 m) quadrants with a 12.18 by 12.18 km extent ([Figure 6](#vt0iehfmo0i4)). The tile products are generated by merging data from 4 quadrants, utilizing a gradual weighting and harmonization approach across quadrant overlap zones to avoid visible boundaries (seam lines) in the final outputs. It is possible, though uncommon, for neighboring quadrants to have selected different PlanetScope scenes, and for the merging to contaminate clear-sky pixels with clouds from the neighbor quadrant's overlap region. For this reason, the merging process also considers the cloud mask, and will mark pixels in the overlap region as cloudy if clouds were detected in either of the contributing quadrants.
### 4.2. Topographic Correction
*Figure 7: Visualization of the impact of the topographic correction on PlanetScope imagery acquired over a mountainous region in Austria on 2022-07-19. The impacts are significant over the sloping terrain with reflectance corrections ranging from approximately ±0.05 (red) and ±0.20 (NIR) reflectance units.*
Topography (irregular shape of the terrain) will affect the surface reflectance as a function of sun illumination conditions (sun elevation and sun azimuth), terrain shape (slope and aspect), and surface and atmospheric characteristics. Topography can significantly alter the reflectance signal and obfuscate the interpretation of surface characteristics in space and time. Topographic corrections attempt to remove the effect of topography on reflectance so that identical surface phenomena (For example, vegetation type) produce comparable reflectance signals irrespective of terrain characteristics.
A topographic correction is applied to the PlanetScope-based product artifacts ([Figure 7](#e9hb9udfhcvd)) produced by the ARPS pipeline. The FORCE surface reflectance data have also been corrected for the effects of topography on reflectance ([Frantz 2019a](#q93ufohcogsk)). The topographic correction adopted by ARPS shares similarities with the approach adopted in FORCE and is based on modeling illumination conditions using a Digital Elevation Model (GLO-30, ) to compute slope and aspect information (using the GDAL "gdaldem" functionality) along with sun elevation and sun azimuth information from the PS scenes. For simplicity, Lambertian (For example, no directional dependence on reflected light) surface conditions are assumed. The implementation is based on the Sun-Canopy-Sensor with C-correction approach described in [Soenen et al. 2005](#jqhq9xbqv5m4). The semi-empirical C-correction component is included to avoid over-corrections by accounting for the effects of diffuse radiation ([Teillet et al. 1982](#kcjkhcz64qas)). The topographic correction is applied to slopes of greater than 10 degrees in both the PSMOD and PS-TOAR stacked product artifacts produced in steps 3 and 4 ([Figure 5](#bu6ydmlsd1u3)). Applying the topographic correction to PS data is shown to significantly improve the agreement with day-coincident FORCE over AOIs with complex terrain and improves the overall quality of the ARPS data in regions with significant topography.
### 4.3. Cloud and Cloud Shadow Masking
Analysis-Ready PlanetScope cloud and cloud shadow detection (step 5, [Figure 5](#bu6ydmlsd1u3)) is performed at 30 m resolution using a temporally-driven approach that takes advantage of PlanetScope and FORCE (L8/9, S-2) surface reflectance information in a synergistic way. The approach starts from the original scene-based cloud and cloud shadow masks associated with both the PlanetScope and FORCE data. For PlanetScope, the initial cloud and cloud shadow mask is produced during the MODIS/VIIRS-based calibration stage (step 2, [Figure 5](#bu6ydmlsd1u3)) predominantly informed by UDM 2.0 (before 2023-11-23) or 2.1 (after 2023-11-23) detections, when available. A cloud verification approach is implemented at this step in an attempt to reduce commission/omissions errors.
*Figure 8: Example of ARPS cloud (white) and cloud shadow (black) detections over a region in Bolivia. Yellow represents the applied buffer around the detections.*
The temporally-driven detection approach can accommodate PS and FORCE data acquired at different times on the same day. The multi-source input data are first geometrically harmonized (see [Section 4.5](#45-geometric-harmonization)) to improve detection results and reduce commission issues resulting from pixels not being properly aligned. The detection approach utilizes clear-sky observations (For example, as identified by the initial cloud masks during the first iteration) over a flexible temporal window (up to ±1 year) for any given 30 m pixel to help flag spectral outliers potentially resulting from cloud, cloud shadow, or haze contamination. The deep temporal stack of clear-sky observations is used to create a clear-sky background image for each acquisition date over the defined TOI. The clear-sky background image generation utilizes clear-sky information acquired from multiple dates in the past and future (if available) relative to the prediction date, and adopts daily class-specific spectral trajectories (derived on the basis of the clear-sky imagery stack) to change adjust the past/future acquisition data to be more representative of surface conditions on the prediction date. After outlier screening, the temporally interpolated clear-sky observations are compared against the prediction date imagery to flag pixel domains (if any) exhibiting spectrally anomalous behavior (For example, dips or spikes). A carefully weighted average of the multi-temporal clear-sky inputs (this will include the prediction date data if not identified as anomalous) are then used to create the clear-sky background image. Next, the clear-sky background image is used in combination with the actual image acquired on the prediction date to identify spectrally distinct classes using an unsupervised k-means clustering approach. A suite of spectral difference metrics, such as the difference in red and NIR reflectance between the background and actual imagery, combined with a set of carefully defined spectral thresholds and a number of other constraints are then used to classify each cluster as clear, cloud, cloud shadow, or haze. Additional cross-correlation tests between the background and actual imagery serve to further resolve and label any cloud, cloud shadow, and haze contaminations. Furthermore, a series of automated techniques are implemented to verify these classifications and avoid (to the extent possible) masking out actual change. This includes the integration of hillshade information to help reduce commission issues in landscapes with significant terrain shadowing.
The cloud detected areas are expanded using a buffer zone (For example, adjacent cloud domain, layer 1 in [Table 4](#8leouj2apj)) (see also [Figure 8](#gwrkkacfyz3d)) to make it more likely that most of the contaminated pixels are identified in the final outputs. The scheme will refine and update the scene-based cloud masks (30 m) associated with both the PS (PSMOD-H) and FORCE (FLS-SR-H) data (step 5, [Figure 5](#bu6ydmlsd1u3)).
After the completion of the cloud masking step, a cloud verification step is invoked to further reduce commission errors. This step will only serve to unmask presumably false cloud/cloud shadow detections based on comparisons against updated clear-sky spectral trajectory signatures along with other verification metrics.
### 4.4. Reference Sampling and Radiometric Harmonization
As its core, the Cubesat-Enabled Spatio-Temporal Enhancement Method (CESTEM) serves as a flexible mechanism to radiometrically harmonize multi-sensor spectral data into a consistent radiometric surface reflectance standard (For example, the "gold standard"). The FORCE-based surface reflectance product (30 m) ([Table 1](#eayvkhwt1aol); FLS-SR) is currently adopted as the gold standard. CESTEM is characterized by a number of unique features:
* Does not require day co-incident acquisitions (PS versus L8/L9/S-2) for cross-calibration/harmonization
* Implements a secondary MODIS/VIIRS-based harmonization to correct for surface reflectance changes occurring over given PS and L8/L9/S-2 acquisition time spans
* Reduces uncertainties associated with both PS and L8/L9/S-2 data via temporally-driven anomaly detection
* Can harmonize data from sensors with contrasting spectral bands and Relative Spectral Responses
* Is largely insensitive to noise (For example, calibration uncertainties) in the input data (For example, PS-TOA)
* Does not require PS inputs to be atmospherically corrected and is agnostic to PS input type (For example, should work equally well with either DNs, TOA radiances, or TOA reflectances)
* The calibration model is locally constrained (For example, specific to each PS quadrant-level image domain) and therefore much less prone to overfitting and portability issues (For example, "hallucinations") relative to more generic AI driven model implementations
*Figure 9: Diagram of the CESTEM radiometric harmonization framework, translating image stacks of PlanetScope TOA radiance (PSTOA) into FORCE-consistent (Landsat 8/9/Sentinel-2) Surface Reflectance (PSFLS).*
The CESTEM-based harmonization (step 6 [Figure 5](#bu6ydmlsd1u3), [Figure 9](#i1o5qvu52bnb)) is applied to all PlanetScope images acquired over a defined Time Of Interest (TOI) drawing spectral reference data (For example, blue, green, red, and NIR) from a pool of FORCE L8/L9/S-2 SR (FLS-SR) images acquired over a predefined "calibration window" (typically one year centered around the TOI). In order to reliably use past or "future" FLS-SR images for calibration purposes they must be associated with a day-coincident PS acquisition. Critical to this process is the use of MODIS/VIIRS-consistent (For example, MCD43/VNP43) PlanetScope data (PSMOD) to quantify relative surface reflectance changes over given PS - FLS acquisition time spans ([Figure 9](#i1o5qvu52bnb)). It follows that data from multiple FLS acquisitions will be sampled to generate a given PS coincident calibration reference image (FLSREF), using weights derived as a function of PS - FLS acquisition time spans and the magnitude of surface reflectance change relative to the prediction day ([Figure 9](#i1o5qvu52bnb)). In addition, the multi-temporal FLS inputs are quality assured (QA) during the sampling step and outliers removed. Importantly, the calibration scheme can handle significant lags between the PS imagery to be harmonized and suitable FLS images as the calibration references can be sampled from images in the past or future (relative to the prediction date). As a result, the harmonization approach will continue to perform well over extended periods of cloudiness and FLS unavailability as long as a sufficient number of good FLS scenes can be identified within the "calibration window".
The multi-sensor and multi-time sampling approach ([Figure 9](#i1o5qvu52bnb)) reduces potential issues and uncertainties (For example, atmospheric contamination, cloud masking, BRDF effects, calibration inaccuracies) associated with both the PS and FLS data to create a very robust and temporally consistent radiometric reference. With this in place, a multivariate linear regression and decision tree approach ([Houborg and McCabe 2018a](#8gfufoj8ok4f)) is employed to learn non-linear scene, sensor, and band-specific translational associations. The resulting models are then used to convert PS TOA (PSTOA) reflectances into FLS-consistent SR (PSFLS). During this process, a number of techniques are implemented to avoid overfitting and to preserve band-specific textural features and spatial gradients present in the original 3 m PS imagery.
The CESTEM-based radiometric harmonization framework has been designed to be highly self-contained with "on-the-fly" radiometric correction models adapted to the characteristics of a specific sensor and local (quadrant-level) surface and atmospheric conditions on any given prediction date. As such the framework is designed to effectively and accurately create sensor agnostic analysis ready data from distributed (virtual) sensor constellations. The framework is largely insensitive to temporal inconsistencies ("noise") associated with the input data (PSTOA), which may result from calibration uncertainties and cross-sensor spectral differences. In fact, as showcased in [Figure 10](#luyifrjkr76s), adding significant random temporal noise to the PS input data has a largely indistinguishable impact on the harmonized results. Another noteworthy feature is the low sensitivity to inaccuracies associated with the reference data, in this case mostly resulting from cloud omission errors in the FORCE-based Sentinel-2 data ([Figure 10](#luyifrjkr76s)).
Note that because the CESTEM-based harmonization needs a sufficient number of clear-sky pixels in an image, and runs independently in each quadrant of a tile ([Figure 6](#vt0iehfmo0i4)), ARPS data will be unavailable for quadrants that have insufficient clear-sky regions.
*Figure 10: Illustration of the robustness of the CESTEM radiometric harmonization to noise in the input data streams (FLS and PS).*
### 4.5. Geometric Harmonization
The imagery used in making Analysis-Ready PlanetScope (For example, PS, L8/9, S-2) has been orthorectified using rigorous preprocessing protocols with a positional accuracy typically better than 10 m RMSE. Nevertheless, perfect image to image alignment is difficult to achieve, particularly when combining data from disparate sensor sources. As ARPS relies heavily on taking advantage of temporal information content for cloud masking and calibration, precise co-registration and sub-pixel fine alignment of stacked imagery becomes a necessity.
ARPS uses an implementation of the phase cross correlation technique ([Guizar-Sicairos et al., 2008](#xok54ba2ammh)) to robustly detect the global shift between two images with sub-pixel precision at various processing stages. Geometric harmonization/co-registration is applied to 1) PS scenes during the scene to quadrant/tile conversion step (step 3/4, [Figure 5](#bu6ydmlsd1u3)), 2) PSMOD and FLS-SR imagery stacks (step 5, [Figure 5](#bu6ydmlsd1u3)), and 3) the CESTEM calibrated (CESTEM-SR) imagery stack (step 7, [Figure 5](#bu6ydmlsd1u3)), as described in more detail below.
Sub-pixel shifts (y, x) are derived based on the overlapping clear-sky domain between a source (to be shifted) and reference/anchor image on a per-band basis. The shifts are evaluated independently in multiple image subsets distributed within the clear-sky overlap region of the two images. An optimal set of image subsets are defined by optimizing the clear-sky data percentages (as close to 100% as possible) and the band-specific cross-correlation. The cross-correlation constraint serves to identify subsets with good alignment features and to reduce the impact of any residual contamination. It follows that the number and sizes of the subsets may vary significantly as a function of the clear-sky percentage of the images. Images with significant cloud cover will typically be characterized by smaller subsets to fit within the clear-sky pixel "pockets". As the subset must be gap-free to enable sub-pixel precision in the shifting estimates, the subset domain will be down-adjusted iteratively until that is achieved or the minimum domain size is reached. In the latter case, small remaining gaps will be filled via nearest neighbor interpolation to not lose the sub-pixel precision. If gaps still remain, shifts will not be derived for the given subset. The "global" (For example, quadrant-level) shift estimate will be based on an average of the subset-level shift estimates after outlier removal. If the derived shifts are within acceptable limits they will be applied to the source image using a Fourier transformation approach. Final acceptance of the shifted image will depend on a series of cross-correlation checks to verify that the spatial correlations between the source and reference image actually improved as a result of the pixel shift adjustments. Non-passing cross-correlation checks may indicate challenges associated with deriving a robust shift estimate due to image quality issues and/or scene registration issues leading to non-global shifts at the quadrant-level. While the shifts are derived on a per-band basis, the final shift estimate will be based on the average of each band-specific shift given the generally high accuracy (\~0.25 pixels for SuperDove) of the PlanetScope band-to-band alignment ([Planet Team 2023](#9l7fdfs707pa)).
Geometric harmonization is needed when creating the quadrant-level image as it will typically combine scenes from multiple PlanetScope sensors ([Figure 4](#6aqvlipijlmp)), which may sometimes be slightly mis-aligned. The clear-sky overlap within a strip or between strips (For example, a strip signifies the set of scenes acquired from a single satellite in a single pass) is used to assess the sub-pixel shifts as described above. If the shifts are deemed valid they will be applied (using the Fourier transformation approach) to help ensure that the PlanetScope scenes within the quadrant are geometrically harmonized (aligned) before merging. However, it will not correct for mis-alignments within the scene due to registration issues when creating the scene composite from raw frames (done upstream of ARPS processing). This approach is applied to both PS-TOAR and PSMOD product artifacts during quadrant-level stacking ([Figure 5](#bu6ydmlsd1u3)).
The 30 m stacked PSMOD and FLS-SR product artifacts are bundle-adjusted using a series of "moving" geometric reference images. The reference images are generated by averaging predominantly clear-sky high quality PSMOD images acquired within partly overlapping moving time periods distributed across the full processing TOI. A minimum number (For example, 10) of contributing PSMOD images will be enforced for this purpose to help ensure robust and gap-free reference images. The contributing time window may be expanded if needed to make enough candidate images available. Subsequently, each stacked PSMOD and FLS-SR image is aligned against the closest reference image using the sub-pixel shift derivation approach outlined above.
The CESTEM calibrated (CESTEM-SR) imagery stack (3 m) is bundle-adjusted in a similar manner. In this case, the dynamic ("moving") geometric reference images will be generated by blending/averaging 8 multi-temporal candidate (For example, clear-sky, high quality) CESTEM-SR images acquired over partly overlapping moving time periods across the full processing TOI. Pixel-level outliers will be flagged and removed before generating the geometric reference images. Then each individual CESTEM-SR image is aligned against the closest reference image as described above.
### 4.6. Backfill Versus Forward-Fill Operation
Analysis-Ready PlanetScope can be processed in either backfill or forward-fill mode. Backfill signifies a run over a time of interest in the past. ARPS data creation always starts by processing at least one year of historical data, even if a shorter backfill (or no backfill) has been requested. This is necessary to establish deep temporal image stacks to inform the cloud masking, calibration, and harmonization processes. Forward-fill jobs are executed subsequent to a backfill operation and typically run as close to present time as possible and typically on a daily basis, processing any new imagery that has become available since the last job execution utilizing information from the deep temporal stacks generated during the backfill for cloud masking, and calibration purposes. Currently a 48 hour latency of delivering ARPS data during daily[1](#user-content-fn-1) forward-fill operation is targeted, which is a function of the latency of the input sources (For example, primarily PlanetScope and MODIS/VIIRS) and processing time.
Various factors may cause differences in product quality between forward-fill and backfill operation. Forward-fill typically involves near real-time (NRT) data processing and the inherent latencies in satellite data and FORCE processing can cause S-2 and/or L8/9 scenes acquired close to the prediction date to not be available to inform the calibration process. While the multi-temporal calibration approach should continue to perform well based on FORCE data acquired in the past relative to the prediction date, the inclusion of the most current (relative to the prediction date) information will tend to be beneficial. The temporally driven cloud detection approach will also benefit from having data available both before and after the prediction date to most effectively detect anomalies attributable to cloud, cloud shadow, or haze contamination. In daily forward-fill, the anomaly detection is based mostly on backwards looking imagery (For example, only data from one day in the future of the prediction day will be available at most), which can increase the risk of commission or omission errors in the cloud mask. Finally, in forward-fill (or when running ARPS within 9 days of present day) NRT MODIS or VIIRS surface reflectance products will be used instead of the standard products ([Section 2](#2-analysis-ready-planetscope-inputs)). The NRT MODIS/VIIRS products rely on backwards looking data alone to inform the BRDF correction and may therefore be less representative of prediction date surface conditions. While a bias correction procedure has been implemented to remedy this potential issue, the generally lower quality NRT MODIS/VIIRS data may impact the quality of the MODIS/VIIRS-based surface reflectance harmonization ([Figure 5](#bu6ydmlsd1u3)), which in turn may impact the accuracy of the CESTEM-based radiometric harmonization.
## 5. Known Limitations and Caveats
* **False cloud/shadow detections** may occur in certain cases: 1) if surface conditions change very rapidly, 2) during prolonged cloudiness, or 3) over AOIs with complex terrain and shadowing. Significant effort has gone into developing automated techniques to differentiate between actual change and atmospheric contamination, but in some cases commission errors can still be an issue.
* **Analysis-Ready PlanetScope is not suited for studies over snow covered surfaces**. As it is virtually impossible to robustly distinguish between snow and clouds based on 4-band VNIR data, periodic snow cover will in most cases be masked out as clouds. Because the radiometric harmonization relies on clear-sky data, snowy regions may have reduced radiometric quality, or be completely unavailable if no clear-sky regions were identified.
* The Analysis-Ready PlanetScope processing focuses on getting surface reflectance values correct for ground pixels, not clouds. In most cases, clouds will have a natural appearance, but **occasional discoloration may occur over clouds** in the image. This effect is not known to be associated with any errors in radiometric harmonization over ground pixels.
* As the Analysis-Ready PlanetScope processing is done independently for each tile, **tile boundary artifacts** can sometimes occur within AOIs which cross tile boundaries. This may be manifested in the form of typically small inter-tile brightness differences and sub-pixel mis-alignments.
* Lastly, the notion of a perfect product is utopian. Remote sensing is difficult. Cloud masking is a balancing act and an unwinnable battle between commission and omission errors. There will be cases where ARPS does not perform as well as we want it to. A lot of effort has gone into developing a differentiated next generation surface reflectance product with an ambition to be "best in class." We are committed to continuously improving it towards realizing the promise of high fidelity, timely, usable, and actionable insights from multi-source satellite observations.
## References
[]()
M. Claverie, J. Ju, J.G. Masek, J.L. Dungan, E.F. Vermote, J.-C. Roger, S.V. Skakun, C. Justice. 2018. The Harmonized Landsat and Sentinel-2 surface reflectance data set. Remote Sensing of Environment, 219, 145-161:
[]()
G. Doxani, E. Vermote, J.-C. Roger, F. Gascon, S. Adriaensen, D. Frantz, O. Hagolle, A. Hollstein, G. Kirches, F. Li, J. Louis, A. Mangin, N. Pahleva, B. Pflug, Q. Vanhellemont. 2018. Atmospheric Correction Inter-Comparison Exercise. Remote Sens., 10(2), 352:
[]()
G. Doxani, E.F. Vermote, J.-C. Roger, S. Skakun, F. Gascon, A. Collison, L. De Keukelaere, C. Desjardins, D. Frantz, O. Hagolle, M. Kim, J. Louis, F. Pacifici, B. Pflug, H. Poilvé, D. Ramon, R. Richter, F. Yin. 2023. Atmospheric Correction Inter-comparison eXercise, ACIX-II Land: An assessment of atmospheric correction processors for Landsat 8 and Sentinel-2 over land. Remote Sensing of Environment, 285, 113412.
[]()
ESA. 2024. The European Space Agency. Available online: (accessed on 12 May 2024)
[]()
D. Frantz. 2019a. FORCE—Landsat + Sentinel-2 Analysis Ready Data and Beyond. Remote Sensing, 11, 1124:
[]()
D. Frantz, M. Stellmes, P.A. Hostert. 2019b. Global MODIS Water Vapor Database for the Operational Atmospheric Correction of Historic and Recent Landsat Imagery. Remote Sens., 11, 257.
[]()
D. Frantz, E. Haß, A. Uhl, J. Stoffels, J. Hill. 2018. Improvement of the Fmask algorithm for Sentinel-2 images: Separating clouds from bright surfaces based on parallax effects. Remote Sens. Environ., 215, 471–481:
[]()
R. Houborg, M.F. McCabe. 2018a. Daily Retrieval of NDVI and LAI at 3 m Resolution via the Fusion of CubeSat, Landsat, and MODIS data. Remote Sensing, 10(6), 890:
[]()
R. Houborg, M.F. McCabe. 2018b. A Cubesat Enabled Spatio-Temporal Enhancement Method (CESTEM) utilizing Planet, Landsat and MODIS data. Remote Sensing of Environment, 209, 211-226:
[]()
M. Guizar-Sicairos, S.T. Thurman, J.R. Fienup. 2008. Efficient subpixel image registration algorithms. Optics Letters 33, 156-158:
[]()
J.W. Rouse, R.H. Hass, J.A. Shell, D. Deering. 1973. Monitoring vegetation systems in the Great Plains with ERTS-1. In: Third Earth Resources Technology Satellite Symposium. Washington DC, pp. 309–317
[]()
D.P. Roy, H.K Zhang, J. Ju, J.L. Gomez-Dans, P.E. Lewis, C.B. Schaaf, Q. Sun, J. Li, H. Huang, V. Kovalskyy. 2016. A general method to normalize Landsat reflectance data to Nadir BRDF Adjusted Reflectance. Remote Sensing of Environment, Vol. 176, pp 255–271:
[]()
D.P. Roy, J. Li, H.K. Zhang, L. Yan, H.Huang, Z. Li. 2017. Examination of Sentinel-2A multi-spectral instrument (MSI) reflectance anisotropy and the suitability of a general method to normalize MSI reflectance to nadir BRDF adjusted reflectance. Remote Sensing of Environment, Vol. 199, pp 25-38:
[]()
D.P. Roy, H. Huan, R. Houborg, V.S. Martins. 2021. A global analysis of the temporal availability of PlanetScope high spatial resolution multi-spectral imagery. Remote Sensing of Environment, Vol. 264, 112586:
[]()
C.B. Schaaf, F. Gao, A.H. Strahler, W. Lucht, X. Li, T. Tsang, N.C. Strugnell, X. Zhang, Y. Jin, J.-P. Muller et al. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote Sens. Environ., 83, 135–148:
[]()
D. Tanré, C. Deroo, P. Duhaut, M. Herman, J.J. Morcrette, J. Perbos, P.Y. Deschamps. 1990. Description of a Computer Code to Simulate the Satellite Signal in the Solar Spectrum: The 5S Code. Int. J. Remote Sens., 11, 659–668:
[]()
Z. Zhu, C.E. Woodcock. 2012. Object-Based Cloud and Cloud Shadow Detection in Landsat Imagery. Remote Sens. Environ., 118, 83–94:
[]()
Planet Team, 2023. Planet L1 Data Quality Q4 2023 Report. Status of Calibration and Data Quality for the PlanetScope Constellation, December 2023, Available online at . Last Accessed: May 13, 2024
[]()
S.A. Soenen, D. R. Peddle and C. A. Coburn. 2005. SCS+C: a modified Sun-canopy-sensor topographic correction in forested terrain. *IEEE Transactions on Geoscience and Remote Sensing*, vol. 43, no. 9, pp. 2148-2159:
[]()
P.M. Teillet, B. Guindon, D.G. Goodenough. 1982. On the slope-aspect correction of multispectral scanner data. Canadian Journal of Remote Sensing, 8 (2), pp. 82-106.
## Footnotes
1. While ARPS processing runs daily in forward-fill operation, data will only be delivered for a given day if at least some clear-sky pixels are present. [↩](#user-content-fnref-1)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/arps/techspec/v1-1-0/)
# Technical Specification
**SURFACE REFLECTANCE**
v1.1.0, April 2026
## 1. Analysis-Ready Planetscope Overview
The PlanetScope (PS) constellation of hundreds of CubeSats in low Earth orbits represents a novel observational resource, which when combined with advances in conventional spaceborne sensing has resulted in a proliferation of satellite sensor data with unprecedented spatial, temporal, and spectral resolution. This constitutes a revolution in the ability to derive time-critical, location-specific insights about dynamic land surface processes. However, the potential for these systems to support decision making is often limited by sensor interoperability issues ([Figure 1](#kz1mqwbgovxc)), cross-calibration challenges, and atmospheric contamination. These obstacles can stand in the way of realizing the full potential of these rich datasets.
*Figure 1: Sources of interoperability issues. Left: The reflectance field of the same observation target can appear very different at the point of the satellite sensor due to differences in satellite viewing and sun illumination angles augmented by shadow effects and non-lambertian surface characteristics (for example, as described by the Bidirectional Reflectance Distribution Function; BRDF). Right: Differences in spectral bands and spectral response functions can result in poor sensor interoperability. This is particularly pronounced when comparing Dove-C (for example, first generation PlanetScope) with public sensor sources (such as L8).*
At Planet, a rigorous methodology has been implemented and improved to enhance, harmonize, inter-calibrate, and fuse cross-sensor data streams. The CubeSat-Enabled Spatio-Temporal Enhancement Method (CESTEM) ([Houborg and McCabe 2018a](#8gfufoj8ok4f), [2018b](#xr6pcawhkolt)) leverages rigorously calibrated publicly accessible multispectral satellites (for example, Sentinel, Landsat, MODIS, VIIRS) to work in concert with the higher spatial and temporal resolution data provided by Planet's Dove CubeSats. The result is a next generation, analysis ready, harmonized Level-3 data product, which delivers a clean (for example, clouds and cloud shadows clearly labeled), temporally consistent, and radiometrically accurate 4-band surface reflectance (SR) data product.
Analysis-Ready PlanetScope (ARPS) combines distributed observations from the hundreds of individual sensors that make up the PlanetScope constellation (using three generations of hardware). These observations are radiometrically and geometrically harmonized with each other while ensuring radiometric consistency with a suite of widely used reference satellite platforms. The result is a highly temporally consistent stack of PlanetScope data. This next generation Analysis Ready Data (ARD) product is suitable for analytic and data science purposes. Analysis-Ready PlanetScope involves significant processing and novel methodology in the attempt to create a unique surface reflectance product enhanced in resolution, quality, and interoperability ([Figure 2](#xu3wgds3r48h)), as the pathway to usability and meaningful remote sensing driven insights.
*Figure 2: Normalized Difference Vegetation Index (NDVI) time series over a crop field near Lincoln (NE) over the course of two years (July 2021 – July 2023). The ARPS processing translates original PlanetScope Top Of Atmosphere (TOA) reflectance inputs into Surface Reflectances (SR) consistent with Landsat 8/9 and Sentinel-2 clear-sky observations. Note the increased harmonization amongst ARPS observations and FORCE as compared to PlanetScope SR.*
The unique features of Analysis-Ready PlanetScope can be summarized as:
* **Advanced radiometric harmonization which leverages rigorously calibrated third-party sensors (MODIS/VIIRS, Landsat 8/9, and Sentinel-2) for full fleet interoperability**
* **Rigorous, temporally driven, cloud and cloud shadow detection**
* **Cleaned (for example, with cloud mask included) Surface Reflectance values delivered with a 48 hour latency**
* **CubeSats with near-nadir field of view result in minimal BRDF variation effects**
* **Designed to provide high radiometric accuracy and spatio-temporal consistency**
* **Geometric harmonization with sub-pixel co-registration/alignment of stacked imagery**
* **Topographic correction to remove the effect of terrain and illumination conditions on the surface reflectance signal**
* **Includes pixel traceability information to easily identify source imagery for every data point**
## 2. Analysis-Ready Planetscope Inputs
[Table 1](#eayvkhwt1aol) lists the data sources currently used in Analysis-Ready PlanetScope (ARPS) production.
Planet's collection of hundreds of CubeSats operates in Sun synchronous orbits (altitude \~475 km) with a midmorning equatorial overpass time (9:30–11:30 a.m., local solar time) providing global near-nadir (\~4° field of view) imaging on a near-daily basis ([Roy et al., 2021](#nfg7qgvzajyq)). Three generations of "Doves" (collectively referred to as "PlanetScope" in this document) are used as input to ARPS products: the Dove-Classic constellation (2016–2022) is characterized by broad and partly overlapping spectral bands in the visible and near-infrared (NIR) spectrum ([Figure 1](#kz1mqwbgovxc)), whereas the Dove-R (2019–2022) and SuperDove (2020–) constellations are improved to be directly interoperable with the visible and narrow NIR bands of Sentinel-2. The nominal ortho scene size (at 475 km altitude) is also larger for Dove-R (\~25 km x 23 km) and SuperDove (\~32.5 km x 19.6 km) relative to Dove-Classic (\~25 km x 11.5 km). PlanetScope Top Of Atmosphere (TOA) Radiance inputs contribute the bulk of the observations used to make ARPS, and they are derived from 4-band Orthorectified Scene Products that have a resampled pixel size of 3 m (the ground sampling distance depends on the altitude and generation of each satellite and ranges from 3.7 to 4.2 m). While the SuperDove is an 8-band sensor (for example, it adds bands in the visible and red-edge domain compared to previous generations of Doves), currently only the blue, green, red, and NIR bands are used in ARPS production.
[]()
**Table 1: List of inputs currently used in Analysis-Ready PlanetScope production.**
| Product | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PS-TOA | Scene-based PlanetScope Top Of Atmosphere (TOA) Radiance (4-band, resampled to 3 m pixels) () |
| MCD43A4, MCD43A4N | Tile-based MODIS Surface Reflectance (SR) normalized to a nadir view direction and local solar noon (daily, 500 m) () |
| VNP43IA4, VNP43IA4N | Tile-based SR (VIIRS imagery bands) normalized to a nadir view direction and local solar noon (daily, 500 m) () |
| VNP43MA4, VNP43MA4N | Tile-based SR (VIIRS moderate bands) normalized to a nadir view direction and local solar noon (daily, 1000 m) () |
| FLS-SR | In-house implementation for tile-based generation of Nadir BRDF Adjusted Reflectances (NBAR) from Landsat 8/9 and Sentinel-2 data (4-band, 30 m). The Landsat 8/9 data have been spectrally adjusted to match Sentinel-2 spectral band passes. Based on the Framework for Operational Radiometric Correction for Environmental Monitoring (FORCE) () |
A scalable implementation of the Framework for Operational Radiometric Correction for Environmental Monitoring (FORCE version 3.7.10; [Frantz 2019a](#q93ufohcogsk)) is used for generating a combined Landsat 8/9 (L8/9) and Sentinel-2 (S-2) surface reflectance product (FLS-SR) to be used as the "gold reference" during the radiometric calibration and normalization of ARPS products. FORCE includes state-of-the-art atmospheric correction, topography/terrain correction, cloud and cloud shadow detection, spatial co-registration, and view angle normalization ([Frantz 2019a](#q93ufohcogsk)). FORCE infers surface reflectance from L8/9 and S-2 imagery using an implementation of the 5S (Simulation of the Satellite Signal in the Solar Spectrum) code ([Tanre et al., 1990](#4890nor5vtfe)). The aerosol optical depth is estimated from the imagery using a dark object based approach whereas the water vapor content is either estimated on a pixel-specific basis (S-2) or derived from a global MODIS-based database (L8/9) ([Frantz et al., 2019b](#wwy60iiky9or)). Clouds and cloud shadows are detected using a modified version of Fmask ([Zhu and Woodcock, 2012](#9896bortvtge)) that exploits parallax effects to improve detections for S-2 images ([Frantz et al., 2018](#6romhalczsxf)). However the FORCE derived cloud masks may be further refined as part of ARPS processing ([Section 4.3](#43-cloud-and-cloud-shadow-masking)). A global assessment of the FORCE atmospheric correction approach has been conducted as part of the Atmospheric Correction Inter-comparison Exercises (ACIX, ACIX-II) ([Doxani et al., 2018](#ivg7i1vy0qw2) & [2023](#trot904uc2nr)).
The FORCE implementation maps the L8/9 and S-2 data onto a common grid (for example, the UTM-based Military Grid Reference System) to produce 30 m resolution L8/9 and S-2 data with a 2–3 day frequency. A spectral bandpass adjustment ([Claverie et al. 2018](#dim35cgaa27y)) is applied to L8/9 to align with S-2 radiometry. Only the blue (center wl: 0.490 µm, bandwidth: 0.065 µm), green (center wl: 0.560 µm, bandwidth: 0.035 µm), red (center wl: 0.665 µm, bandwidth: 0.030 µm), and narrow NIR (center wl: 0.865 µm, bandwidth: 0.021 µm) bands (S-2 radiometry) are currently used for ARPS production. The reported bandwidths are the values measured at Full Width Half Maximum (FWHM).
MODIS or VIIRS surface reflectance (SR) data normalized to nadir view and local solar noon is a required input to the ARPS reference sampling and calibration process ([Section 4.4](#44-reference-sampling-and-radiometric-harmonization)). ARPS uses the version 6.1 combined (for example, Terra and Aqua) MCD43A4 product that provides daily 500 m SR in 7 bands corrected for reflectance anisotropy (MODIS has a \~110° field of view) using a semiempirical bidirectional reflectance distribution function (BRDF) ([Schaaf et al. 2002](#6j563z3v2wig)). The BRDF utilizes the best observations from both Terra and Aqua sensors collected over a 16-day period centered on the day of interest where observations at the day of interest are emphasized in the daily retrieval. Only the blue (0.459–0.479 µm), green (0.545–0.565 µm), red (0.62–0.67 µm), and NIR (0.841–0.876 µm) bands are ingested for ARPS processing. The near real-time product version (MCD43A4N) is used when the standard product is not available (for example, as dictated by a 9 days latency). The VIIRS products (VNP43IA4/VNP43IA4N, VNP43MA4/VNP43MA4N) have been designed to ensure continuity of MCD43 and are used as a backup should MCD43A4/MCD43A4N become unavailable. The VIIRS-based processing ingests the red (0.60–0.68 µm) and NIR (0.85–0.88 µm) Imagery bands (500 m) in addition to the blue (0.478–0.488 µm) and green (0.545–0.565 µm) Moderate bands (1000 m). Since the two latter bands are provided at a coarser spatial resolution (1000 m), the finer resolution (500 m) red band is used to super-resolve the 1000 m band data for consistency.
## 3. Analysis-Ready Planetscope Products
The Analysis-Ready PlanetScope product line (ARPS) is outlined in [Table 2](#zercfubc5ciy). The ARPS products are provided at a near-daily cadence and orthorectified onto a fixed grid (see [Section 3.4](#34-delivery-projection-and-gridding)) with a 3 m pixel size. The products can be produced starting from January 1, 2017 and up till present, deliverable with a 48 hour latency (For example, data requested for Monday will typically be delivered Wednesday).
[]()
**Table 2: Overview descriptions of the Analysis-Ready PlanetScope (ARPS) products.**
| Product key | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| ARPS-SR | ARPS Surface Reflectance (SR) product. PS TOA Reflectance radiometrically harmonized to 4-band FLS-SR using the CESTEM methodology. |
| ARPS-QA | ARPS Quality Assurance (QA) product |
| ARPS-STAC | ARPS SpatioTemporal Asset Catalog (STAC) items and catalog |
### 3.1. Surface Reflectance Product (ARPS-SR)
The Analysis-Ready PlanetScope Surface Reflectance product (ARPS-SR) records gridded (3 m), radiometrically and geometrically corrected orthorectified PlanetScope data in four spectral bands (blue, green, red, NIR) at a near-daily interval. The data is stored in 16-bit integer format (with a multiplication factor of 10,000) as cloud optimized geotiffs compressed using LZW compression. During ARPS processing and harmonization, 4-band PS TOA Reflectance (PS-TOAR) (converted from the radiances) are transformed into surface reflectances ensuring radiometric consistency with Sentinel-2. As a result the spectral bands and spectral response functions of ARPS data ([Table 3](#o023kp6ilo0e)) will be equivalent to the blue (B2), green (B3), red (B4), and narrow NIR (B8a) bands of Sentinel-2 ([ESA 2024](#c5vrv0vt2fwb)).
The ARPS-SR data represents Normalized BRDF Adjusted Reflectances (NBAR) as the Landsat 8/9 and Sentinel-2 data used for cross-calibration have been normalized to nadir view ([Roy et al. 2016](#hygf64l76qgv), [2017](#37ck249ixdf9)). As the ARPS cross-calibration adopts a multi-temporal reference sampling approach (see [Section 4.4](#44-reference-sampling-and-radiometric-harmonization)), the significant uncertainties related to the L8/L9/S-2-based BRDF normalization ([Roy et al. 2017](#37ck249ixdf9)) are likely to cancel out. In addition, in contrast to L8/9 (\~15° field of view) and particularly S-2 (\~21° field of view), the PlanetScope sensors are nadir viewing natively (\~4° field of view), which will act to further reduce view angle BRDF effects.
[]()
**Table 3: ARPS-SR data format specifications providing the band-specific center wavelengths and bandwidths (bw). The bandwidths are the values measured at FWHM.**
| Layer | Description | Date Type | Valid range | Scale factor |
| ------ | --------------------------------------------- | --------------------- | ----------- | ------------ |
| Band 1 | Blue band (0.490 µm, bw: 0.065 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 2 | Green band (0.560 µm, bw: 0.035 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 3 | Red band (0.665 µm, bw: 0.030 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
| Band 4 | NIR band (0.865 µm, bw: 0.021 µm) SR (NBAR) | 16-bit signed integer | 1 - 10,000 | 0.0001 |
### 3.2. Quality Assurance Product (ARPS-QA)
The Analysis-Ready PlanetScope Quality Assurance product (ARPS-QA) is a 2 layer thematic raster using the same spatial grid as the corresponding ARPS-SR product. It contains information denoting cloud and cloud shadow detection (layer 1) and pixel traceability/provenance (layer 2) ([Table 4](#8leouj2apj)).
[]()
**Table 4: ARPS-QA data format specifications. Note that additional metadata have been embedded in the tiff file, as described in the table and listed separately in [Table 5](#lpfw7cjfqo8i)**
| Layer | Description | Date Type | Valid range | Scale factor | Offset |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------- | ------------ | ------ |
| Layer 1 | Cloud and cloud shadow mask 1 = Clear 2 = Bright Clouds 3 = Cloud shadows 4 = Haze 5 = Adjacent clouds/clouds shadows 6 = Additional cloud/shadow/haze elements based on a cross-scene correlation detection approach 7 = Suspect (for example, poor image quality, radiometric or geometric quality issues) -999 = Scene data not available | 16-bit signed integer | 1 - 7, and -999 | 1 | 0 |
| Layer 2 | Pixel traceability/provenance mask (*see embedded metadata for scene IDs*) -999 = Scene data not available | 16-bit signed integer | 1 - 200, and -999 | 1 | 0 |
[Figure 3](#dcrzarok9z9m) depicts the cloud and cloud shadow mask from QA layer 1.
*Figure 3: QA layer 1 (cloud and cloud shadow mask) and input PS-TOAR product.*
A pixel traceability/provenance mask is also provided in QA layer 2 ([Figure 4](#6aqvlipijlmp)). This raster layer identifies the footprints of the PlanetScope scenes used to produce any given tile image (cloudy or clear). Each domain is associated with a unique integer value that is linked to a scene identifier (for example, Itemtype/sceneID) embedded as metadata in the QA geotiff. The scene identifier (For example, PSScene/20190701\*172222\_104e) provides the information needed to locate and access the source data through Planet's API. The embedded metadata may be displayed using GDAL (For example, `gdalinfo name_of_file.tif`). Note that the scene identifier is formatted as `**\_`. This provides information on the time of acquisition for each pixel in the image. Importantly, and as further detailed in [Section 4.6](#46-merging-of-satellite-specific-processing-chunks), more than one PlanetScope scene may be contributing to the same date-specific image domain. If that is the case, the tiff embedded metadata will list two or more scene identifier links to the unique integer value (footprint).
*Figure 4: QA layer 2 (pixel traceability mask) for the tile in Figure 3 (8000 x 8000 pixels) on July 1, 2019. In this case, a total of 10 PS ortho scenes from three separate strips were used to construct the tile image. The associated scene identifiers were extracted from the ARPS-QA embedded metadata. The visible seam lines in the PS-TOAR product result from merging Dove-R (reddish strip) and Dove-C (greenish strip) scene data with quite different spectral bands and Relative Spectral Response (RSR). Note that these transitions are not visible in the final ARPS-SR output.*
The QA product includes several pieces of non-raster metadata embedded in the tiff header. These are described in [Table 5](#lpfw7cjfqo8i).
[]()
**Table 5: List of metadata embedded in the header of ARPS-QA tiff files**
| Name | Description | Example |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CREATED | Timestamp of the product creation, corresponding to the time at which contributing satellite observations were gathered. | 2024-09-20T17:19:27Z |
| PERCENTAGE\_CLEAR | Fraction of pixels in the raster marked as class 1, "clear", in the QA layer 1 cloud mask | 86.68 |
| PERCENTAGE\_STANDARD\_QUALITY | Fraction of observed pixels in the tile which came from "standard" (as opposed to "test" quality PlanetScope images, see [Roy et al., 2021](#nfg7qgvzajyq)) | 100 |
| PIPELINE\_VERSION | Version identifier for the image processing pipeline used to create that day's data | 1.0.0 |
| RUN\_TYPE | Designates whether the data were produced in "backfill" or "forwardfill" mode. (See [Section 4.7](#47-backfill-versus-forward-fill-operation)) | backfill |
| SCENE\_IDS\[LAYER\_2\_VALUE] | Newline-separated scene IDs corresponding to integer reference numbers in QA layer 2. See the layer 2 description above for more information. | PSScene/20210708\_131909\_101b\[1] PSScene/20210708\_131910\_101b\[2] PSScene/20210708\_131911\_101b\[3] PSScene/20210708\_131912\_101b\[4] PSScene/20210708\_134254\_06\_2406\[5] None\[-999] |
| PERCENTAGE\_BAD\_GEOMETRY | The percentage of pixels identified with bad geometry for each scene contributing to the footprint (as identified in the layer 2 scene provenance raster) | 0\[1] 0\[2] 0\[3] 0\[4] 0\[5] None\[-999] |
| PERCENTAGE\_BAD\_RADIOMETRY | The percentage of pixels identified with bad radiometry for each scene contributing to the footprint (as identified in the layer 2 scene provenance raster) | 0\[1] 0\[2] 0\[3] 0\[4] 0\[5] None\[-999] |
| SCENE\_SOLAR\_AZIMUTH\[LAYER\_2\_VALUE] | The solar azimuth in degrees for each scene contributing to the footprint (as identified in the layer 2 scene provenance raster) | 40.30\[1] 40.20\[2] 40.20\[3] 40.20\[4] 35.00\[5] None\[-999] |
| SCENE\_SOLAR\_ELEVATION\[LAYER\_2\_VALUE] | The solar elevation in degrees for each scene contributing to the footprint (as identified in the layer 2 scene provenance raster) | 38.60\[1] 38.50\[2] 38.50\[3] 38.40\[4] 41.90\[5] None\[-999] |
### 3.3. Spatiotemporal Asset Catalog (ARPS-STAC)
All Analysis-Ready PlanetScope products are delivered with a SpatioTemporal Asset Catalog (STAC) file that conforms to the STAC specifications. This STAC item contains information that summarizes the properties of the ARPS-SR and ARPS-QA products. This includes the version of ARPS that the products were generated with, the dates that the products were created, and support for several STAC extensions.
| STAC Extension | Description |
| -------------- | ------------------------------------------------------------------------ |
| Projection | Coordinates representing the bounding geometry of the raster's footprint |
| Raster | Properties of the tile pixels |
In addition, the "properties" section of each STAC item contains a copy of the metadata included in the header of the QA raster (described in [Table 5](#lpfw7cjfqo8i)). Metadata entries which contain lists of items (For example, "SCENE\_IDS\[LAYER\_2\_VALUE]") are contained in the STAC item as lists of items, not single strings. Metadata keys are given in lower case (For example, "SCENE\_IDS\[LAYER\_2\_VALUE]" from the tiff header is "scene\_ids\[layer\_2\_value]" in the STAC item's "properties" block).
### 3.4. Delivery, Projection, and Gridding
Analysis-Ready PlanetScope products are delivered through the [Planet Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md), clipped to a provided Area of Interest (AOI). Each Subscription will receive 3 files (ARPS-SR, ARPS-QA, and ARPS-STAC) for each day in which at least some PlanetScope imagery intersects the requested AOI. If no PlanetScope surface reflectance data are available for a given day over the requested AOI, no files will be provided for that day. The AOI-clipped data have a 3 m pixel size and are projected in the UTM zone intersected by their extent using the WGS-84 horizontal datum.
If a requested AOI is too large to deliver as a single file, it will instead be delivered as a series of regularly gridded raster tiles. Tiles have a 3 m pixel size, a 24 by 24 km extent (8000 pixel width and height), and are projected in the UTM zone intersected by their extent using the WGS-84 horizontal datum. Tile identifiers are based on a "{i}E-{j}N" template, where "i" is the zero-based easting index and "j" is the zero-based northing index using the origin of the UTM zone's coordinate reference system. For tiled delivery, each subscription will receive one ARPS-SR, one ARPS-QA, and one ARPS-STAC file per tile per day.
Regardless of the size of the requested AOI, all ARPS processing described in this document takes place using regularly gridded raster tiles. The tile size for each Subscription is selected from a pre-defined set of grids based on the size and placement of the requested AOI.
## 4. Analysis-Ready Planetscope Methodology
*Figure 5: A generalized overview of Analysis-Ready PlanetScope processing modules for any given ARPS tile and TOI. The diagram highlights the key intermediate and final product artifacts, the associated pixel resolution (3 or 30 m) and processing features (For example, cloud masking, radiometric and geometric harmonization, time-series processing).*
The overall methodological elements of Analysis-Ready PlanetScope surface reflectance processing are diagrammed in [Figure 5](#bu6ydmlsd1u3). ARPS products are based on an implementation of the CubeSat-Enabled Spatio-Temporal Enhancement Method (CESTEM), which has been described in detail in [Houborg and McCabe 2018a](#8gfufoj8ok4f)/[2018b](#xr6pcawhkolt). ARPS processing includes significant refinements and additional functionality related to geometric harmonization, topographic correction, and cloud masking. Key elements of the approach and processing specifics are outlined below.
While ARPS data are delivered as clipped AOIs, they are processed in units of tiles (as described in [Section 3.4](#34-delivery-projection-and-gridding)).
### 4.1. Tile-Level Stacking
After identifying the source imagery (PS-TOA, FLS-SR, PSMOD) that intersect with a given ARPS tile over a specified Time Of Interest (TOI) (step 1, [Figure 5](#bu6ydmlsd1u3)), the respective input streams are stacked and re-gridded to the ARPS tiling system ([Section 3.4](#34-delivery-projection-and-gridding)) with either a 3 m or 30 m pixel resolution (step 2/3/4, [Figure 5](#bu6ydmlsd1u3)).
In the case of the scene-based PlanetScope TOA reflectance (PS-TOAR) data, several scenes from multiple satellites may be overlapping with parts of the tile domain on any given day ([Figure 4](#6aqvlipijlmp)). Each satellite will in general take multiple sequential scenes, collectively designated a "strip". Satellite-specific scenes (for example, scenes from a given satellite strip) will be processed, merged, and clipped to the tile domain independently. The merging of the satellite-specific tiles will happen once all radiometric and geometric processing is complete (step 8, [Figure 5](#bu6ydmlsd1u3)) as further detailed in [Section 4.6](#46-merging-of-satellite-specific-processing-chunks).
A phase correlation technique ([Section 4.5](#45-geometric-harmonization)) is used to help ensure that the PlanetScope scenes from a given satellite-specific strip are geometrically aligned/co-registered (with sub-pixel precision) before compositing the strip. In addition, the re-aligned PS-TOAR scenes are brightness harmonized across the strip domain to facilitate a seamless surface reflectance calibration ([Section 4.4](#44-reference-sampling-and-radiometric-harmonization)). The brightness harmonization utilizes the clear-sky overlap between scenes within the satellite-specific strip to derive band-specific regression coefficients that are used to normalize the reflectance magnitudes across the scenes.
A 30 m resolution stack of MODIS/VIIRS Surface Reflectance-calibrated PlanetScope imagery (PSMOD) is also produced (step 2/4, [Figure 5](#bu6ydmlsd1u3)). The MODIS/VIIRS calibration is performed at the PlanetScope scene level using day-coincident MCD43/VNP43 NBAR products ([Table 1](#eayvkhwt1aol)) as the radiometric reference, translating PS-TOAR into MODIS/VIIRS-consistent SR data ([Houborg and McCabe 2018a](#8gfufoj8ok4f), [2018b](#xr6pcawhkolt)) (step 2, [Figure 5](#bu6ydmlsd1u3)). The scenes from a given satellite-specific strip are processed as described above for PS-TOAR when producing the tile. This also involves co-registration of the 30 m PSMOD scenes prior to merging and tile composition.
The FORCE-based Surface Reflectance tiles (FLS-SR) are mapped onto the ARPS tiling grid in a similar way.
### 4.2. Topographic Correction
*Figure 6: Visualization of the impact of the topographic correction on PlanetScope imagery acquired over a mountainous region in Austria on 2022-07-19. The impacts are significant over the sloping terrain with reflectance corrections ranging from approximately ±0.05 (red) and ±0.20 (NIR) reflectance units.*
Topography (irregular shape of the terrain) will affect the surface reflectance as a function of sun illumination conditions (sun elevation and sun azimuth), terrain shape (slope and aspect), and surface and atmospheric characteristics. Topography can significantly alter the reflectance signal and obfuscate the interpretation of surface characteristics in space and time. Topographic corrections attempt to remove the effect of topography on reflectance so that identical surface phenomena (such as vegetation type) produce comparable reflectance signals irrespective of terrain characteristics.
A topographic correction is applied to the PlanetScope-based product artifacts ([Figure 6](#e9hb9udfhcvd)) produced by the ARPS pipeline. The FORCE surface reflectance data have also been corrected for the effects of topography on reflectance ([Frantz 2019a](#q93ufohcogsk)). The topographic correction adopted by ARPS shares similarities with the approach adopted in FORCE and is based on modeling illumination conditions using a Digital Elevation Model (GLO-30, ) to compute slope and aspect information (using the GDAL "gdaldem" functionality) along with sun elevation and sun azimuth information from the PS scenes. For simplicity, Lambertian (for example, no directional dependence on reflected light) surface conditions are assumed. The implementation is based on the Sun-Canopy-Sensor with C-correction approach described in [Soenen et al. 2005](#jqhq9xbqv5m4). The semi-empirical C-correction component is included to avoid over-corrections by accounting for the effects of diffuse radiation ([Teillet et al. 1982](#kcjkhcz64qas)). Band-specific C values are initially derived for each date and satellite-specific tile domain (for example, for slopes greater than 10 degrees) from a linear regression between pixel-wise illumination condition (a function of slope, aspect, sun elevation, and sun azimuth) and the reflectance signal. The derived C values can be associated with significant uncertainty and will strongly depend on the reflectance type (SR versus TOAR) and atmospheric condition (such as cloud contamination, haze, and degree of diffuse radiation). The derived C values (across the full TOI) are used to train SR and TOAR specific C models that will subsequently be used to predict more robust and consistent band-specific C values needed for a reliable topographic correction of the PS-based stacked product artifacts produced in steps 3 and 4 ([Figure 5](#bu6ydmlsd1u3)). A Cubist rule-based regression approach is used for predicting the band-specific C values as a function of illumination condition, sun elevation, sun azimuth, haze percentages, and aerosol optical depth (AOD). Daily AOD values are extracted from the Terra MODIS global Aerosol Optical Thickness product (MOD09CMA). This product has a spatial resolution of 5.5 km and the average of the best quality pixels within the tile domain is used. If no best quality pixels are found, the search is extended within an expanded domain centered on the tile and includes all valid values irrespective of quality. The C values are strongly dependent on scene haziness (for example, degree of diffuse radiation), and the inclusion of the AOD information helps create accurate band-specific models represented by Pearson's correlations typically in the range of 0.85 to 0.95.
The topographic correction is applied to PS pixels identified as either clear-sky or haze. The topographic correction is shown to significantly improve the agreement with day-coincident FORCE over AOIs with complex terrain and improves the overall quality of the ARPS data in regions with significant topography.
### 4.3. Cloud and Cloud Shadow Masking
Analysis-Ready PlanetScope cloud and cloud shadow detection (step 5, [Figure 5](#bu6ydmlsd1u3)) is performed at 30 m resolution using a temporally-driven approach that takes advantage of PlanetScope and FORCE (L8/9, S-2) surface reflectance information in a synergistic way. The approach starts from the original scene-based cloud and cloud shadow masks associated with both the PlanetScope and FORCE data. For PlanetScope, the initial cloud and cloud shadow mask is produced during the MODIS/VIIRS-based calibration stage (step 2, [Figure 5](#bu6ydmlsd1u3)) predominantly informed by UDM 2.0 (before 2023-11-23) or 2.1 (after 2023-11-23) detections, when available. A cloud verification approach is applied at this step in an attempt to reduce commission/omissions errors.
*Figure 7: Example of ARPS cloud (white) and cloud shadow (black) detections over a region in Bolivia. Yellow represents the applied buffer around the detections.*
The temporally-driven detection approach can accommodate PS and FORCE data acquired at different times on the same day. The multi-source input data are first geometrically harmonized (see [Section 4.5](#45-geometric-harmonization)) to improve detection results and reduce commission issues resulting from pixels not being properly aligned. The detection approach utilizes clear-sky observations (for example, as identified by the initial cloud masks) over a flexible temporal window (up to ±1 year) for any given 30 m pixel to help flag spectral outliers potentially resulting from cloud, cloud shadow, or haze contamination. The deep temporal stack of clear-sky observations is used to create a clear-sky background image for each acquisition date over the defined TOI. The clear-sky background image generation utilizes clear-sky information acquired from multiple dates in the past and future (if available) relative to the prediction date, and adopts daily class-specific spectral trajectories (derived on the basis of the clear-sky imagery stack) to change/adjust the past/future acquisition data to be more representative of surface conditions on the prediction date. After outlier screening, the temporally interpolated clear-sky observations are compared against the prediction date imagery to flag pixel domains (if any) exhibiting spectrally anomalous behavior (for example, dips or spikes). A carefully weighted average of the multi-temporal clear-sky inputs (this will include the prediction date data if not identified as anomalous) are then used to create the clear-sky background image. Next, the clear-sky background image is used in combination with the actual image acquired on the prediction date to identify spectrally distinct classes using an unsupervised k-means clustering approach. A suite of spectral difference metrics, such as the difference in red and NIR reflectance between the background and actual imagery, combined with a set of carefully defined spectral thresholds and a number of other constraints are then used to classify each cluster as clear, cloud, cloud shadow, or haze. The detection of haze can be particularly uncertain and MODIS-based AOD values (see [Section 4.2](#42-topographic-correction)) are integrated to help constrain and validate the UDM2-based haze detections to reduce false positives. Additional cross-correlation tests between the background and actual imagery serve to further resolve and label any cloud, cloud shadow, and haze contaminations. Furthermore, a series of automated techniques are implemented to verify these classifications and avoid (to the extent possible) masking out actual change. This includes the integration of hillshade information to help reduce commission issues in landscapes with significant terrain shadowing.
The cloud detected areas are expanded using a buffer zone (for example, adjacent cloud domain, layer 1 in [Table 4](#8leouj2apj)) (see also [Figure 7](#gwrkkacfyz3d)) to make it more likely that most of the contaminated pixels are identified in the final outputs. The scheme will refine and update the scene-based cloud masks (30 m) associated with both the PS (PSMOD-H) and FORCE (FLS-SR-H) data (step 5, [Figure 5](#bu6ydmlsd1u3)).
After the completion of the cloud masking step, a cloud verification step is invoked to further reduce commission errors. This step will only serve to unmask presumably false cloud/cloud shadow detections based on comparisons against updated clear-sky spectral trajectory signatures along with other verification metrics.
### 4.4. Reference Sampling and Radiometric Harmonization
At its core, the Cubesat-Enabled Spatio-Temporal Enhancement Method (CESTEM) serves as a flexible mechanism to radiometrically harmonize multi-sensor spectral data into a consistent radiometric surface reflectance standard (for example, the "gold standard"). The FORCE-based surface reflectance product (30 m) ([Table 1](#eayvkhwt1aol); FLS-SR) is currently adopted as the gold standard. CESTEM is characterized by a number of unique features:
* Does not require day co-incident acquisitions (PS versus L8/L9/S-2) for cross-calibration/harmonization
* Implements a secondary MODIS/VIIRS-based harmonization to correct for surface reflectance changes occurring over given PS and L8/L9/S-2 acquisition time spans
* Reduces uncertainties associated with both PS and L8/L9/S-2 data via carefully assigned image quality weights and temporally-driven anomaly detection
* Can harmonize data from sensors with contrasting spectral bands and Relative Spectral Responses
* Is largely insensitive to noise (such as calibration uncertainties) in the input data (such as PS-TOA)
* Does not require PS inputs to be atmospherically corrected and is agnostic to PS input type (for example, should work equally well with either DNs, TOA radiances, or TOA reflectances)
* The calibration model is locally constrained (for example, specific to each PS tile-level image domain) and therefore much less prone to overfitting and portability issues (such as "hallucinations") relative to more generic AI driven model implementations
*Figure 8: Diagram of the CESTEM radiometric harmonization framework, translating image stacks of PlanetScope TOA radiance (PS^TOA) into FORCE-consistent (Landsat 8/9/Sentinel-2) Surface Reflectance (PS^FLS).*
The CESTEM-based harmonization (step 6, [Figure 5](#bu6ydmlsd1u3), [Figure 8](#i1o5qvu52bnb)) is applied to all PlanetScope images acquired over a defined Time Of Interest (TOI) drawing spectral reference data (for example, blue, green, red, and NIR) from a pool of FORCE L8/L9/S-2 SR (FLS-SR) images acquired over a predefined "calibration window" (typically one year centered around the TOI). In order to reliably use past or "future" FLS-SR images for calibration purposes they must be associated with a day-coincident PS acquisition. Critical to this process is the use of MODIS/VIIRS-consistent (for example, MCD43/VNP43) PlanetScope data (PSMOD) to quantify relative surface reflectance changes over given PS – FLS acquisition time spans ([Figure 8](#i1o5qvu52bnb)). It follows that data from multiple FLS acquisitions will be sampled to generate a given PS coincident calibration reference image (FLS^REF), using composite weights derived as a function of image quality, PS – FLS acquisition time spans, and the magnitude of surface reflectance change relative to the prediction day ([Figure 8](#i1o5qvu52bnb)). The image quality weight is a function of scene quality ("standard" vs "test"), cloud, haze, and snow percentages, daily aerosol optical depth (AOD) from MODIS (see [Section 4.2](#42-topographic-correction)), and sun elevation difference between the Landsat/Sentinel-2 and PlanetScope acquisition times. The image quality weights help ensure that the highest quality FLS – PS pairs are weighted the most during the harmonization process, reducing uncertainties resulting from atmospheric correction uncertainties, BRDF effects, and residual cloud and haze contamination. In addition, the multi-temporal FLS inputs are further quality assured (QA) during the sampling step and outliers are removed. Importantly, the calibration scheme can handle significant lags between the PS imagery to be harmonized and suitable FLS images as the calibration references can be sampled from images in the past or future (relative to the prediction date). As a result, the harmonization approach will continue to perform well over extended periods of cloudiness and FLS unavailability as long as a sufficient number of good FLS scenes can be identified within the "calibration window".
The multi-sensor and multi-time sampling approach ([Figure 8](#i1o5qvu52bnb)), along with the associated weights, reduces potential issues and uncertainties (such as atmospheric contamination, cloud masking, BRDF effects, calibration inaccuracies) associated with both the PS and FLS data to create a very robust and temporally consistent radiometric reference. With this in place, a multivariate linear regression and decision tree approach ([Houborg and McCabe 2018a](#8gfufoj8ok4f)) is employed to learn non-linear tile-, sensor-, and band-specific translational associations. The resulting models are then used to convert PS TOA (PS^TOA) reflectances into FLS-consistent SR (PS^FLS). During this process, a number of techniques are implemented to avoid overfitting and to preserve band-specific textural features and spatial gradients present in the original 3 m PS imagery.
The CESTEM-based radiometric harmonization framework has been designed to be highly self-contained with "on-the-fly" radiometric correction models adapted to the characteristics of a specific sensor, satellite strip, and local (tile-level) surface and atmospheric conditions on any given prediction date. As such the framework is designed to effectively and accurately create sensor agnostic analysis ready data from distributed (virtual) sensor constellations. The framework is largely insensitive to temporal inconsistencies ("noise") associated with the input data (PS^TOA), which may result from calibration uncertainties and cross-sensor spectral differences. In fact, as showcased in [Figure 9](#luyifrjkr76s), adding significant random temporal noise to the PS input data has a largely indistinguishable impact on the harmonized results. Another noteworthy feature is the low sensitivity to inaccuracies associated with the reference Sentinel-2 data ([Figure 9](#luyifrjkr76s)), in this case mostly resulting from cloud omission errors in the FORCE-based Sentinel-2 data.
The CESTEM-based harmonization typically relies exclusively on clear-sky pixels across the tile domain to inform model training. However, if the clear-sky percentage is less than 0.5% any available haze contaminated pixels will be included in the model training. ARPS data will be unavailable for tiles that have less than 100 clear-sky or haze pixels.
*Figure 9: Illustration of the robustness of the CESTEM radiometric harmonization to noise in the input data streams (FLS and PS).*
### 4.5. Geometric Harmonization
The imagery used in making Analysis-Ready PlanetScope (such as PS, L8/9, S-2) has been orthorectified using rigorous preprocessing protocols with a positional accuracy typically better than 10 m RMSE. Nevertheless, perfect image to image alignment is difficult to achieve, particularly when combining data from disparate sensor sources. As ARPS relies heavily on taking advantage of temporal information content for cloud masking and calibration, precise co-registration and sub-pixel fine alignment of stacked imagery becomes a necessity.
ARPS uses an implementation of the phase cross correlation technique ([Guizar-Sicairos et al., 2008](#xok54ba2ammh)) to robustly detect the global shift between two images with sub-pixel precision at various processing stages. Geometric harmonization/co-registration is applied to: 1) PS scenes during the satellite strip to tile conversion step (step 3/4, [Figure 5](#bu6ydmlsd1u3)), 2) PSMOD and FLS-SR imagery stacks (step 5, [Figure 5](#bu6ydmlsd1u3)), and 3) the CESTEM calibrated (CESTEM-SR) imagery stack (step 7, [Figure 5](#bu6ydmlsd1u3)).
Sub-pixel shifts (y, x) are derived based on the overlapping clear-sky domain between a source (to be shifted) and reference/anchor image on a per-band basis. The shifts are evaluated independently in multiple image subsets distributed within the clear-sky overlap region of the two images. An optimal set of image subsets are defined by optimizing the clear-sky data percentages (as close to 100% as possible) and the band-specific cross-correlation. The cross-correlation constraint serves to identify subsets with good alignment features and to reduce the impact of any residual contamination. It follows that the number and sizes of the subsets may vary significantly as a function of the clear-sky percentage of the images. Images with significant cloud cover will typically be characterized by smaller subsets to fit within the clear-sky pixel "pockets". As the subset must be gap-free to enable sub-pixel precision in the shifting estimates, the subset domain will be down-adjusted iteratively until that is achieved or the minimum domain size is reached. In the latter case, small remaining gaps will be filled via nearest neighbor interpolation to not lose the sub-pixel precision. If gaps still remain, shifts will not be derived for the given subset. The "global" (for example, tile-level) shift estimate will be based on an average of the subset-level shift estimates after outlier removal. If the derived shifts are within acceptable limits they will be applied to the source image using a Fourier transformation approach. Final acceptance of the shifted image will depend on a series of cross-correlation checks to verify that the spatial correlations between the source and reference image actually improved as a result of the pixel shift adjustments. Non-passing cross-correlation checks may indicate challenges associated with deriving a robust shift estimate due to image quality issues and/or scene registration issues leading to non-global shifts at the tile-level. While the shifts are derived on a per-band basis, the final shift estimate will be based on the average of each band-specific shift given the generally high accuracy (\~0.25 pixels for SuperDove) of the PlanetScope band-to-band alignment ([Planet Team 2023](#9l7fdfs707pa)).
Geometric harmonization is first enforced when creating the tile-level image as it may combine multiple scenes from the same PlanetScope sensor (for example, a satellite strip), which may sometimes be slightly mis-aligned. The clear-sky overlap within a strip (for example, a strip signifies the set of scenes acquired from a single satellite in a single pass) is used to assess the sub-pixel shifts as described above. If the shifts are deemed valid they will be applied (using the Fourier transformation approach) to help ensure that the PlanetScope scenes within the tile are geometrically harmonized (aligned) before merging. However, it will not correct for mis-alignments within the scene due to registration issues when creating the scene composite from raw frames (done upstream of ARPS processing). This approach is applied to both PS-TOAR and PSMOD product artifacts during tile-level stacking ([Figure 5](#bu6ydmlsd1u3)).
The 30 m stacked PSMOD and FLS-SR product artifacts are bundle-adjusted using a series of "moving" geometric reference images. The reference images are generated by averaging predominantly clear-sky high quality PSMOD images acquired within partly overlapping moving time periods distributed across the full processing TOI. A minimum number of contributing PSMOD images will be enforced for this purpose to help ensure robust and gap-free reference images. The contributing time window may be expanded if needed to make enough candidate images available. Subsequently, each stacked PSMOD and FLS-SR image is aligned against the closest reference image using the sub-pixel shift derivation approach outlined above.
The CESTEM calibrated (CESTEM-SR) imagery stack (3 m) is bundle-adjusted in a similar manner. In this case, the dynamic ("moving") geometric reference images will be generated by blending/averaging a minimum of 10 multi-temporal candidate (such as clear-sky, high quality) CESTEM-SR images acquired over partly overlapping moving time periods across the full processing TOI. Pixel-level outliers will be flagged and removed before generating the geometric reference images. Then each individual CESTEM-SR image is aligned against the closest reference image as described above.
In some cases, pixels at the borders of scenes will be marked "suspect" in the QA product's cloud mask where sub-pixel shifting may have introduced additional uncertainty into those pixels' radiometry.
### 4.6. Merging of Satellite-Specific Processing Chunks
The radiometric and geometric harmonization steps described above are done independently for each satellite-specific strip (for example, a strip signifies the set of scenes acquired from a single satellite in a single pass) on any given date, resulting in a series of fully harmonized, date and satellite-specific processing chunks spanning the requested TOI. Often, more than one PlanetScope scene/strip may be contributing to the same date-specific image domain, and the satellite-specific processing chunks available on a given date are merged to produce the final tile-based ARPS product artifacts (step 8, [Figure 5](#bu6ydmlsd1u3)). The default approach is a best-scene-on-top priority stacking approach when merging the available clear-sky observations across the different processing chunks. The prioritization weights are established as a function of image quality, calibration robustness, and cloud contamination. Outlier detection and masking will be enabled if more than two clear-sky observations (for example, from different PS satellites) are available on a given date. The high radiometric consistency between the satellite-specific sources helps ensure consistency in the merged output but a weighted blending technique across transition zones is also adopted to ensure seamless transitions between clear-sky domains originating from different satellite sources.
A different best-on-top prioritization protocol is used for the domain that is cloudy across all of the satellite-specific processing chunks. The adopted protocol will prioritize those cloud-contaminated pixels that are most likely to retain surface recoverable information. As a result, pixels identified as haze will be assigned the highest priority whereas pixels identified as bright clouds will be assigned the lowest priority. See [Table 6](#mrgpriority) for the complete priority order.
[]()
**Table 6: Priority order for selecting contaminated pixels when merging satellite-specific processing chunks.**
| Priority order | Class name | Class label |
| -------------- | ------------------- | ----------- |
| 1 | Haze | 4 |
| 1 | Other contamination | 6 |
| 2 | Cloud shadow | 3 |
| 2 | Adjacent clouds | 5 |
| 3 | Suspect | 7 |
| 3 | Bright clouds | 2 |
While this prioritization scheme will attempt to preserve potentially useful pixel information (such as pixels detected as haze), the merging of cloud contaminated pixels from different sources can sometimes lead to transition artifacts in the final product artifacts. The transition between clear-sky and cloud contaminated pixels will be abrupt (for example, not seamless) as the cloud detected pixels are not to cross-contaminate the clear-sky domain. Similarly, there may be transition artifacts between different contaminated domains (such as bright cloud and haze) depending on which scenes have been prioritized within the contaminated domain.
The raster-based cloud mask and pixel traceability data for the Analysis-Ready PlanetScope Quality Assurance product ([Section 3.2](#32-quality-assurance-product-arps-qa)) is also generated at this step. In addition, non-raster metadata is gathered and embedded in the tiff header ([Table 5](#lpfw7cjfqo8i)) of the QA product artifacts. This will include pixel-level information on contributing PlanetScope scenes and their overlapping contribution footprints. Some of the satellite-specific scenes may have been flagged with "bad geometry" or "bad radiometry" during the harmonization steps, and if they end up contributing to the final tile image, it will be indicated in the embedded metadata (see [Table 5](#lpfw7cjfqo8i)). Scenes identified as "bad" will only be included if there is no "validated" scene data available to fill the tile. The fact that the final tile-based product artifacts may include "bad" scene data makes it critically important for the users to use the associated QA information to determine the quality and usefulness of the data and apply relevant masking before application.
Finally, it is worth noting that the final ARPS product artifacts will only be populated with data if there is at least some clear-sky (or haze) pixels present (for example, currently enforcing a minimum clear-sky/haze percentage of 5%). Haze contaminated pixels have been included in this condition as those pixels may have some useful surface recoverable information. For the largest tile grid ([Section 3.4](#34-delivery-projection-and-gridding)), a quadrant-level processing scheme (for example, each tile is divided into four equally-sized chunks) is adopted for optimization purposes. As the clear-sky percentage threshold is enforced at the quadrant-level, it is possible to have tiles with one or more quadrants completely filled with no data.
### 4.7. Backfill Versus Forward-Fill Operation
Analysis-Ready PlanetScope can be processed in either backfill or forward-fill mode. Backfill signifies a run over a time of interest in the past. ARPS data creation always starts by processing at least one year of historical data, even if a shorter backfill (or no backfill) has been requested. This is necessary to establish deep temporal image stacks to inform the cloud masking, calibration, and harmonization processes. Forward-fill jobs are executed subsequent to a backfill operation and typically run as close to present time as possible and typically on a daily basis, processing any new imagery that has become available since the last job execution utilizing information from the deep temporal stacks generated during the backfill for cloud masking, and calibration purposes. Currently a 48 hour latency of delivering ARPS data during daily[1](#user-content-fn-1) forward-fill operation is targeted, which is a function of the latency of the input sources (for example, primarily PlanetScope and MODIS/VIIRS) and processing time.
Various factors may cause differences in product quality between forward-fill and backfill operation. Forward-fill typically involves near real-time (NRT) data processing and the inherent latencies in satellite data and FORCE processing can cause S-2 and/or L8/9 scenes acquired close to the prediction date to not be available to inform the calibration process. While the multi-temporal calibration approach should continue to perform well based on FORCE data acquired in the past relative to the prediction date, the inclusion of the most current (relative to the prediction date) information will tend to be beneficial. The temporally driven cloud detection approach will also benefit from having data available both before and after the prediction date to most effectively detect anomalies attributable to cloud, cloud shadow, or haze contamination. In daily forward-fill, the anomaly detection is based mostly on backwards looking imagery (for example, only data from one day in the future of the prediction day will be available at most), which can increase the risk of commission or omission errors in the cloud mask. Finally, in forward-fill (or when running ARPS within 9 days of present day) NRT MODIS or VIIRS surface reflectance products will be used instead of the standard products ([Section 2](#2-analysis-ready-planetscope-inputs)). The NRT MODIS/VIIRS products rely on backwards looking data alone to inform the BRDF correction and may therefore be less representative of prediction date surface conditions. While a bias correction procedure has been implemented to remedy this potential issue, the generally lower quality NRT MODIS/VIIRS data may impact the quality of the MODIS/VIIRS-based surface reflectance harmonization ([Figure 5](#bu6ydmlsd1u3)), which in turn may impact the accuracy of the CESTEM-based radiometric harmonization.
## 5. Known Limitations and Caveats
* **False cloud/shadow detections** may occur in certain cases: 1) if surface conditions change very rapidly, 2) during prolonged cloudiness, or 3) over AOIs with complex terrain and shadowing. Significant effort has gone into developing automated techniques to differentiate between actual change and atmospheric contamination, but in some cases commission errors can still be an issue.
* **Analysis-Ready PlanetScope is not suited for studies over snow covered surfaces.** As it is virtually impossible to robustly distinguish between snow and clouds based on 4-band VNIR data, periodic snow cover will in most cases be masked out as clouds. Because the radiometric harmonization relies on clear-sky data, snowy regions may have reduced radiometric quality, or be completely unavailable if no clear-sky regions were identified.
* The Analysis-Ready PlanetScope processing focuses on getting surface reflectance values correct for ground pixels, not clouds. In most cases, clouds will have a natural appearance, but **occasional discoloration may occur over clouds** in the image. This effect is not known to be associated with any errors in radiometric harmonization over ground pixels.
* As the Analysis-Ready PlanetScope processing is done independently for each tile, **tile boundary artifacts** can sometimes occur within AOIs which cross tile boundaries. This may be manifested in the form of typically small inter-tile brightness differences and sub-pixel mis-alignments.
* Lastly, the notion of a perfect product is utopian. Remote sensing is hard. Cloud masking is a balancing act and an unwinnable battle between commission and omission errors. There WILL be cases where ARPS does not perform as well as we want it to. A lot of effort has gone into developing a differentiated next generation surface reflectance product with an ambition to be "best in class". We are committed to continuously improving it towards realizing the promise of high fidelity, timely, usable, and actionable insights from multi-source satellite observations.
## References
[]()
M. Claverie, J. Ju, J.G. Masek, J.L. Dungan, E.F. Vermote, J.-C. Roger, S.V. Skakun, C. Justice. 2018. The Harmonized Landsat and Sentinel-2 surface reflectance data set. Remote Sensing of Environment, 219, 145-161:
[]()
G. Doxani, E. Vermote, J.-C. Roger, F. Gascon, S. Adriaensen, D. Frantz, O. Hagolle, A. Hollstein, G. Kirches, F. Li, J. Louis, A. Mangin, N. Pahleva, B. Pflug, Q. Vanhellemont. 2018. Atmospheric Correction Inter-Comparison Exercise. Remote Sens., 10(2), 352:
[]()
G. Doxani, E.F. Vermote, J.-C. Roger, S. Skakun, F. Gascon, A. Collison, L. De Keukelaere, C. Desjardins, D. Frantz, O. Hagolle, M. Kim, J. Louis, F. Pacifici, B. Pflug, H. Poilvé, D. Ramon, R. Richter, F. Yin. 2023. Atmospheric Correction Inter-comparison eXercise, ACIX-II Land: An assessment of atmospheric correction processors for Landsat 8 and Sentinel-2 over land. Remote Sensing of Environment, 285, 113412.
[]()
ESA. 2024. The European Space Agency. Available online: (accessed on 12 May 2024)
[]()
D. Frantz. 2019a. FORCE—Landsat + Sentinel-2 Analysis Ready Data and Beyond. Remote Sensing, 11, 1124:
[]()
D. Frantz, M. Stellmes, P.A. Hostert. 2019b. Global MODIS Water Vapor Database for the Operational Atmospheric Correction of Historic and Recent Landsat Imagery. Remote Sens., 11, 257.
[]()
D. Frantz, E. Haß, A. Uhl, J. Stoffels, J. Hill. 2018. Improvement of the Fmask algorithm for Sentinel-2 images: Separating clouds from bright surfaces based on parallax effects. Remote Sens. Environ., 215, 471–481:
[]()
R. Houborg, M.F. McCabe. 2018a. Daily Retrieval of NDVI and LAI at 3 m Resolution via the Fusion of CubeSat, Landsat, and MODIS data. Remote Sensing, 10(6), 890:
[]()
R. Houborg, M.F. McCabe. 2018b. A Cubesat Enabled Spatio-Temporal Enhancement Method (CESTEM) utilizing Planet, Landsat and MODIS data. Remote Sensing of Environment, 209, 211-226:
[]()
M. Guizar-Sicairos, S.T. Thurman, J.R. Fienup. 2008. Efficient subpixel image registration algorithms. Optics Letters 33, 156-158:
[]()
J.W. Rouse, R.H. Hass, J.A. Shell, D. Deering. 1973. Monitoring vegetation systems in the Great Plains with ERTS-1. In: Third Earth Resources Technology Satellite Symposium. Washington DC, pp. 309–317
[]()
D.P. Roy, H.K. Zhang, J. Ju, J.L. Gomez-Dans, P.E. Lewis, C.B. Schaaf, Q. Sun, J. Li, H. Huang, V. Kovalskyy. 2016. A general method to normalize Landsat reflectance data to Nadir BRDF Adjusted Reflectance. Remote Sensing of Environment, Vol. 176, pp 255–271:
[]()
D.P. Roy, J. Li, H.K. Zhang, L. Yan, H. Huang, Z. Li. 2017. Examination of Sentinel-2A multi-spectral instrument (MSI) reflectance anisotropy and the suitability of a general method to normalize MSI reflectance to nadir BRDF adjusted reflectance. Remote Sensing of Environment, Vol. 199, pp 25-38:
[]()
D.P. Roy, H. Huan, R. Houborg, V.S. Martins. 2021. A global analysis of the temporal availability of PlanetScope high spatial resolution multi-spectral imagery. Remote Sensing of Environment, Vol. 264, 112586:
[]()
C.B. Schaaf, F. Gao, A.H. Strahler, W. Lucht, X. Li, T. Tsang, N.C. Strugnell, X. Zhang, Y. Jin, J.-P. Muller et al. 2002. First operational BRDF, albedo nadir reflectance products from MODIS. Remote Sens. Environ., 83, 135–148:
[]()
D. Tanré, C. Deroo, P. Duhaut, M. Herman, J.J. Morcrette, J. Perbos, P.Y. Deschamps. 1990. Description of a Computer Code to Simulate the Satellite Signal in the Solar Spectrum: The 5S Code. Int. J. Remote Sens., 11, 659–668:
[]()
Z. Zhu, C.E. Woodcock. 2012. Object-Based Cloud and Cloud Shadow Detection in Landsat Imagery. Remote Sens. Environ., 118, 83–94:
[]()
Planet Team, 2023. Planet L1 Data Quality Q4 2023 Report. Status of Calibration and Data Quality for the PlanetScope Constellation, December 2023, Available online at . Last Accessed: May 13, 2024
[]()
S.A. Soenen, D. R. Peddle and C. A. Coburn. 2005. SCS+C: a modified Sun-canopy-sensor topographic correction in forested terrain. *IEEE Transactions on Geoscience and Remote Sensing*, vol. 43, no. 9, pp. 2148-2159:
[]()
P.M. Teillet, B. Guindon, D.G. Goodenough. 1982. On the slope-aspect correction of multispectral scanner data. Canadian Journal of Remote Sensing, 8 (2), pp. 82-106.
## Footnotes
1. While ARPS processing runs daily in forward-fill operation, data will only be delivered for a given day if at least some clear-sky pixels are present. [↩](#user-content-fnref-1)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/mosaics/)
# Mosaics
## About Mosaics
Mosaics are analysis-ready data products created by mosaicking the best imagery over a time period. Planet offers a range of mosaic products, including [Visual Mosaics](#visual-mosaics) and [Normalized Surface Reflectance Mosaics](#normalized-surface-reflectance-mosaics), all designed for visual and/or analytical use.
Mosaics are generated by querying scenes that overlap a specific area of interest within a designated time frame. These scenes are then ranked based on quality metrics metadata, such as the presence of clouds and haze, with the highest-quality scenes placed at the top. Using a "best-on-top" algorithm, the highest quality scenes are efficiently composited to create the final mosaic.
## Global Mosaics
Global Mosaics are generated between 74° North and 60° South to minimize distortion at the poles, using PlanetScope and/or [RapidEye](https://docs.planet.com/data/imagery/rapideye.md) imagery. These mosaics are color-corrected and designed for both human viewing and computer vision analytics. The Global Mosaic product is the Q3 Quarterly Visual Mosaic, with distinct pricing due to its global nature. While all mosaic products can be generated globally, this version is created explicitly at a set interval to ensure a consistent global visual product. The Global Mosaic is typically utilized in background GIS applications, or as a visual background.
 *Planet Global Mosaic Q3 2023*
## Mosaics
Mosaics are generated at weekly, monthly, and quarterly intervals, tailored to customer-specified areas of interest. These mosaics are categorized into two product types: Visual and Normalized Surface Reflectance.
#### Visual Mosaics
**Visual** Mosaics are optimized to minimize the effects of cloud cover, haze, and topographic variations. These mosaics are color-corrected and designed for human viewing and computer vision analytics, enabling users to monitor landscape and infrastructure changes over time and space.
| Source imagery | Download bands | Streaming bands | Monitoring frequency | Zoom level | Color target |
| ------------------------------------------------- | -------------- | --------------- | ---------------------------------- | ---------- | ------------ |
| PlanetScope and/or
RapidEye\* Visual Product | RGB | RGB | Weekly
Monthly
Quarterly | 15 | MODIS |
*\*RapidEye Imagery is used in Global Mosaics for dates before to February, 2020.*
#### Normalized Surface Reflectance Mosaics
**Normalized Surface Reflectance Mosaics** are created using the Ortho Analytic Surface Reflectance imagery asset type ([ortho\_analytic\_4b\_sr/ortho\_analytic\_8b\_sr](https://docs.planet.com/data/imagery/planetscope/psscene.md)). These mosaics are optimized to reduce the variability due to atmospheric effects, enabling users to perform spectral, quantitative, and time series analyses.
Normalized Surface Reflectance Mosaics undergo additional processing steps to improve spatial and temporal consistency, making them less likely to have seamlines. The normalization process involves matching the mosaics to a common reference target. The targets are multi-year monthly composite mosaics, derived using Sentinel-2 imagery, with the goal of enhancing the spatial and temporal consistency of the mosaics, enabling time-series analyses. Nonetheless, the normalization process can result in less accurate absolute spectral values. These mosaics are ideal for use cases where spatial consistency is prioritized or for generating training data for machine learning algorithms. They are particularly suited for longer time periods (for example, monthly, quarterly) where multiple scenes are mosaicked together, and additional image processing is beneficial. Applications include land cover classification, forest disease monitoring, and flood risk analysis.
#### Mosaics - Normalized Surface Reflectance source imagery
| Source imagery | Download bands | Streaming bands | Monitoring frequency | Zoom level | Color target |
| -------------------------------------- | --------------------------- | --------------- | ---------------------------------- | ---------- | ------------ |
| PlanetScope Surface
Reflectance | BGRN | RGB, CIR | Weekly
Monthly
Quarterly | 15 | Sentinel-2 |
| PlanetScope 8-Band Surface Reflectance | CB,B,G,GII,Y,R,
RE,NIR | RGB, CIR | Weekly
Monthly
Quarterly | 15 | Sentinel-2 |
#### SuperRes Mosaics
Visual Mosaics are optimized to minimize the effects of cloud cover, haze, and topographic variations. These mosaics are color-corrected and designed for human viewing and computer vision analytics, enabling users to monitor landscape and infrastructure changes over time and space.
| Source Imagery | Download Bands | Streaming Bands | Frequency | Zoom Level |
| -------------------------------------------------------------------------------------------------------- | -------------- | --------------- | ------------------------------------------------ | ---------- |
| visual ortho\_analytic\_4b top of atmosphere reflectance and surface reflectance ortho\_analytic\_4b\_sr | RGB | RGB | Weekly
Biweekly
Monthly
Quarterly | 15 |
\**SuperRes Mosaics general specifications*
SuperRes Mosaics are created using the visual ortho\_analytic\_4b top of atmosphere reflectance imagery asset and the surface reflectance `ortho_analytic_4b_sr`. These mosaics are optimized to visually enhance human and machine perception of PlanetScope imagery. SuperRes Mosaics leverage our foundational model built on the Enhanced Super-Resolution Generative Adversarial Network (ESRGAN) with a collection of 120,000 pairs of SkySat and PlanetScope imagery with a perceptual loss training technique to produce imagery that looks natural and remains faithful to the ground truth. We include a confidence layer to help assess the degree of accuracy of the generated pixel by evaluating various sources of error. Learn more about our [SuperRes model’s specification and performance](https://docs.planet.com/data/imagery/superres/) on the product page.
#### Mosaics - Normalized Surface Reflectance Product Details
| Type | Prioritizes | Data | Pixel values | Normalization |
| -------------------- | --------------------------------------------- | -------------- | ---------------------------- | ------------- |
| Normalized SR | Spatial & temporal consistency; training data | 4-band, 16-bit | Modified Surface Reflectance | Sentinel-2 |
| 8-Band Normalized SR | Spatial & temporal consistency; training data | 8-Band, 16-bit | Modified Surface Reflectance | Sentinel-2 |
#### Mosaics - availability
| Type | Available after | UDM2 | Pixel provenance |
| -------------------- | --------------- | ----------------- | ---------------- |
| Visual | January 2016 | Mixed | Yes |
| Normalized SR | May 2016 | After August 2018 | Yes |
| 8-Band Normalized SR | August 2020 | Yes | Yes |
## Product Specifications
#### Mosaic quads
Mosaics use the Web Mercator projection, the standard for web mapping applications, due to its efficiency in handling large geospatial datasets. This projection supports a tile-based system, dividing the world into uniform square tiles at multiple zoom levels. This allows for pre-rendered and cached tiles for fast map loading and smooth user interactions in GIS applications. Mosaics are distributed as a grid of GeoTIFF files, which are called *quads*—the size of each quad is 4096 x 4096 pixels.
 *Web Mercator Tiling Grid with Monthly Visual Mosaic of Jamaica, April, 2024*
| Attribute | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Imagery | PlanetScope and RapidEye (Visual)
PlanetScope (Surface Reflectance) |
| Pixel Size\* | 4.77 m at the Equator for zoom level 15 (PlanetScope and RapidEye) |
| Image Bit Depth | 8-bit (Visual)
16-bit (Surface Reflectance) |
| Bands | Red, Green, Blue, Alpha (Visual)
Blue, Green, Red, NIR, Alpha (Surface Reflectance)
Coastal Blue, Blue, Green I, Green II, Yellow, Red, Red Edge, NIR, Alpha (8 band) |
| Projection | WGS84 Web Mercator (EPSG:3857) |
| Size | 4096 x 4096 pixels |
| Processing | Orthorectification
Atmospheric correction (Surface Reflectance only)
May be radiometrically balanced
Seamlines may be minimized with tonal balancing
|
*\*The pixel size in meters can be estimated as follows: 4.77 \* cos(latitude) m (4.77 m at the Equator) for zoom level 15 (PlanetScope and RapidEye)*.
#### Product naming
The name of each mosaic quad represents the x and y position of the quad within the two-dimensional grid which makes up the mosaic. For example, `{X}-{Y}`, where X and Y are the x and y position of the quad in the grid.
Example: `439-1220`
Upon download, the name of the downloaded quad also contains the Zoom Level.
Example: `L15-0439E-1220N.tif`
#### Publication
Planet aims to publish all Mosaics 7 days after the end of the acquisition period. However, there may be instances where publishing may take longer. Publishing times for custom mosaics are determined on a case-by-case basis.
#### Cadence
Mosaics are generated at a specified cadence based on the `first_acquired` and `last_acquired` UTC timestamps for underlying source imagery.
| Cadence | Start (`first_acquired`) | End (`last_acquired`) |
| --------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Weekly | Mondays at 00:00:00 UTC | Sundays at 23:59:59 UTC |
| Monthly | The first day of each month at 00:00:00 UTC | The last day of each month at 23:59:59 UTC |
| Quarterly | January 1st, April 1st, July 1st, and October 1st at 00:00:00 UTC | March 31st, June 30th, September 30th, and December 31st at 23:59:59 UTC |
## Mosaics Delivery
Mosaics can be downloaded or streamed through multiple methods. Below are some of the available options.
### Planet Insights Platform
[Planet Insights Platform](https://insights.planet.com/data/mosaics) can be used to view and download mosaic quads. A complete tutorial on how to use the Planet Insights Platform to access Mosaics is available in this [introductory course](https://university.planet.com/introduction-to-planet-basemaps) from Planet University.
### QGIS/ArcGIS Pro plugins
Mosaics can be downloaded or streamed through the Planet [QGIS](https://docs.planet.com/platform/integrations/qgis/planet-qgis-plugin.md#explore-basemaps) or [ArcGIS Pro](https://docs.planet.com/platform/integrations/arcgis/planet-add-in-for-arcgis-pro.md#explore-basemaps) plugins. These plugins enable users to search for mosaics within the catalog and offer multiple filtering options, such as filtering by area of interest or by different types of mosaics.
### Orders API
Mosaics can also be accessed through the Orders API, which allows users to reproject the data to a coordinate system other than Web Mercator, clip mosaics to a specified extent, merge multiple quads, perform band math calculations, and deliver the data to a cloud service provider. However, there are limitations to consider. Users can merge and download up to 25 quads at once. If the merge tool is not used, the limit is 500 quads per order, meaning the provided geometry must encompass fewer than 500 quads. For downloading areas larger than 500 quads, it is recommended to use the Basemaps API.
For more detailed information, see [the Mosaics documentation](https://docs.planet.com/develop/apis/orders/sources.md#mosaics-source-type).
### Basemaps API
The Basemaps API is recommended for users seeking endpoints for scalable workflows, direct access to Cloud Optimized GeoTIFF links, and the ability to stream mosaics into web applications. Often, users combine the capabilities of both APIs (Orders and Basemaps) when writing their own libraries to access mosaics. The detailed API reference can be found [here](https://docs.planet.com/develop/apis/basemaps/reference.md).
Some use cases of the Basemaps API are:
* Find the quads that intersect an Area of Interest and download those quads.
* Get the list of items that contribute to the particular quad.
* Stream into web applications using the XYZ and WMTS protocols.
* Get a list of series and mosaics available for a user.
### Tile Services
Planet's Mosaic WMTS and XYZ tile services provide programmatic streaming access to Mosaics including full bit depth data.
### Quad Packaging
Mosaic quads can be downloaded through the Basemaps API and Orders API along with their associated metadata (JSON), [UDM2](https://docs.planet.com/data/imagery/udm.md) assets, and pixel provenance raster and vector files, which trace all scenes used when producing the quads. The table below shows the list of files returned when downloading a single quad, and their associated files, for a Normalized SR Mosaic.
| File name | Size |
| -------------------------------- | ------ |
| 484-1310\_quad.tif | 117 MB |
| 484-1310\_provenance\_raster.tif | 236 KB |
| 484-1310\_ortho\_udm2.tif | 1.2 MB |
| 484-1310\_provenance\_vector.zip | 22 KB |
| L15-0484E-1310N.dbf | 788 B |
| L15-0484E-1310N.prj | 425 B |
| L15-0484E-1310N.shp | 66 KB |
| L15-0484E-1310N.shx | 124 B |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/mosaics/sandbox/)
# Planet Mosaics Sandbox Data
This Planet Sandbox Data collection for Planet Mosaics provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| --------------------------------------- | -------------------------------------------- | ----------------------------------------- | ----------------------- |
| ps\_s2\_normalized\_sr\_monthly\_mosaic | Planet Sandbox Data - Planet Monthly Mosaics | BYOC-c48c018f-67a1-4827-a1e4-f3ab98690312 | 2021-01-01 - 2023-04-01 |
## Planet Sandbox Data Areas
This collection includes 9 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 9 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ----------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Cusco, Province of Chumbivilcas, Peru | 3211 | 2021-01-01 – 2023-04-01 | -14.52, -71.81 |
| Iowa, United States | 28229 | 2021-01-01 – 2023-04-01 | 41.11, -93.78 |
| Mato Grosso, Central-West Region, Brazil | 1445 | 2021-01-01 – 2023-04-01 | -13.07, -56.60 |
| Pará, North Region, Brazil | 27021 | 2021-01-01 – 2023-04-01 | -6.66, -52.29 |
| Nouvelle-Aquitaine, Metropolitan France, France | 19181 | 2021-01-01 – 2023-04-01 | 44.65, -0.44 |
| Svalbard, Norway | 97 | 2021-03-01 – 2023-04-01 | 78.17, 15.56 |
| Dodoma Region, Central Zone, Tanzania | 2255 | 2021-01-01 – 2023-04-01 | -6.32, 36.83 |
| Al Qalyubiya, Egypt | 13962 | 2021-01-01 – 2023-04-01 | 30.22, 31.20 |
| Western Australia, Australia | 29827 | 2021-01-01 – 2023-04-01 | -31.72, 116.54 |
[Download GeoJSON](https://docs.planet.com/data/imagery/mosaics/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=9\&lat=-6.7652\&lng=-52.3763\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
São Félix do Xingu, Brazil
2021-01-01 to 2023-04-01
27021km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=9\&lat=-6.7652\&lng=-52.3763\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=9\&lat=44.7345\&lng=-0.676\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
Bordeaux, France
2021-01-01 to 2023-04-01
19181km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=9\&lat=44.7345\&lng=-0.676\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=9\&lat=-31.702\&lng=116.524\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
Perth, Australia
2021-01-01 to 2023-04-01
29827km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=9\&lat=-31.702\&lng=116.524\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F64e8174f-7d03-4863-ba70-5139e325a75d\&datasetId=c48c018f-67a1-4827-a1e4-f3ab98690312\&fromTime=2023-04-01T00%3A00%3A00.000Z\&toTime=2023-04-01T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D=%22MAPZEN%22)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/mosaics/surfacereflectance/)
# Surface Reflectance Mosaics
Mosaics are generated by querying scenes that overlap a specific area of interest within a designated time frame. These scenes are then ranked based on quality metrics metadata, such as the presence of clouds and haze, with the highest quality scenes placed at the top. Using a best-on-top algorithm, the highest quality scenes are efficiently composited to create the final mosaic.
**Normalized Surface Reflectance Mosaics** (Zoom Level 15 – 4.77 meter cell size at the equator) are created using the Ortho Analytic Surface Reflectance imagery asset type ([ortho\_analytic\_4b\_sr/ortho\_analytic\_8b\_sr](https://docs.planet.com/data/imagery/planetscope/psscene.md) ). These mosaics are optimized to reduce the variability due to atmospheric effects, enabling users to perform spectral, quantitative, and time series analyses.
For more details, see the [Mosaics Webpage](https://docs.planet.com/data/imagery/mosaics.md) and the [Mosaic Product Technical Specification](https://assets.planet.com/products/basemap/planet-basemaps-product-specifications.pdf) document.
### Normalized Surface Reflectance Mosaics Product Details
| Source imagery | Download bands | Streaming bands | Monitoring frequency | Zoom level | Color target |
| -------------------------------------------------- | -------------- | --------------- | ---------------------------------- | ---------- | ------------------------------------- |
| PlanetScope Surface Reflectance
`analytic_sr` | BGRN | RBG, CIR | Weekly
Monthly
Quarterly | 15 | Sentinel-2
None (non-normalized) |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/mosaics/techspec/)
# Technical Specification
### Download the PDF
[Download PlanetScope Mosaics Imagery Product Specification →](https://planet.widen.net/view/pdf/gbkcexll3p/Planet-UserDocumentation-MosaicsProductSpecification.pdf)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/mosaics/visual/)
# Visual Mosaics
PlanetScope Mosaics are generated by querying PlanetScope scenes that overlap a specific area of interest within a designated time frame. These scenes are then ranked based on quality metrics metadata, such as the presence of clouds and haze, with the highest quality scenes placed at the top. Using a best-on-top algorithm, the highest quality scenes are efficiently composited to create the final mosaic.
**PlanetScope Visual Mosaics** (Zoom Level 15 – 4.77 meter cell size at the equator) are optimized to minimize the effects of cloud cover, haze, and topographic variations. These mosaics are generated using the [visual](https://docs.planet.com/data/imagery/planetscope/psscene.md) asset type, and are color-corrected and designed for human viewing and computer vision analytics, enabling users to monitor landscape and infrastructure changes over time and space.
**SkySat Visual Mosaics** (Zoom Level 18 – 0.596 meter cell size at the equator) can be generated post SkySat tasking over a custom area and time of interest. SkySat Visual Mosaics are generated using [ortho\_visual](https://docs.planet.com/data/imagery/skysat/item-types/skysatcollect.md) asset type. In addition, SkySat Visual Mosaics may be purchased as an add-on to our Flexible Tasking product.
For more details, see the [Mosaics Webpage](https://docs.planet.com/data/imagery/mosaics.md) and the [Mosaic Product Technical Specification](https://assets.planet.com/products/basemap/planet-basemaps-product-specifications.pdf) document.
### Visual Mosaics Product Details
| Source imagery | Download bands | Streaming bands | Monitoring frequency | Zoom level | Color target |
| --------------------------------------------------------------------- | -------------- | --------------- | ---------------------------------------------- | ---------- | ------------------------------------------------------------ |
| PlanetScope and/or
RapidEye\* Visual Product
`visual` asset | RGB | RGB | Weekly
Monthly
Quarterly | 15 | MODIS |
| SkySat Visual Product
`ortho_visual` asset | RGB | RGB | Weekly
Monthly
Quarterly
Custom | 18 | PlanetScope (normalized to MODIS)
None (non-normalized) |
*\*RapidEye Imagery is used in Global Mosaics for dates prior to February 2020.*
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/pelican/)
# Pelican Overview
## Constellation & Sensor Overview
Pelican, operated by Planet, is a next-generation high-resolution constellation designed to support rapid tasking, improved image quality, and low-latency delivery. Pelican produces multispectral and panchromatic imagery and is sampled at **50 centimeters per pixel** when orthorectified.
The Pelican satellite constellation consists of multiple launches of Generation-1 Pelican spacecraft, beginning commercial operations in 2025. Each satellite is **3-axis stabilized** and highly agile, capable of slewing rapidly between targets of interest. Pelican satellites include an electric propulsion unit for orbital control, along with **four reaction wheels and three magnetic torquers** for attitude control. Generation-2 spacecraft are anticipated to begin operations in 2026.
Pelican supports multiple collection modes including point, line, area, and developing stereo capabilities. Pelican captures imagery as continuous strips that are segmented into framed Scenes. Pelican Gen-1 collects an **8 km swath** at nadir.
Pelican Gen-1 satellites contain high-performance **Cassegrain telescopes** with an effective focal length of **4.03 meters**, paired with a line-scan detector system consisting of **dual panchromatic sensor arrays (12,288 pixels)** and **six multispectral bands (6,144 pixels)**. The panchromatic sensors are diagonally offset by half a pixel, enabling oversampling used in advanced processing and pansharpening. Pelican collects imagery in 6 multispectral bands alongside the panchromatic channel.
Pelican imagery is captured using **Time Delay Integration (TDI)**, enabling high SNR at high resolution. The multispectral pixels have a larger native sample distance, while the panchromatic band provides finer detail for pansharpened and visual products. Pelican collects frame imagery in all tasking modes and is engineered for fast downlink and rapid product availability.
### Pelican Spectral Bands
Pelican satellites have two spectral band configurations: **Pelican-2** and **Generation-1 Pelican (Pelican-3 through Pelican-10)**. The table below presents both sets of bands side-by-side for easy comparison. Pelican Generation 2 satellites will have the same band configurations as Generation 1.
| **Band** | **Pelican-2 (nm)** | **Gen-1 and Gen-2 Pelicans (nm)
(Pelican-3+)** |
| ------------------- | ------------------ | --------------------------------------------------- |
| **Panchromatic** | 450 – 800 | 450 – 800 |
| **Blue** | 450 – 520 | 465 – 518 |
| **Green** | 520 – 590 | 547 – 585 |
| **Red** | 630 – 690 | 650 – 682 |
| **Red Edge / RE-I** | 693 – 715 | 699 – 716 |
| **Red Edge II** | 729 – 751 | — |
| **NIR** | 770 – 890 | — |
| **NIR Wide** | — | 779 – 885 |
| **NIR Narrow** | — | 846 – 887 |
## Pelican Imagery Products
Pelican products are available for search and download via the Planet APIs, User Interfaces, and integrations. Pelican imagery is delivered in the form of **Scene products**, which are encoded in the Planet Platform as a set of Item Types and Asset Types. All Pelican imagery is collected as continuous strips using a line-scan sensor and then segmented into framed Scenes for processing and delivery.
Pelican supports **multiple radiometric and geometric processing levels**, including Level 1A (minimally processed panchromatic), Level 1B Basic (radiometrically and sensor-corrected), and Level 3B Ortho (fully orthorectified radiance, surface reflectance, pansharpened, and visual products). These products are interoperable with Planet’s high-resolution SkySat offerings while improving upon image quality, artifact reduction, and delivery speed.
### Item Types
A **Pelican Scene Product** is an individual framed segment extracted from a Pelican imaging strip. Each strip is captured with a dual-panchromatic + multispectral line-scan system and then divided into Scenes for processing. Pelican Scenes typically cover an **8 km swath width** and vary in length depending on the tasking mode and imaging geometry.
Pelican Scenes are represented in the Planet Platform as the `PelicanScene` item type. Each Scene includes:
* Panchromatic and multispectral imagery
* Geometry footprint and acquisition metadata
* UDM2 (Usable Data Mask) for cloud, haze, shadow, snow/ice, and unusable pixels
* RPC files for Basic products
* Projection and radiometric metadata for Ortho products
Pelican does **not** include a Collect product type, equivalent to SkySatCollect, as PelicanScenes do not require scene to scene mosaic as SkySatScenes do.
### Imagery Asset Types
Pelican Scene products are available for download in the form of imagery assets. Multiple asset types are made available for Pelican Scenes, each with differences in radiometric processing, geometric correction, and spectral content. Asset type availability varies by processing level.
**Basic L1A Panchromatic** (`basic_l1a_panchromatic`) assets are minimally processed, non-orthorectified panchromatic imagery products. These products include raw-mapped detector values with accompanying calibration coefficients and are designed for advanced users requiring earliest access or custom radiometric workflows.
**Basic Panchromatic** (`basic_panchromatic`) assets are non-orthorectified, calibrated panchromatic imagery products. They include Time Delay Integration (TDI) corrections and are transformed to scaled Top of Atmosphere Radiance. These products are designed for data science and analytic workflows that benefit from Pelican’s wide (450–800 nm) panchromatic band and include associated rational polynomial coefficients (RPCs) for user-driven orthorectification.
**Basic Analytic** (`basic_analytic`) assets are non-orthorectified, calibrated multispectral imagery products. They contain Pelican’s six spectral bands at native multispectral resolution and are transformed to scaled Top of Atmosphere Radiance. These products are intended for analytic applications requiring spectral fidelity and for users who wish to geometrically correct the imagery themselves using RPCs.
**Ortho Panchromatic** (`ortho_panchromatic`) assets are orthorectified, calibrated panchromatic imagery products resampled to a uniform 50 cm pixel size. These products provide high-resolution detail suitable for geospatial analysis, mapping, and applications requiring accurate cartographic projection.
**Ortho Analytic** (`ortho_analytic`) assets are orthorectified, calibrated 6-band multispectral imagery products transformed to Top of Atmosphere Radiance and delivered at a 1 m pixel size. They are intended for workflows requiring accurate geolocation and multispectral analysis.
**Ortho Analytic Surface Reflectance** (`ortho_analytic_sr`) assets are orthorectified 6-band multispectral imagery corrected for the effects of the Earth’s atmosphere, accounting for the molecular composition and variation with altitude along with aerosol content. Combining the use of standard atmospheric models with the use of MODIS or VIIRS for water vapor, ozone and aerosol data, this provides reliable and consistent surface reflectance scenes over Planet’s varied constellation of satellites as part of our normal, on-demand data pipeline.
**Ortho Pansharpened** (`ortho_pansharpened`) assets are orthorectified 6-band multispectral imagery sharpened using Pelican’s oversampled dual-panchromatic channels to achieve 50 cm resolution. These products are designed for multispectral applications requiring the highest available spatial detail combined with spectral richness.
**Ortho Visual** (`ortho_visual`) assets are orthorectified, color-corrected RGB imagery optimized for visualization. Lower-resolution multispectral bands are pansharpened to 50 cm using Pelican’s dual-panchromatic imagery. These products are intended for direct visual inspection and easy ingestion into GIS platforms.
**UDM2** (`*_udm2`) assets are Usable Data Masks accompanying both Basic and Ortho products. UDM2 identifies clear, cloud, haze, shadow, snow/ice, confidence, and unusable pixels, enabling users to filter or mask portions of the Scene.
Pelican’s full product specifications can be found in the [Pelican User Documentation](https://planet.widen.net/s/kbt9m6p6sx/planet-userdocumentation-pelicanproductspec).
## Product Naming
Pelican image products follow two naming conventions depending on whether the file is a **full Scene** or a **trimmed deliverable** produced as part of task fulfillment. Both conventions provide globally unique identifiers for acquisition time, satellite, and asset type.
### Full Scene Image Filename Convention
Full Pelican Scene products use the following naming pattern:
```
___.
```
Examples:
```
20250305_143613_03_3009_Analytic.tif
20250305_143613_03_3009_Visual.tif
```
This convention applies to all complete Pelican Scenes generated directly from the imaging strip before trimming or task‑specific processing.
### Trimmed Imagery Folder Naming Convention
Trimmed assets, delivered for task fulfillment, include an additional **unique capture identifier** in the folder name:
```
___
```
Example:
```
20250305_143613_03_3009_3a44e78a-de6d-4d4b-b199-8f142deb10dd
```
## Processing
Several processing steps are applied to Pelican imagery to produce the complete set of Pelican Scene products available for download.
### Sensor & Radiometric Calibration
### *Sensor*
**Darkfield/Offset Correction**: Corrects for sensor bias and dark noise. On-orbit calibration collects are captured with the same operational settings during eclipse to yield faithful representative darkfield images. Darkfield images are updated periodically for all bands.
**Flat Field Correction:** Flat fields are created from on-orbit imagery taken post-launch. These fields are used to correct sensor non-uniformities. Flat field images are updated periodically for all bands.
**Band Co‑Registration**: Aligns Pelican’s dual panchromatic channels and six multispectral bands using an improved geometric model, ensuring pixel‑accurate spectral alignment across the stack.
### *Radiometric*
**Absolute Radiometric Calibration**: Converts detector digital number (DN) measurements into physical radiance units (W/(m²·sr·µm)) using calibration coefficients derived from laboratory and on‑orbit calibration.
**Atmospheric Correction**: Surface reflectance is determined from Top of Atmosphere (TOA) reflectance, calculated using coefficients supplied with the Planet Radiance product. The Planet Surface Reflectance product corrects for the effects of the Earth's atmosphere, accounting for the molecular composition and variation with altitude along with aerosol content. Combining the use of standard atmospheric models with the use of satellite water vapor, ozone and aerosol data, this provides reliable and consistent surface reflectance scenes over Planet's varied constellations of satellites as part of our normal, on-demand data pipeline. However, there are some limitations to the corrections performed:
* In some instances, there is no satellite data overlapping a Planet scene or the area nearby. In those cases, AOD is set to a value of 0.226 which corresponds to a “clear sky” visibility of 23 km, the aot\_quality is set to the satellite “no data” value of 127, and aot\_status is set to ‘Missing Data - Using Default AOT’. If there is no overlapping water vapor or ozone data, the correction falls back to a predefined 6SV internal model.
* The effects of haze and thin cirrus clouds are not corrected for.
* Aerosol type is limited to a single, global model.
* All scenes are assumed to be at sea level, and the surfaces are assumed to exhibit Lambertian scattering - no BRDF effects are accounted for.
* Stray light and adjacency effects are not corrected for.
### *Visual*
### Visual Product Processing
Pelican Visual products present imagery as natural color, optimized for human interpretation. Processing includes:
1. **Color Curve Application**: A custom color profile is applied to enhance visual clarity and alignment with natural appearance.
2. **Pansharpening**: Lower‑resolution multispectral bands are fused with Pelican's dual‑panchromatic channels to produce a 50 cm RGB product.
3. **Post‑Processing Enhancements**: Final tuning steps to ensure consistent tone and contrast across the continuous sequence of images captured by the satellite during a single pass over an area. We do not guarantee visual consistency between non-continuous sequences of images, nor across independent passes over an area.
### Geometric Processing
Pelican imagery undergoes a multistep georectification process to ensure positional and geometric accuracy meets Planet’s quality standards. This process transforms the raw satellite imagery into a map-ready product. Planet image products are offered with different levels of processing to correct for sensor and geometric distortions which include the following product levels:
* **Basic Products:** These are sensor-corrected and geometrically aligned. Basic products are georeferenced to improve positional accuracy beyond what telemetry alone provides, but they are not orthorectified or corrected for terrain distortions.
* **Ortho Products:** In addition to the corrections applied to Basic products, Ortho products account for terrain distortion. Imagery is orthorectified and projected onto a 50 cm grid using a digital elevation model (DEM) to accurately model local terrain. Ortho products utilize the UTM WGS84 map projection
#### Geometric Processing Workflow
Both Basic and Ortho products are generated from a rigorous sensor model refined through these steps:
1. **Initial Pointing Estimate:** Satellite telemetry provides the initial pointing estimate (typically 75–100 m accuracy). Corrections for boresight and optical distortion are applied within a physical camera model.
2. **Refined Pointing with Global Reference:** Ground control tie points from the panchromatic band are matched against global reference imagery. This refines the satellite attitude and corrects low‑frequency satellite motions.
3. **Band Alignment and Fine Refinement:** The remaining panchromatic and multispectral bands are rectified to the initial panchromatic band. This spatially aligns the bands and further refines the camera's attitude, removing higher-frequency satellite motions.
After refinement, the updated physical camera model is used to generate final outputs:
* **Basic Products:** Bands are aligned within the image plane. **Rational Polynomial Coefficients (RPCs)** are included for users who want to perform their own orthorectification. RPCs approximate the full camera model but may not be continuous across adjacent tiles.
* **Ortho Scene Products:** Imagery is projected and resampled onto a fixed 50 cm grid using the refined camera model and a reference DEM.
#### Geometric Processing Accuracy
The positional accuracy of Planet imagery is contingent upon the efficacy of our multi-step georectification process. Variations in image characteristics and the availability of geodetic control influence the final geospatial accuracy.
**Positional Accuracy in the Absence of Ground Control**
Imagery acquired under conditions that preclude the extraction of sufficient ground control tie points (GCPs) will exhibit increased positional uncertainty. In such cases, the rigorous physical camera model will necessarily revert to parameter estimations derived predominantly from the initial satellite telemetry data. This results in a nominal absolute geospatial accuracy of 75 to 100 meters circular error 90% (CE90). Conditions contributing to this scenario include, but are not limited to:
* **Significant cloud obscuration:** Extensive cloud cover prevents line-of-sight to ground features essential for GCP extraction.
* **Dominant water bodies:** Large water features within a scene lack stable, distinct, and identifiable georeferencing points.
* **Dynamic or homogenous terrain:** Regions undergoing rapid geomorphological change, or those characterized by uniform, featureless surfaces (for example, snow-covered expanses), impede reliable GCP generation.
* Imagery relying solely on telemetry-derived positional estimates can be identified in the product metadata where the "Ground Control" field will be explicitly set to "FALSE".
**Influence of Reference Data Fidelity**
The absolute geospatial accuracy of Planet's derived image products is directly impacted by the inherent accuracy of the global reference imagery datasets utilized in our georectification pipeline.
Specific details regarding the absolute accuracy of the reference data are systematically reported in Planet's quarterly Image Quality Reports (IQRs). For example, during Q1 through Q2, Planet's primary reference imagery demonstrated an absolute accuracy of 5 meters CE90 across the majority of locations characterized by terrain slopes less than 20 degrees. This CE90 metric signifies that 90% of the measured horizontal errors are expected to be within a 5-meter radius of the true ground position.
Users may observe a localized degradation in absolute positional accuracy in geographic regions exhibiting:
* **Rapid Urban Development or Significant New Construction:** Recent anthropogenic modifications may not be fully represented in the current reference data.
* **Pronounced Topographical Changes:** Areas with dynamic geomorphic processes (for example, landslides, erosion) can lead to discrepancies.
* **High Terrain Slopes:** Steep slopes inherently introduce greater geometric distortion and can challenge precise orthorectification, potentially reducing positional accuracy even with an accurate digital elevation model (DEM).
Planet updates **reference data** to mitigate these factors and maintain optimal geospatial processing fidelity. The current DEM and reference imagery accuracy used for orthorectification is detailed in the relevant Image Quality Reports.
## Miscellaneous
**Rational Polynomial Coefficients (RPCS)**
For Pelican Basic Imagery, Planet supplies Rational Polynomial Coefficients (RPCs) similar to SkySat and PlanetScope. RPCs provide a mathematical relationship that maps the 3D ground coordinates (latitude, longitude, elevation) to 2D image coordinates (row, column pixels) and vice-versa. This is essential for accurately geolocating features within an image and for removing geometric distortions caused by sensor geometry, terrain variations, and satellite attitude during image acquisition.
RPCs are ratios of polynomials that approximate a physical sensor model. They consist of a set of coefficients (numerators and denominators) for both forward (ground to image) and inverse (image to ground) transformations. These coefficients are derived as part of the Geometric processing.
The RPCs are an approximation to a rigorous physical sensor model that Planet uses to generate Pelican Orthorectified image products. As such, users who use RPCs may find that their generated ortho image does not match Planet’s orthorectified imagery exactly. Currently, the RPCs are generated for individual tiles and discontinuities in the solution may occur at tile boundaries.
RPCs are supplied with Basic products and designed for users with advanced image processing and geometric correction capabilities. Basic products are not orthorectified or corrected for terrain distortions by Planet. With accompanying RPC files users can perform these corrections themselves using standard GIS tools. Users will need an elevation model (for example, a Digital Elevation Model) to correctly orthorectify this product. For Pelican, the RPC files are supplied as text (.TXT) files. The following table describes the RPC file format. The RPCs are also available in the Tiff header for the Basic product.
**Pelican NITF 2.1 Image Product**
Planet can produce imagery in the National Imagery Transmission Format (NITF 2.1) compliant with MIL-STD-2500C and guidelines provided by the United States National Geospatial Intelligence Agency (NGA). The NITF provided for Pelican imagery includes the image itself, meta data, and the UDM mask. It includes a generic linear array scanner (GLAS) model in a standard format which allows for users to create orthorectified products from the imagery using a digital elevation model. The GFM is an approximation to the full physical model used by Planet. More information on the GLAS can be found in Theiss, ISPRS Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences, Volume V-1-2020. Full information on the MIL-STD-2500C standards is available through the United States NITF Technical board.
NITF for Pelican implements a Generic Linear Array Scanner (GLAS) as its geometric sensor model because Pelican is a linear scanner. As such, Pelican produces a long continuous image which we segment into chunks, rather than a mosaic of images. Further, GLAS is a generic physical sensor model that applies to images that retain their original perspective geometry and have not been warped to fit some other geospatial data.
**Automated Delivery**
For Pelican, users may order their preferred image type and indicate a delivery location at time of tasking by using Planet’s Automated Delivery feature. This feature will automatically activate the generation of the user’s requested image asset as part of the image processing chain. Delivery is also automatically initiated once the asset’s imagery has been generated. This decreases the number of steps a user needs to begin using their tasked imagery. More information on how to configure and use the Automated Delivery features can be found in the documentation at the [Planet Documentation site for Automated Delivery](https://docs.planet.com/develop/apis/tasking/auto_delivery/). Additional imaging assets can be ordered using our standard ordering process or by retriggering the automated delivery
**Trimming**
By default, Pelican imagery captured to fulfill a tasking request will be delivered trimmed to the tasked AOI. In the case of point targets, a 5 km by 5 km image will be provided. Trimming allows Planet to streamline the delivery process, improving the time to deliver imagery after capture. Additionally, trimming reduces the storage needs for users who choose to download imagery into their own storage locations. The delivered trimmed imagery is only available to the organization that originally tasked the image. Full Pelican Scenes may be obtained from the Planet Archive. Archive imagery may also be trimmed to an AOI by requesting clipping at time of ordering.
**Unusable Data Mask (UDM) File**
The UDM file is a standard deliverable included in many Pelican scene order types. It provides a spatially corresponding array identifying areas of unusable data within the associated image. The UDM identifies pixels that are impacted by cloud cover, snow, and shadows or indicate non-imaged regions Only UDM2 is supported for Pelican. Users can learn more about the process used to label pixels in the UDM process at the [Planet Documentation site for UDM2](https://docs.planet.com/data/imagery/udm/).
The UDM is delivered in a TIF format. Each 8-bit pixel within the UDM2 array utilizes individual bits to specify the utility of the corresponding image data:
* Band 1: clear mask (a value of “1” indicates the pixel is clear, a value of “0” indicates that the pixel is not clear and is one of the 5 remaining classes below)
* Band 2: snow mask
* Band 3: shadow mask
* Band 4: light haze mask
* Band 5: heavy haze mask (all images acquired after November 29, 2023 will have a value of “0” in band 5)
* Band 6: cloud mask
* Band 7: confidence map (a value of “0” indicates a low confidence in the assigned classification, a value of “100” indicates a high confidence in the assigned classification)
* Band 8: unusable data mask
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/pelican/pelican-scene/)
# Pelican Scene
The **Pelican Scene** product is the fundamental imagery unit of the Pelican constellation.
Each Scene is a framed segment extracted from a continuous Pelican imaging strip captured using Pelican’s dual-panchromatic and multispectral line-scan sensor.
## Products Overview
A Pelican Scene typically covers an **8 km swath width** and varies in along-track length depending on tasking mode, slews, and imaging geometry. Scenes contain:
* **Dual oversampled Panchromatic channels (450–800 nm)**
* **Six Multispectral bands** (Blue, Green, Red, Red Edge, NIR-Wide, and NIR-Narrow for Gen-1; or the Pelican-2 configuration)
* Radiometric and geometric corrections depending on the selected asset type
* Standard **UDM2 usable data mask**
Pelican Scenes may be delivered as:
* **Basic products** (radiometrically calibrated, sensor-corrected, georeferenced, includes RPCs)
* **Ortho products** (orthorectified, cartographically projected, 50 cm GSD)
* **Surface Reflectance, Pansharpened, and Visual** variants for analytic or visual workflows
note
Please note that non-orthorectified assets cannot be delivered to a data collection as they lack the precise geospatial alignment required to be positioned and visualized correctly on a map.
Scenes are the only Pelican item type; Pelican does **not** produce a “Collect” product like SkySatCollect.
## Pelican Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/pelican/techspec/)
# Technical Specification
### Download the PDF
[Download Pelican Product Specifications →](https://planet.widen.net/s/kbt9m6p6sx/planet-userdocumentation-pelicanproductspec)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/planetscope/)
# PlanetScope
The Planet medium-resolution (3 m spatial resolution) fleet, called "Doves", is made up of multiple flocks of satellites. In 2017, the Dove fleet achieved near-daily coverage of multispectral imagery over all landmasses, marking the completion of the Planet Mission 1.
The success of Mission 1 was made possible by the launch of Flock 3P, consisting of 88 Dove satellites, in February 2017, followed by Flock 2K with 48 satellites in July 2017. Since completing Mission 1, Planet has maintained and replenished the Dove fleet through regular launches of new flocks multiple times each year. Full list of operational satellites can be obtained from the [Planet Satellite Operational Report](https://ephemerides.planet-labs.com/operational_status.txt).
The Dove satellites design are based on the CubeSat 3U form factor, measuring 10 cm × 10 cm × 30 cm. All new flocks are launched into sun-synchronous orbit with orbit altitude of 525 kilometers with 98° inclination. It takes approximately 90 minutes for a Dove to orbit the earth. The minimum and maximum latitude coverage is ±81.5° depending on season. All of the Doves have a system constraint to image regions that have a sun elevation angle greater than 10°. Below this, the quality of the images starts to decline.
Original Dove constellation design consistent of Red, Green, Blue and Near-Infrared spectral bands. By August 2021, Planet had upgraded the constellation by replacing the original Dove satellites with next-generation SuperDoves. SuperDoves introduced four additional spectral bands—green I, red edge, yellow, and coastal blue.
note
Although the satellites are named "Doves", the imagery they capture is branded as PlanetScope.
## Dove Instruments
The table below outlines the three types of Dove instruments:
| Instrument Name | Instrument ID | Description |
| --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Dove Classic | `PS2` | Built with a telescope we call "PS2", this instrument captures red, green, blue, and near infrared channels. It produces Scene products which are approximately 25.0 x 11.5 sq km. Earliest imagery available on July, 2014 to April 29, 2022. |
| Dove-R | `PS2.SD` | Built with the same "PS2" telescope, but with updated Bayer pattern and pass-band filters, this instrument captures red, green, blue, and near infrared channels. It produces Scene products which are approximately 25.0 x 23.0 sq km. Earliest imagery available is on March, 2019 to April 22, 2022. |
| SuperDove | `PSB.SD` | Built with a telescope we call "PSB" and the same filter response as PS2.SD instrument, this instrument captures red, green, blue, near infrared, as well as a new red edge, green I, coastal blue, and yellow channel. It produces Scene products which are approximately 32.5 x 19.6 sq km. Earliest imagery available is mid-March, 2020 to current monitoring. |
You can read a more detailed overview of our sensors below. For detailed technical information on PlanetScope images refer to [PlanetScope Product Specification](https://planet.widen.net/s/vswqcrm9zw/planet-userdocumentation-psscene-productspec).
### PSB.SD
The newest **PSB.SD (SuperDove)** instrument consists of the next-generation "PSBlue" telescope with a larger 47 megapixel sensor and the same filter response as PS2.SD, in the Red, Green, Blue and NIR bands. The PSB.SD payload extends to include four additional bands; Red Edge, Green I, Yellow and Coastal Blue. Six out of eight bands are meant to be interoperable with Sentinel-2 bands. Refer to the table below to see the absorption range for each SuperDove band and interoperable with Sentinel-2. Earliest imagery available is mid-March, 2020 to current monitoring.
| Band | Name | Wavelength (fwhm) | Interoperable with Sentinel-2 |
| ---- | ------------ | ----------------- | ----------------------------- |
| 1 | Coastal Blue | 443 (20) | Yes - with Sentinel-2 band 1 |
| 2 | Blue | 490 (50) | Yes - with Sentinel-2 band 2 |
| 3 | Green I | 531 (36) | No equivalent with Sentinel-2 |
| 4 | Green | 565 (36) | Yes - with Sentinel-2 band 3 |
| 5 | Yellow | 610 (20) | No equivalent with Sentinel-2 |
| 6 | Red | 665 (31) | Yes - with Sentinel-2 band 4 |
| 7 | Red Edge | 705 (15) | Yes - with Sentinel-2 band 5 |
| 8 | NIR | 865 (40) | Yes - with Sentinel-2 band 8a |
Please refer to [this support article](https://support.planet.com/hc/en-us/articles/360014290293-Do-you-provide-Relative-Spectral-Response-Curves-RSRs-for-your-satellites) for spectral response within absorption ranges.
PSB.SD features a larger sensor, resulting in a wider scene product in both dimensions compared to PS2.SD and PS2 scene products. Each frame comprises eight stripes, as shown below, to produce the final 8-band image. These frames are stacked together using a series of consecutive frames on either side of the anchor frame.
The following image is an example of a raw PSB.SD frame as it is downlinked from a SuperDove satellite.
### PS2.SD
The PS2.SD instrument builds on the original "PS2" telescope design, utilizing the same 2D frame detector as the PS2 satellites. However, the Bayer pattern and pass-band filters from PS2 have been replaced with a high-performance butcher-block filter. This updated filter consists of four individual pass-band filters, which separate light into the Blue, Green, Red, and NIR channels. The pass-band filters for PS2.SD were specifically chosen to closely match and ensure interoperability with those of Sentinel-2 and match the Blue, Green, Red and NIR channels of SuperDove. Earliest imagery available is from March, 2019 to April 22, 2022.
| Band | Name | Wavelength (fwhm) | Interoperable with Sentinel-2 |
| ---- | ----- | ----------------- | ----------------------------- |
| 1 | Blue | 490 (50) | Yes - with Sentinel-2 band 2 |
| 2 | Green | 565 (36) | Yes - with Sentinel-2 band 3 |
| 3 | Red | 665 (31) | Yes - with Sentinel-2 band 4 |
| 4 | NIR | 865 (40) | Yes - with Sentinel-2 band 8a |
Each frame acquired by the PS2.SD instrument consists of 4 stripes, as seen below. In order to generate the final 4-band image, we stack together a number of consecutive frames on either side of a given anchor frame.
The following image is an example of a raw PS2.SD frame as it is downlinked from a Dove-R satellite.
### PS2
The PS2 satellites are equipped with instruments featuring a telescope, referred to as "PS2", paired with a 2D frame detector with a resolution of 6600 pixels across by 4400 lines down. This detector incorporates a Bayer pattern filter to separate light into Blue, Green, and Red channels. Over the Bayer pattern filter is a "2-stripe" filter, where the top half blocks NIR wavelengths, allowing only blue, green, and red light to pass through.
As a result, each frame captured by the PS2 instrument consists of a top half that is an RGB image and a bottom half that captures NIR light exclusively. To create the final 4-band image, the RGB half of each frame is combined with the NIR half of the adjacent frame. The earliest available imagery from these satellites spans from July 2014 to April 29, 2022.
The following image is an example of a raw PS2 frame as it is downlinked from a Dove-C satellite.
### Band Order
The type of imagery asset requested—whether 3-band, 4-band, or 8-band—depends on the requested scene product and may be captured using a combination of different Dove instruments. The table below outlines the type of assets produced by each of the three instruments.
| Imagery Frequency of Order Returned from PlanetScope Sensors | | | |
| ------------------------------------------------------------ | ------------------- | --------------------- | -------------------------- |
| *Bands Ordered* | *Imagery from PS2* | *Imagery from PS2.SD* | *Imagery from PSB.SD* |
| 3-band | | | |
| Band 1 = Red | Red: 590 - 670 nm | Red: 650 - 682 nm | Red: 650 - 680 nm |
| Band 2 = Green | Green: 500 - 590 nm | Green: 547 - 585 nm | Green: 547 - 585 nm |
| Band 3 = Blue | Blue: 455 - 515 nm | Blue: 464 - 517 nm | Blue: 465 - 515 nm |
| 4-band | | | |
| Band 1 = Blue | Blue: 455 - 515 nm | Blue: 464 - 517 nm | Blue: 465 - 515 nm |
| Band 2 = Green | Green: 500 - 590 nm | Green: 547 - 585 nm | Green: 547 - 585 nm |
| Band 3 = Red | Red: 590 - 670 nm | Red: 650 - 682 nm | Red: 650 - 680 nm |
| Band 4 = Near-infrared | NIR: 780 - 860 nm | NIR: 846 - 888 nm | NIR: 845 - 885 nm |
| 8-band | | | |
| Band 1 = Coastal Blue | n/a | | Coastal Blue: 431 - 452 nm |
| Band 2 = Blue | n/a | | Blue: 465 - 515 nm |
| Band 3 = Green I | n/a | | Green I: 513 - 549 nm |
| Band 4 = Green | n/a | | Green: 547 - 583 nm |
| Band 5 = Yellow | n/a | | Yellow: 600 - 620 nm |
| Band 6 = Red | n/a | | Red: 650 - 680 nm |
| Band 7 = Red Edge | n/a | | Red Edge: 697 - 713 nm |
| Band 8 = Near-infrared | n/a | | NIR: 845 - 885 nm |
## Dove Imagery Products
PlanetScope Products are available for search and download via the Planet APIs, User Interfaces, and Integrations, in the form of Basic Scene and Ortho Scene products, which are available through our platform as a set of Item Types and Asset Types.
A PlanetScope Scene Product is an individual framed scene within a strip, captured by the satellite in its continuous line-scan of the Earth. Scenes within a strip are overlapping and not organized to any particular tiling grid system.
PlanetScope Scene products range from approximately 280 to 630 square kilometers in size, depending on which instrument type captured them. They are represented in the Planet Platform as PSScene item types. PSScene supports access to 8-Band imagery (RGB, NIR, Red Edge, Yellow, Green I, and Coastal Blue).
PlanetScope Scene imagery products are available for download in the form of imagery assets. Multiple asset types are made available for Scene products, each with differences in radiometric processing and/or rectification. See PSScene Supported Assets for asset type availability.
### Asset Types
#### Basic analytic
Basic Analytic assets are non-orthorectified, calibrated, multispectral imagery products that have been corrected for sensor artifacts and transformed to Top of Atmosphere (at-sensor) radiance. These products are designed for data science and analytic applications, and for users who wish to geometrically correct the data themselves with the associated rational polynomial coefficients (RPCs) asset type. These asset names are `basic_analytic_4b` and `basic_analytic_8b`.
#### Top of the atmosphere radiance
Analytic assets are orthorectified, calibrated, multispectral imagery products that have been corrected for sensor artifacts and terrain distortions, and transformed to Top of Atmosphere (at-sensor) radiance. These products are designed for data science and analytic applications which require imagery with accurate geolocation and cartographic projection. These asset names are `ortho_analytic_4b` and `ortho_analytic_8b`.
#### Visual
Visual assets are orthorectified, color-corrected, RGB imagery products that are optimized for the human eye, providing images as they would look if viewed from the perspective of the satellite. These products are designed for simple and direct visual inspection, and can be used and ingested directly into a Geographic Information System or application. This asset is named `ortho_visual`.
#### Surface reflectance
Surface Reflectance assets are orthorectified and radiometrically corrected to ensure consistency across localized atmospheric conditions, and to minimize uncertainty in spectral response across time and location. These multispectral imagery products are designed for temporal analysis and monitoring applications, especially in agriculture and forestry sectors. These asset names are `ortho_analytic_4b_sr` and `ortho_analytic_8b_sr`.
info
Surface Reflectance asset types take longer to generate than our other PlanetScope products. They are typically available 8-12 hours after an item is published to our catalog.
### Product Naming
The name of each acquired PlanetScope image is designed to be unique and allow for easier recognition and sorting of the imagery. It includes the date and time of capture, as well as the id of the satellite that captured it. The name of each downloaded image product is composed of the following elements:
#### PlanetScope downloaded product name
The name consists of the following elements:
* `{acquisition-date}_{acquisition-time}_{acquisition-time-seconds-hundredths}_{satellite-id}_{product-level}_{band-product}.{ext}`
##### Example:
* **20230207\_143613\_03\_241c\_3B\_AnalyticMS\_SR\_8b.tif**
* **20230207\_143613\_03\_241c\_3B\_Visual.tif**
#### PlanetScope searchable product name
The name consists of:
* `{acquisition-date}_{acquisition-time-to-1-100th}_{satellite-id}`
##### Example:
* **20230207\_143613\_03\_241c**
## Processing Steps
Several processing steps are applied to PlanetScope imagery to produce the set of data products available for download.
### Sensor and Radiometric Calibration
**Darkfield/Offset Correction**: Corrects for sensor bias and dark noise. Master offset tables are created by averaging on-orbit darkfield collects across 5-10 degree temperature bins and applied to scenes during processing based on the CCD temperature at acquisition time.
**Flat Field Correction**: Flat fields are collected for each optical instrument before launch. These fields are used to correct image lighting and CCD element effects to match the optimal response area of the sensor. Flat fields are routinely updated on orbit during the satellite's lifetime.
**Camera Acquisition Parameter Correction**: Determines a common radiometric response for each image (regardless of exposure time, number of TDI stages, gain, camera temperature and other camera parameters).
**Absolute Calibration**: As a last step, the spatially and temporally adjusted datasets are transformed from digital number values into physical-based radiance values (scaled to W/(m²strμm)\*100). For additional technical details, refer to [On-Orbit Radiometric Calibration of the Planet Satellite Fleet](https://assets.planet.com/docs/radiometric_calibration_white_paper.pdf).
### Orthorectification
Removes terrain distortions. This process consists of two steps:
1. The rectification tiedown process wherein tie points are identified across the source images and a collection of reference images (ALOS, NAIP, Landsat) and RPCs are generated.
2. The actual orthorectification of the scenes using the RPCs, to remove terrain distortions. The terrain model used for the orthorectification process is derived from multiple sources (Intermap, NED, SRTM, and other local elevation datasets) and is periodically updated. Snapshots of the elevation datasets used are archived (helps in identifying the DEM that was used for any given scene at any given point).
### Visual Processing
Presents the imagery as natural color, optimized as seen by the human eye. This process consists of three steps:
1. Nominalization - Sun angle correction, to account for differences in latitude and time of acquisition. This makes the imagery appear to look like it was acquired at the same sun angle by converting the exposure time to the nominal time (noon).
2. Unsharp mask (sharpening filter) applied before the warp process.
3. Custom color curve applied post-warping.
### Surface Reflectance Processing
Removes atmospheric effects. This process consists of three steps:
1. Top of Atmosphere (TOA) reflectance calculation using coefficients supplied with the at-sensor radiance product.
2. Lookup table (LUT) generation using the 6SV2.1 radiative transfer code and MODIS near-real-time data inputs.
3. Conversion of TOA reflectance to surface reflectance for all combinations of selected ranges of physical conditions and for each satellite sensor type using its individual spectral response and estimates of the state of the atmosphere.
You can find a detailed white paper on our [Surface Reflectance Products here](https://assets.planet.com/marketing/PDF/Planet_Surface_Reflectance_Technical_White_Paper.pdf).
## Imagery Collection Versus Publication
Although the Dove constellation captures imagery of nearly all of Earth's landmasses daily, only imagery that meets our quality thresholds is published in the catalog. There are several common reasons why imagery might not be published or test-quality imagery may be published instead of standard-quality imagery.
note
Starting July 19, 2023, Planet began publishing all unrectified SuperDove images. For more details, see our Knowledge Base article, [Publishing All Unrectified PlanetScope Imagery](https://support.planet.com/hc/en-us/articles/11392960870173-Publishing-All-Unrectified-PlanetScope-Imagery-API-Changes-and-FAQ). Previously, these images were excluded from publication due to strict rectification requirements. Most unrectified images have heavy cloud cover, which hinders our pipelines from achieving accurate rectification and ground lock. While unrectified imagery was previously published only under special circumstances, we have now expanded this practice globally. All unrectified images are marked with `"publishing_stage": "preview"`.
If you notice gaps in image publication in your area before July 19, 2023, they were most likely caused by cloud cover, as weather conditions can vary significantly across regions. For gaps observed after July 19, the likely causes include band misalignment, missing pixels, other image processing issues, or the absence of image collection over that area.
### Lack of Ground Lock
Approximately 95 percent of groundlock failures are due to cloud cover. However, other factors such as extreme latitudes, challenging topography, and open water can also affect our ability to georeference images accurately. Non-groundlocked imagery provides only approximate geolocation obtained from the satellite telemetry data. To avoid user confusion or analysis errors, we recommend using imagery that has achieved rectification. Images without ground control points are identified in the metadata with the classification `"publishing_stage": "preview"`.
Occasionally, a test-quality image without groundlock may achieve groundlock and be re-categorized within 24–72 hours. Ground control points are more commonly refined after publication, typically within the first 24 hours of the image appearing in our catalog.
### Non-publication Due to Image Quality
A small percentage of images collected cannot be fully processed due to anomalies in image capture, atmospheric conditions, or other factors. To maintain quality standards, we do not publish anything that cannot be processed to a final composited image.
### Standard Versus Test Imagery
The Planet Data API provides metadata regarding image quality. This falls into two categories: 'standard' and 'test'. Most published imagery falls into the 'standard' category, meaning it has passed all of the Planet image quality metrics in the processing pipeline. To qualify for 'standard' image quality, an image must meet all of the following criteria:
* sun altitude greater than or equal to 10 degrees
* off-nadir view angle less than 20 degrees
* saturated pixels fewer than 20 percent
* image has obtained at least 200 ground control points during rectification
* and alignment threshold (based on across-track registration residuals) of less than 0.3 pixels for all band combinations.
The remaining published imagery falls into the 'test' category. Most test-quality images are categorized this way due to no lack of ground lock, or less than 199 ground control points, band alignment of less than 0.5 pixels, or a high volume of no signal pixels.
For use cases requiring fine positional accuracy, we recommend using images with `"ground_lock": true`. Test images are usable images and are appropriate for most use cases.
You can find whether an image is 'standard' or 'test' quality within the scene metadata in Explorer and the Planet Data API.
## PlanetScope Publishing Lifecycle
PlanetScope publishing stage will help users understand when the right time is to download an PlanetScope image, based on whether users pipeline needs to optimize for data latency and data accuracy.
PlanetScope publishing stage has the following values:
* `preview`: Lowest latency, lowest fidelity. PlanetScope images are unrectified; metadata changes are expected upon subsequent republishing.
* `standard`: Standard latency, standard fidelity. Data is stable and rectified, but subject to minimal metadata changes upon republishing.
* `finalized`: Highest latency, highest fidelity. Data is stable and rectified, no additional metadata changes are expected (barring any bug fixes or new quality improvements).
### Preview Stage
Applicable only to unrectifiable, open water or cloud PlanetScope images (less than 20% of all PSScene items globally).
Preview publishing stage for PlanetScope images is typically published about 4 to 6 hours before they will be republished as standard (if they are rectifiable). If an image is still marked as preview after 48 hours of acquisition, it will remain in the preview state and not move to the next.
### Standard Stage
Applicable to all PSScene items. With the exception of unrectifiable, open water/cloudy PSScene imagery.
All standard PlanetScope items will be republished to a finalized stage and may be subject to minimal change upon republishing as more scenes within a strip are published.
### Finalized Stage
Applicable to all rectifiable PSScene items. While no further republishing or metadata changes are expected as part of standard publishing for finalized items, Planet's catalog is dynamic and we will republish items as bug fixes, new metadata fields, new asset types, and broader quality improvements are released. You can read more on our [UpdateFilter](https://docs.planet.com/develop/apis/data/item-search/#updatefilter) feature to learn about ways we support redownloading to filter on these enhancements.
For PSScene items, finalized data will be available approximately 12-24 hours after an item reaches standard stage.
info
Planet replenishes the SuperDove fleet through regular launches of new flocks multiple times each year. PlanetScope images from new satellites will have a large delay of publication while the satellites undergo commissioning. Once a SuperDove is commissioned, the latency will be as above and Planet will publish all images dating back to first light for each new satellite.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/planetscope/psscene/)
# PSScene
## PSScene Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/planetscope/sandbox/)
# PlanetScope Sandbox Data
This Planet Sandbox Data collection for PlanetScope provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| ---------------------- | --------------------------------- | ----------------------------------------- | ----------------------- |
| analytic\_8b\_sr\_udm2 | Planet Sandbox Data - PlanetScope | BYOC-28eef896-9632-4546-a99e-cea34d74b21e | 2022-05-01 - 2023-04-30 |
## Planet Sandbox Data Areas
This collection includes 239 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 239 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ---------------------------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Idaho, United States | 25 | 2022-05-01 – 2023-04-30 | 46.58, -116.54 |
| Alberta, Canada | 25 | 2022-05-01 – 2023-04-30 | 50.25, -111.97 |
| Sinaloa, Mexico | 25 | 2022-05-01 – 2023-04-30 | 25.83, -109.30 |
| Saskatchewan, Canada | 25 | 2022-05-01 – 2023-04-30 | 50.95, -107.96 |
| Arauca, RAP Llanos, Colombia | 25 | 2022-05-01 – 2023-04-30 | 6.34, -71.95 |
| Texas, United States | 25 | 2022-05-01 – 2023-04-30 | 35.10, -102.46 |
| Ontario, Canada | 25 | 2022-05-01 – 2023-04-27 | 45.07, -75.50 |
| Madre de Dios, Province of Manú, Peru | 25 | 2022-05-01 – 2023-04-30 | -12.76, -70.56 |
| Santiago Rodríguez, Dominican Republic | 25 | 2022-05-02 – 2023-04-30 | 19.30, -71.50 |
| Madre de Dios, Province of Tambopata, Peru | 37 | 2022-05-02 – 2023-04-30 | -12.68, -70.10 |
| Acre, North Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -8.15, -70.29 |
| Santa Cruz Province, Argentina | 25 | 2022-05-03 – 2023-04-28 | -49.46, -70.07 |
| Madre de Dios, Province of Tambopata, Peru | 58 | 2022-05-01 – 2023-04-30 | -12.97, -69.96 |
| Madre de Dios, Province of Tambopata, Peru | 70 | 2022-05-01 – 2023-04-30 | -12.89, -70.03 |
| Madre de Dios, Province of Tambopata, Peru | 80 | 2022-05-01 – 2023-04-30 | -12.85, -70.05 |
| Madre de Dios, Province of Tambopata, Peru | 58 | 2022-05-01 – 2023-04-29 | -12.97, -69.96 |
| Neuquén Province, Argentina | 25 | 2022-05-01 – 2023-04-30 | -37.74, -69.60 |
| Vichada, RAP Llanos, Colombia | 25 | 2022-05-02 – 2023-04-28 | 5.40, -69.87 |
| Mendoza, Argentina | 25 | 2022-05-01 – 2023-04-30 | -33.09, -69.54 |
| Apure State, Venezuela | 25 | 2022-05-02 – 2023-04-30 | 7.58, -69.30 |
| Amazonas, North Region, Brazil | 25 | 2022-05-01 – 2023-04-29 | -3.57, -69.24 |
| Amazonas, North Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | 1.99, -67.69 |
| Vichada, RAP Llanos, Colombia | 25 | 2022-05-02 – 2023-04-30 | 5.00, -69.14 |
| La Pampa, Argentina | 25 | 2022-05-01 – 2023-04-29 | -36.24, -67.43 |
| Beni, Bolivia | 25 | 2022-05-01 – 2023-04-30 | -13.39, -67.11 |
| Beni, Bolivia | 25 | 2022-05-01 – 2023-04-30 | -15.29, -66.12 |
| Guarico State, Venezuela | 25 | 2022-05-02 – 2023-04-30 | 9.27, -65.97 |
| Amazonas State, Venezuela | 25 | 2022-05-01 – 2023-04-28 | 1.04, -65.85 |
| Guarico State, Venezuela | 25 | 2022-05-02 – 2023-04-30 | 8.36, -65.34 |
| Newfoundland and Labrador, Canada | 25 | 2022-05-01 – 2023-04-30 | 53.81, -65.33 |
| Tarija, Bolivia | 25 | 2022-05-01 – 2023-04-30 | -22.04, -64.49 |
| Santa Cruz, Bolivia | 25 | 2022-05-01 – 2023-04-30 | -18.15, -64.36 |
| Rondônia, North Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -10.05, -64.34 |
| Bolivar State, Venezuela | 25 | 2022-05-01 – 2023-04-30 | 5.71, -63.91 |
| Santiago del Estero, Argentina | 25 | 2022-05-03 – 2023-04-30 | -27.12, -63.56 |
| Amazonas, North Region, Brazil | 25 | 2022-05-03 – 2023-04-28 | -4.73, -61.34 |
| Santa Cruz, Bolivia | 25 | 2022-05-01 – 2023-04-30 | -15.75, -60.55 |
| Mato Grosso, Central-West Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -14.03, -60.07 |
| Entre Ríos Province, Argentina | 25 | 2022-05-01 – 2023-04-30 | -30.81, -59.61 |
| Amazonas, North Region, Brazil | 25 | 2022-05-03 – 2023-04-29 | -0.58, -58.82 |
| Quebec, Côte-Nord, Canada | 25 | 2022-05-02 – 2023-04-30 | 51.87, -58.12 |
| Caaguazú, Región Oriental, Paraguay | 25 | 2022-05-01 – 2023-04-30 | -25.05, -56.12 |
| Newfoundland and Labrador, Canada | 25 | 2022-05-02 – 2023-04-30 | 52.11, -57.97 |
| Suriname | 25 | 2022-05-05 – 2023-04-30 | 3.48, -54.99 |
| Brokopondo, Suriname | 25 | 2022-05-01 – 2023-04-30 | 5.09, -55.03 |
| Suriname | 48 | 2022-05-02 – 2023-04-30 | 4.85, -54.67 |
| Suriname | 166 | 2022-05-02 – 2023-04-30 | 5.01, -54.54 |
| Para, Suriname | 25 | 2022-05-01 – 2023-04-30 | 5.13, -54.83 |
| Suriname | 79 | 2022-05-02 – 2023-04-30 | 4.91, -54.61 |
| Rocha, Uruguay | 25 | 2022-05-01 – 2023-04-30 | -33.49, -53.73 |
| Suriname | 140 | 2022-05-02 – 2023-04-30 | 5.04, -54.54 |
| Rio Grande do Sul, South Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -31.30, -53.68 |
| Pará, North Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -1.43, -53.53 |
| Rio Grande do Sul, South Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -33.07, -52.92 |
| Mato Grosso, Central-West Region, Brazil | 25 | 2022-05-02 – 2023-04-30 | -15.65, -53.45 |
| Santa Catarina, Região Geográfica Intermediária de Chapecó, Brazil | 25 | 2022-05-01 – 2023-04-30 | -27.24, -52.29 |
| Mato Grosso do Sul, Central-West Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -22.08, -52.61 |
| Paraná, South Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -24.36, -51.23 |
| Mato Grosso, Central-West Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -13.19, -51.27 |
| São Paulo, Southeast Region, Brazil | 25 | 2022-05-02 – 2023-04-30 | -24.18, -49.22 |
| Goiás, Central-West Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -16.60, -48.80 |
| São Paulo, Southeast Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -23.61, -46.48 |
| Pará, North Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -3.35, -47.20 |
| Bahia, Northeast Region, Brazil | 25 | 2022-05-02 – 2023-04-30 | -11.12, -46.33 |
| Maranhão, Northeast Region, Brazil | 25 | 2022-05-02 – 2023-04-30 | -2.84, -43.62 |
| Bahia, Northeast Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -9.47, -40.83 |
| Paraíba, Northeast Region, Brazil | 25 | 2022-05-01 – 2023-04-30 | -7.41, -36.36 |
| Central River Division, The Gambia | 25 | 2022-05-01 – 2023-04-30 | 13.60, -15.27 |
| Greenland | 25 | 2022-05-01 – 2023-04-30 | 71.56, -28.85 |
| Tonkolili District, Sierra Leone | 25 | 2022-05-01 – 2023-04-30 | 9.10, -11.70 |
| Morocco | 25 | 2022-05-02 – 2023-04-30 | 26.36, -13.03 |
| Grand Cape Mount County, Liberia | 25 | 2022-05-03 – 2023-04-28 | 7.20, -11.25 |
| Kayes, Mali | 25 | 2022-05-01 – 2023-04-30 | 14.89, -11.49 |
| Grand Kru County, Liberia | 25 | 2022-05-02 – 2023-04-30 | 4.60, -8.01 |
| Hodh El Gharbi, Mauritania | 25 | 2022-05-02 – 2023-04-30 | 15.61, -9.29 |
| Galicia, Spain | 25 | 2022-05-01 – 2023-04-30 | 43.10, -8.42 |
| Savanes, Côte d'Ivoire | 25 | 2022-05-01 – 2023-04-29 | 9.51, -4.80 |
| Taoudénit Region, Mali | 25 | 2022-05-01 – 2023-04-30 | 17.21, -5.11 |
| Taoudénit Region, Mali | 25 | 2022-05-01 – 2023-04-29 | 16.06, -4.72 |
| Castile-La Mancha, Spain | 25 | 2022-05-02 – 2023-04-30 | 40.09, -4.49 |
| Upper-Basins, Burkina Faso | 25 | 2022-05-01 – 2023-04-29 | 11.57, -4.04 |
| Autonomous Community of the Basque Country, Spain | 25 | 2022-05-03 – 2023-04-30 | 43.24, -3.02 |
| England, United Kingdom | 25 | 2022-05-03 – 2023-04-29 | 50.82, -3.81 |
| Sahel, Burkina Faso | 25 | 2022-05-01 – 2023-04-30 | 14.22, -1.87 |
| Andalusia, Spain | 25 | 2022-05-01 – 2023-04-30 | 37.87, -2.50 |
| Castile-La Mancha, Spain | 25 | 2022-05-08 – 2023-04-30 | 39.20, -1.31 |
| England, United Kingdom | 25 | 2022-05-03 – 2023-04-29 | 53.76, -1.33 |
| Central-North, Burkina Faso | 50 | 2022-05-01 – 2023-04-29 | 13.85, -0.88 |
| Central-North, Burkina Faso | 50 | 2022-05-01 – 2023-04-30 | 13.85, -0.88 |
| Valencian Community, La Hoya de Buñol, Spain | 25 | 2022-05-05 – 2023-04-30 | 39.39, -0.80 |
| Central-North, Burkina Faso | 25 | 2022-05-01 – 2023-04-29 | 13.82, -0.74 |
| Volta Region, Ghana | 25 | 2022-05-01 – 2023-04-27 | 6.50, 0.51 |
| East, Burkina Faso | 25 | 2022-05-01 – 2023-04-30 | 12.15, 0.93 |
| Tamanrasset, Algeria | 25 | 2022-05-01 – 2023-04-30 | 24.23, 1.89 |
| Tiaret, Algeria | 25 | 2022-05-01 – 2023-04-30 | 34.96, 1.86 |
| Auvergne-Rhône-Alpes, Metropolitan France, France | 25 | 2022-05-01 – 2023-04-29 | 46.33, 2.60 |
| Ile-de-France, Metropolitan France, France | 25 | 2022-05-01 – 2023-04-30 | 48.31, 3.01 |
| Dosso Region, Niger | 25 | 2022-05-01 – 2023-04-30 | 12.54, 3.12 |
| El Menia, Algeria | 25 | 2022-05-01 – 2023-04-30 | 31.70, 4.04 |
| Delta State, Nigeria | 25 | 2022-05-05 – 2023-04-28 | 5.85, 5.30 |
| Flevoland, Netherlands | 25 | 2022-05-01 – 2023-04-30 | 52.34, 5.52 |
| Cross River State, Nigeria | 25 | 2022-05-01 – 2023-04-30 | 6.66, 9.17 |
| Lower Saxony, Germany | 25 | 2022-05-01 – 2023-04-30 | 52.25, 9.24 |
| Estuaire Province, Gabon | 25 | 2022-05-03 – 2023-04-28 | 0.03, 10.05 |
| Borno State, Nigeria | 50 | 2022-05-01 – 2023-04-28 | 10.71, 11.85 |
| Norway | 25 | 2022-05-03 – 2023-04-30 | 59.42, 9.29 |
| Borno State, Nigeria | 50 | 2022-05-01 – 2023-04-30 | 10.51, 11.97 |
| Borno State, Nigeria | 75 | 2022-05-01 – 2023-04-29 | 10.61, 11.89 |
| Veneto, Italy | 25 | 2022-05-02 – 2023-04-30 | 45.90, 12.29 |
| Sweden | 25 | 2022-05-02 – 2023-04-30 | 59.87, 12.04 |
| Borno State, Nigeria | 25 | 2022-05-01 – 2023-04-28 | 11.78, 13.17 |
| Jafara, Libya | 25 | 2022-05-02 – 2023-04-30 | 32.54, 13.15 |
| Brandenburg, Germany | 25 | 2022-05-02 – 2023-04-29 | 52.94, 12.64 |
| Borno State, Nigeria | 25 | 2022-05-01 – 2023-04-30 | 12.67, 13.60 |
| East, Cameroon | 25 | 2022-05-01 – 2023-04-30 | 3.93, 15.11 |
| Southwest, Czechia | 25 | 2022-05-01 – 2023-04-30 | 49.29, 14.50 |
| Bahr el Gazel, Chad | 25 | 2022-05-01 – 2023-04-30 | 13.97, 16.09 |
| Czechia | 25 | 2022-05-01 – 2023-04-30 | 49.75, 15.50 |
| Oshikoto, Namibia | 25 | 2022-05-01 – 2023-04-30 | -19.02, 16.74 |
| Malanje Province, Angola | 25 | 2022-05-01 – 2023-04-30 | -9.56, 16.33 |
| Équateur, Democratic Republic of the Congo | 25 | 2022-05-01 – 2023-04-30 | -1.39, 16.92 |
| Mai-Ndombe, Democratic Republic of the Congo | 25 | 2022-05-01 – 2023-04-30 | -1.26, 18.79 |
| Tshuapa, Democratic Republic of the Congo | 25 | 2022-05-01 – 2023-04-27 | -1.05, 19.62 |
| Mongala, Democratic Republic of the Congo | 25 | 2022-05-01 – 2023-04-28 | 3.09, 20.80 |
| Ouaka, Central African Republic | 25 | 2022-05-02 – 2023-04-29 | 5.34, 20.73 |
| South Great Plain, Hungary | 25 | 2022-05-01 – 2023-04-30 | 46.60, 20.20 |
| Sila, Chad | 25 | 2022-05-01 – 2023-04-30 | 12.27, 22.02 |
| Peloponnese, Western Greece and the Ionian, Greece | 25 | 2022-05-01 – 2023-04-30 | 38.58, 21.68 |
| West Darfur, Sudan | 25 | 2022-05-01 – 2023-04-30 | 13.06, 22.22 |
| Bulgaria | 25 | 2022-05-01 – 2023-04-30 | 43.78, 23.30 |
| Romania | 25 | 2022-05-01 – 2023-04-30 | 47.71, 23.11 |
| Lviv Oblast, Ukraine | 25 | 2022-05-01 – 2023-04-30 | 49.27, 23.55 |
| Lower Uele, Democratic Republic of the Congo | 25 | 2022-05-01 – 2023-04-27 | 4.39, 23.73 |
| Central Darfur State, Sudan | 25 | 2022-05-01 – 2023-04-30 | 12.98, 23.94 |
| Central District, Botswana | 25 | 2022-05-01 – 2023-04-30 | -21.65, 24.50 |
| Kufra, Libya | 25 | 2022-05-01 – 2023-04-30 | 20.49, 24.72 |
| Western Bahr el Ghazal State, South Sudan | 25 | 2022-05-01 – 2023-04-29 | 7.71, 27.98 |
| Bulgaria | 25 | 2022-05-01 – 2023-04-30 | 42.39, 25.96 |
| Matabeleland North Province, Zimbabwe | 25 | 2022-05-01 – 2023-04-30 | -18.14, 28.06 |
| Western Equatoria, South Sudan | 25 | 2022-05-01 – 2023-04-29 | 4.95, 30.00 |
| Lakes, South Sudan | 25 | 2022-05-01 – 2023-04-28 | 6.70, 29.81 |
| Zhytomyr Oblast, Ukraine | 25 | 2022-05-01 – 2023-04-30 | 50.47, 28.59 |
| Jonglei, South Sudan | 25 | 2022-05-05 – 2023-04-28 | 6.91, 31.36 |
| Cairo, Egypt | 25 | 2022-05-01 – 2023-04-30 | 30.06, 31.47 |
| KwaZulu-Natal, South Africa | 25 | 2022-05-03 – 2023-04-29 | -28.94, 31.55 |
| Eastern, Egypt | 25 | 2022-05-01 – 2023-04-30 | 30.49, 31.64 |
| Bryansk Oblast, Central Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 52.59, 31.67 |
| Murmansk Oblast, Northwestern Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 66.94, 31.69 |
| Mashonaland East Province, Zimbabwe | 25 | 2022-05-01 – 2023-04-30 | -18.24, 31.71 |
| Tver Oblast, Central Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 56.38, 34.11 |
| Sofala Province, Mozambique | 25 | 2022-05-01 – 2023-04-30 | -18.42, 34.29 |
| Gaza Strip, Palestinian Territories | 25 | 2022-05-01 – 2023-04-30 | 31.28, 34.27 |
| Kisii County, Nyanza, Kenya | 25 | 2022-05-01 – 2023-04-28 | -0.66, 34.65 |
| Kursk Oblast, Central Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 51.98, 35.60 |
| Tigray, Ethiopia | 44 | 2022-05-01 – 2023-04-30 | 14.07, 36.57 |
| Republic of Karelia, Northwestern Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 62.15, 36.52 |
| Niassa Province, Zona Norte, Mozambique | 25 | 2022-05-01 – 2023-04-30 | -14.67, 36.74 |
| Marsabit County, Kenya | 25 | 2022-05-01 – 2023-04-29 | 1.86, 37.41 |
| Kitui County, Kenya | 25 | 2022-05-01 – 2023-04-30 | -1.43, 37.92 |
| Eastern Anatolia Region, Turkey | 25 | 2022-05-03 – 2023-04-30 | 38.34, 38.15 |
| Nampula Province, Zona Norte, Mozambique | 25 | 2022-05-01 – 2023-04-30 | -14.79, 38.51 |
| Luhansk Oblast, Ukraine | 25 | 2022-05-01 – 2023-04-29 | 49.16, 39.62 |
| Somali Region, Ethiopia | 25 | 2022-05-01 – 2023-04-30 | 9.84, 43.20 |
| Krasnodar Krai, Southern Federal District, Russia | 25 | 2022-05-04 – 2023-04-27 | 44.92, 40.60 |
| Shirak Province, Armenia | 25 | 2022-05-03 – 2023-04-30 | 40.66, 43.90 |
| Somali Region, Ethiopia | 50 | 2022-05-02 – 2023-04-30 | 6.94, 44.65 |
| Baghdad Governorate, Iraq | 25 | 2022-05-03 – 2023-04-29 | 33.32, 44.45 |
| Somali Region, Ethiopia | 50 | 2022-05-02 – 2023-04-30 | 6.94, 44.65 |
| Baghdad Governorate, Iraq | 25 | 2022-05-03 – 2023-04-30 | 33.36, 44.66 |
| Lower Shabelle, Somalia | 25 | 2022-05-01 – 2023-04-30 | 2.24, 44.83 |
| Riyadh Region, Saudi Arabia | 25 | 2022-05-03 – 2023-04-30 | 20.19, 44.85 |
| West Azerbaijan Province, Iran | 25 | 2022-05-03 – 2023-04-29 | 36.15, 45.48 |
| West Azerbaijan Province, Iran | 25 | 2022-05-04 – 2023-04-30 | 38.08, 45.06 |
| Astrakhan Oblast, Southern Federal District, Russia | 25 | 2022-05-03 – 2023-04-29 | 47.85, 45.83 |
| Vologda Oblast, Northwestern Federal District, Russia | 25 | 2022-05-02 – 2023-04-30 | 60.86, 45.92 |
| Astrakhan Oblast, Southern Federal District, Russia | 25 | 2022-05-02 – 2023-04-30 | 47.76, 46.40 |
| Kirov Oblast, Volga Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 58.19, 46.51 |
| Galgaduud, Somalia | 25 | 2022-05-02 – 2023-04-30 | 6.15, 46.63 |
| Karabakh, Azerbaijan | 47 | 2022-05-04 – 2023-04-30 | 39.93, 46.72 |
| Chuvashia, Volga Federal District, Russia | 25 | 2022-05-02 – 2023-04-30 | 55.49, 46.62 |
| Karabakh, Azerbaijan | 50 | 2022-05-01 – 2023-04-30 | 39.92, 46.72 |
| Galgaduud, Somalia | 25 | 2022-05-01 – 2023-04-29 | 4.49, 46.95 |
| Ulyanovsk Oblast, Volga Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 53.11, 47.01 |
| Galgaduud, Somalia | 25 | 2022-05-02 – 2023-04-29 | 5.65, 47.04 |
| Mudug, Somalia | 25 | 2022-05-03 – 2023-04-30 | 6.00, 47.49 |
| West Kazakhstan Region, Kazakhstan | 25 | 2022-05-01 – 2023-04-30 | 49.70, 53.02 |
| Komi Republic, Northwestern Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 63.76, 49.20 |
| West Kazakhstan Region, Kazakhstan | 25 | 2022-05-01 – 2023-04-30 | 50.15, 53.78 |
| Orenburg Oblast, Volga Federal District, Russia | 25 | 2022-05-02 – 2023-04-30 | 50.91, 55.85 |
| Kerman Province, Iran | 25 | 2022-05-01 – 2023-04-30 | 27.50, 58.40 |
| Komi Republic, Northwestern Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 65.63, 59.03 |
| Ahal Region, Turkmenistan | 25 | 2022-05-01 – 2023-04-30 | 37.56, 59.32 |
| Republic of Karakalpakstan, Uzbekistan | 25 | 2022-05-05 – 2023-04-30 | 42.77, 59.70 |
| Herat Province, Afghanistan | 25 | 2022-05-01 – 2023-04-29 | 33.75, 62.84 |
| Kyzylorda Region, Kazakhstan | 25 | 2022-05-01 – 2023-04-30 | 47.04, 63.24 |
| Kurgan Oblast, Ural Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 56.03, 64.23 |
| Surxondaryo Region, Uzbekistan | 25 | 2022-05-01 – 2023-04-30 | 37.38, 66.73 |
| Khanty-Mansiysk Autonomous Okrug – Ugra, Ural Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 62.19, 65.10 |
| Maharashtra, India | 25 | 2022-05-02 – 2023-04-30 | 17.21, 73.64 |
| Maharashtra, India | 25 | 2022-05-02 – 2023-04-28 | 21.71, 74.51 |
| Rajasthan, India | 25 | 2022-05-01 – 2023-04-29 | 27.73, 77.15 |
| Tomsk Oblast, Siberian Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 57.71, 77.20 |
| Telangana, India | 25 | 2022-05-01 – 2023-04-28 | 17.06, 80.17 |
| Xinjiang, Ili, China | 25 | 2022-05-01 – 2023-04-30 | 44.32, 81.01 |
| Chhattisgarh, India | 25 | 2022-05-01 – 2023-04-28 | 21.34, 81.12 |
| Odisha, India | 25 | 2022-05-01 – 2023-04-30 | 20.71, 83.44 |
| Xinjiang, Bayingolin, China | 25 | 2022-05-01 – 2023-04-30 | 38.82, 85.55 |
| Jharkhand, India | 25 | 2022-05-02 – 2023-04-30 | 22.78, 86.07 |
| Bihar, India | 25 | 2022-05-01 – 2023-04-30 | 25.63, 87.76 |
| Kemerovo Oblast–Kuzbass, Siberian Federal District, Russia | 25 | 2022-05-02 – 2023-04-30 | 55.53, 87.76 |
| Sikkim, India | 25 | 2022-05-01 – 2023-04-29 | 27.30, 88.32 |
| Xinjiang, Altay Prefecture, China | 25 | 2022-05-01 – 2023-04-30 | 46.64, 90.75 |
| Chattogram Division, Bangladesh | 25 | 2022-05-01 – 2023-04-29 | 21.19, 92.18 |
| Assam, India | 25 | 2022-05-03 – 2023-04-30 | 26.52, 93.78 |
| Yunnan, Chuxiong, China | 25 | 2022-05-04 – 2023-04-30 | 25.12, 101.83 |
| Qinghai, Haibei, China | 25 | 2022-05-01 – 2023-04-30 | 37.59, 101.75 |
| Thailand | 25 | 2022-05-01 – 2023-04-29 | 16.44, 102.87 |
| Yunnan, China | 25 | 2022-05-05 – 2023-04-30 | 25.98, 102.65 |
| Krasnoyarsk Krai, Siberian Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 62.15, 102.16 |
| Riau, Sumatra, Indonesia | 25 | 2022-05-01 – 2023-04-30 | -0.76, 102.90 |
| Irkutsk Oblast, Siberian Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 57.82, 102.93 |
| Stung Treng, Cambodia | 25 | 2022-05-01 – 2023-04-28 | 13.18, 105.85 |
| Irkutsk Oblast, Siberian Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 55.34, 103.62 |
| Guizhou, Tongren, China | 25 | 2022-05-02 – 2023-04-30 | 28.01, 109.27 |
| Inner Mongolia, Bayannur City, China | 25 | 2022-05-01 – 2023-04-29 | 41.12, 108.25 |
| Western Australia, Australia | 25 | 2022-05-01 – 2023-04-29 | -32.34, 115.80 |
| Western Australia, Australia | 25 | 2022-05-01 – 2023-04-30 | -32.11, 116.01 |
| Nueva Ecija, Central Luzon, Philippines | 25 | 2022-05-02 – 2023-04-30 | 15.82, 120.88 |
| Anhui, China | 25 | 2022-05-01 – 2023-04-30 | 32.51, 118.01 |
| Camarines Norte, Bicol Region, Philippines | 25 | 2022-05-01 – 2023-04-30 | 14.13, 122.38 |
| Liaoning, Anshan City, China | 25 | 2022-05-01 – 2023-04-30 | 40.51, 123.22 |
| North Pyongan, North Korea | 25 | 2022-05-01 – 2023-04-30 | 39.99, 124.61 |
| Amur Oblast, Far Eastern Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 51.23, 130.16 |
| Japan | 25 | 2022-05-02 – 2023-04-29 | 40.16, 140.91 |
| Amur Oblast, Far Eastern Federal District, Russia | 25 | 2022-05-01 – 2023-04-30 | 53.42, 131.17 |
| Queensland, Australia | 25 | 2022-05-01 – 2023-04-28 | -15.68, 145.10 |
| Chukotka Autonomous Okrug, Far Eastern Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 66.45, 159.82 |
| Manawatū-Whanganui, New Zealand | 25 | 2022-05-02 – 2023-04-27 | -39.40, 175.56 |
| Chukotka Autonomous Okrug, Far Eastern Federal District, Russia | 25 | 2022-05-01 – 2023-04-29 | 62.68, 174.51 |
[Download GeoJSON](https://docs.planet.com/data/imagery/planetscope/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-16.59673\&lng=-48.78251\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2022-11-17T00%3A00%3A00.000Z\&toTime=2022-11-17T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Planalmira, Brazil
2022-05-01 to 2023-04-30
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-16.59673\&lng=-48.78251\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2022-11-17T00%3A00%3A00.000Z\&toTime=2022-11-17T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=30.05862\&lng=31.47\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2022-11-20T00%3A00%3A00.000Z\&toTime=2022-11-20T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Cairo, Egypt
2022-05-01 to 2023-04-30
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=30.05862\&lng=31.47\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2022-11-20T00%3A00%3A00.000Z\&toTime=2022-11-20T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-32.1112\&lng=116.0231\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2023-04-19T00%3A00%3A00.000Z\&toTime=2023-04-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Perth, Australia
2022-05-01 to 2023-04-30
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-32.1112\&lng=116.0231\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2F11ce5d8a-4ae8-4f99-923c-334073b747a1\&datasetId=28eef896-9632-4546-a99e-cea34d74b21e\&fromTime=2023-04-19T00%3A00%3A00.000Z\&toTime=2023-04-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/planetscope/techspec/)
# Technical Specification
### Download the PDF
[Download PlanetScope Product Specifications →](https://assets.planet.com/docs/Planet_PSScene_Imagery_Product_Spec_letter_screen.pdf)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/rapideye/)
# RapidEye
RapidEye, formerly operated by Planet, is a retired constellation of five satellites operating from 2009 to 2020. RapidEye images are approximately 5 meters per pixel resolution and are still available for download through Planet platforms.
The RapidEye satellite constellation consisted of a single launch of five high-resolution satellites.
## RapidEye Imagery Products
RapidEye products, such as Scene and Orthotile, are available for search and download via the Planet APIs, User Interfaces, and Integrations. The platform encodes these products as a set of Item Types and Asset Types.
A **RapidEye Scene Product** is a framed scene captured by the satellite in its line scan of the Earth. Scenes within a strip overlap and are not organized according to any particular tiling grid system. RapidEye Scene Products range from 75 x 50 square kilometers to 75 x 300 square kilometers. They are represented in the Planet Platform as the `REScene` item type.
A **RapidEye OrthoTile Product** is a 25 x 25 square kilometers orthorectified and tiled product generated from consecutive scenes within a strip (usually 1 or 2), based on a worldwide, fixed UTM grid system. They are represented in the Planet Platform as the `REOrthoTile` item type.
### Asset Types
#### Basic Analytic
Basic Analytic (`basic_analytic`) assets are non-orthorectified, calibrated, multispectral imagery products corrected for sensor artifacts and transformed to Top of Atmosphere (at-sensor) radiance. These products are designed for data science and analytic applications and for users who wish to geometrically correct the data (leveraging the associated rational polynomial coefficient Asset Type).
#### Analytic
Analytic (`analytic`) assets are orthorectified, calibrated, multispectral imagery products that have been corrected for sensor artifacts and terrain distortions, and transformed to Top of Atmosphere (at-sensor) radiance. These products are designed for data science and analytic applications that require imagery with accurate geolocation and cartographic projection.
#### Visual
Visual (`visual`) assets are orthorectified and color-corrected to optimize colors seen by the human eye, providing images as they would look if viewed from the satellite's perspective. These products are designed for simple and direct visual inspection, and can be used and ingested directly into a Geographic Information System or application.
#### Surface Reflectance
Surface Reflectance (`analytic_sr`) assets are orthorectified and radiometrically corrected to ensure consistency across localized atmospheric conditions and to minimize uncertainty in spectral response across time and location. These products are designed for temporal analysis and monitoring applications, especially in agriculture and forestry sectors.
### Product Naming
The name of each acquired RapidEye image is designed to be unique and allow for easier recognition and sorting of the imagery. It includes the date and time of capture, the satellite's ID, product level, and product type. The name of each downloaded image product is composed of the following elements:
#### RapidEye scene downloaded product name
The name consists of the following elements:
* `{acquisition-date}T{acquisition-time}_{satellite-id}_{product-level}_{band-product}.{extension}`
##### Example:
* **2018-09-29T163919\_RE1\_1B\_band1.tif**
#### RapidEye orthoTile downloaded product name
The name consists of:
* `{tileid}_{acquisition-date}_{satellite-id}_{product-level}_{band-product}.{extension}`
##### Example:
* **1657017\_2018-09-29\_RE1\_3A\_Analytic.tif**
## Processing Steps
Several processing steps are applied to RapidEye imagery to produce the data products that are available for download.
### Sensor and Radiometric Calibration
**Flat Field Correction:** Flat fields were collected for each optical instrument before launch. These fields were used to correct image lighting and CCD element effects to match the sensor's optimal response area.
**Temporal Calibration:** To achieve cross-calibration, corrections were applied such that all RapidEye cameras read the same DN (digital number) regardless of when the image was taken during the mission lifetime.
**Absolute Calibration:** As a last step, the spatially and temporally adjusted datasets were transformed from digital number values into physical based radiance values (scaled to W/(m²strμm)\*100).
### Orthorectification
Removes terrain distortions. This process consists of two steps:
1. The rectification tiedown process wherein tie points are identified across the source images and a collection of reference images (ALOS, NAIP, Landsat) and RPCs are generated.
2. The actual orthorectification of the scenes using the RPCs, to remove terrain distortions. The terrain model used for the orthorectification process is derived from multiple sources (Intermap, NED, SRTM and other local elevation datasets), which are periodically updated. Snapshots of the elevation datasets used are archived (helps identify the DEM used for any given scene at any given point).
### Visual Product Processing
Presents the imagery as natural color, optimized as seen by the human eye. This process consists of three steps:
1. Nominalization - Sun angle correction to account for differences in latitude and time of acquisition. This makes the imagery look like it was acquired at the same sun angle by converting the exposure time to the nominal time (noon).
2. Unsharp mask (sharpening filter) applied before the warp process.
3. Custom color curve applied post-warping.
### Surface Reflectance Product Processing
Removes atmospheric effects. This process consists of the following steps:
1. Top of Atmosphere (TOA) reflectance calculation using coefficients supplied with the at-sensor radiance product.
2. Lookup table (LUT) generation using the 6SV2.1 radiative transfer code and MODIS near-real-time data inputs.
3. Conversion of TOA reflectance to surface reflectance for all combinations of selected ranges of physical conditions and for each satellite sensor type using its spectral response and estimates of the state of the atmosphere.
For detailed technical information on RapidEye images, refer to [Planet Imagery Product Specification](https://planet.widen.net/content/dtzlv15tk3/original/Planet-UserDocument-CombinedImagery-ProductSpec.pdf).
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/rapideye/item-types/reorthotile/)
# REOrthoTile
## REOrthoTile Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/rapideye/item-types/rescene/)
# REScene
## REScene Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/)
# SkySat
SkySat, operated by Planet, is a high resolution constellation of 15 satellites, able to image revisit any location on Earth up to 10x daily (a daily collection capacity of 4,000 km2/day). SkySat supports the Planet high resolution [tasking](https://docs.planet.com/platform/get-started/access-data/task-imagery.md), which allows you to choose when and where to capture SkySat imagery. SkySat produces 4-band and panchromatic imagery and is sampled at 50 centimeters per pixel when orthorectified.
The SkySat satellite constellation consists of multiple launches of the Planet SkySat-C generation satellites, first launched in 2016. Each satellite is 3-axis stabilized and agile enough to slew between different targets of interest. Each satellite has four thrusters for orbital control, along with four reaction wheels and three magnetic torquers for attitude control. Currently, the SkySat constellation consists of morning and afternoon sun-synchronous satellites with an operational altitude of 475 km. The minimum and maximum latitude coverage is up to ±80°, but depends on season. SkySat collects approximately a 5.73 km swath.
All SkySat satellites contain Cassegrain telescopes with a focal length of 3.6 m, with three overlapping 5.5 megapixel CMOS imaging detectors making up the focal plane. The central detector is slightly offset from the side detectors, giving SkySat imagery its unique tuning fork outline. SkySat can collect frame imagery, stereo imagery, and video in day or night collects. SkySat images are typically collected in short exposures, coregistered, and stacked to improve the SNR and GSD with super-resolution. SkySat collects RGB, NIR and panchromatic imagery.
| Band | Name | Wavelength |
| ---- | ------------ | ------------ |
| 1 | Blue | 450 - 515 nm |
| 2 | Green | 515 - 595 nm |
| 3 | Red | 605 - 695 nm |
| 4 | Near IR | 740 - 900 nm |
| NA | Panchromatic | 450 - 900 nm |
## SkySat Imagery Products
SkySat imagery products are available for search, ordering, and download via Planet's APIs, User Interfaces, and Integrations. Planet offers several `item` types for SkySat imagery. Small AOIs that are covered by a single SkySat frame image may be ordered as `SkySatScene` item. Larger strips are available as coregistered, stacked, mosaiced scenes with the `SkySatCollect` item. Videos are delivered with the `SkySatVideo` item. For `SkySatScene` and `SkySatCollect`, different levels of image processing for the final product can be specified via the `Asset` type. More information on Planet `Item` and `Asset` types is available [here](https://docs.planet.com/develop/apis/data/items.md).
### SkySat Item Types
A **SkySat Scene Product** is an individual framed scene within a strip, captured by the satellite in its line-scan of the Earth. SkySat Satellites have three cameras per satellite, which capture three overlapping strips. Each of these strips contain overlapping scenes, not organized to any particular tiling grid system.
SkySat Scene products are approximately 1 x 2.5 sq km in size and are represented in the Planet Platform as the `SkySatScene` item type. You can find an image that covers an area of interest larger than a SkySat Scene and order a SkySat Collect Product.
A **SkySat Collect Product** is created by composing many SkySat Scenes along an imaging strip into an orthorectified segment. Collects are often composed of 60 or more scenes and will be at least 5 km long. They are represented in the Planet Platform as the `SkySatCollect` item type. This product may be easier to handle, if you're looking at larger areas of interest with SkySat imagery. Due to the image rectification process involved in creating this product, Collect is generally recommended over the Scene product when the AOI spans multiple scenes, particularly if a mosaic or composite image of the individual scenes is required. Collect performs necessary rectification steps automatically. This is especially useful for users who don't feel comfortable doing orthorectification manually.
A **SkySat Video Product** is a full motion video are collected between 30 and 120 seconds by a single camera from any of the SkySat satellites. Its size is comparable to a SkySat Scene, about 1 x 2.5 square kilometers. They are represented in the Planet Platform as the `SkySatVideo` item type.
SkySat Scene and Collect
### SkySat Imagery Asset Types
SkySat Scene and Collect products are available for download in the form of imagery assets. Multiple asset types are available for Scene and Collect products, each with differences in radiometric processing and/or rectification.
Asset Type availability varies by Item Type. Further details on the supported assets by item type are indicated on each Item Types' documentation site.
**Basic L1A Panchromatic** (`basic_l1a_panchromatic_d`) assets are non-orthorectified, uncalibrated, panchromatic-only imagery products with native sensor resolution. They are typically ready two hours after capture and before all other SkySat asset types are available in the catalog. These products are designed for time-sensitive, low-latency monitoring applications. They can be geometrically corrected with associated rational polynomial coefficients (RPCs) assets derived from satellite telemetry.
**Basic Analytic** (`basic_analytic`) assets are non-orthorectified, calibrated, multispectral imagery products with native sensor resolution, that have been transformed to Top of Atmosphere (at-sensor) radiance. The multispectral bands have been co-registered to each other and to the ground. Rational polynomial coefficients (RPCs) assets (ground control applied) are provided for users who wish to geometrically correct the data themselves. This product is designed for data science and analytic applications. **Basic Panchromatic** (`basic_panchromatic`) assets are non-orthorectified, calibrated, super-resolved, panchromatic-only imagery products that have been transformed to Top of Atmosphere (at-sensor) radiance. Rational Polynomial coefficients (RPCs) assets (ground control applied) are provided if you want to geometrically correct the data. A basic panchromatic image is coregistered with the associated basic analytic image. This product is designed for data science and analytic applications which depend on a wider spectral range (Pan: 450 - 900 nm).
**Ortho Analytic** (`ortho_analytic`) assets are orthorectified, calibrated, multispectral imagery products with native sensor resolution that have been transformed to Top of Atmosphere (at-sensor) radiance. These products are designed for data science and analytic applications which require imagery with accurate geolocation and cartographic projection.
**Ortho Analytic Surface Reflectance** (`ortho_analytic_sr`) assets are corrected for the effects of the Earth's atmosphere, accounting for the molecular composition and variation with altitude along with aerosol content. Combining the use of standard atmospheric models with the use of MODIS water vapor, ozone and aerosol data, this provides reliable and consistent surface reflectance scenes over Planet's varied constellation of satellites as part of our normal, on-demand data pipeline.
**Ortho Panchromatic** (`ortho_panchromatic`) assets are orthorectified, calibrated, super-resolved, panchromatic-only imagery products that have been transformed to Top of Atmosphere (at-sensor) radiance. Final image products are sampled at 50 cm. These products are designed for data science and analytic applications which require a wider spectral range (Pan: 450 - 900 nm), highest available resolution, and accurate geolocation and cartographic projection.
**Ortho Pansharpened** (`ortho_pansharpened`) assets are orthorectified, uncalibrated, super-resolved, multispectral imagery products. Lower resolution multispectral bands are sharpened to match the resolution of the super-resolved panchromatic band. Final image products are sampled at 50 cm resolution. These products are designed for multispectral applications which require highest available resolution and accurate geolocation and cartographic projection.
**Ortho Visual** (`ortho_visual`) assets are orthorectified, color-corrected, super-resolved, RGB imagery products. Color corrections are applied that are optimized for the human eye, providing images as they would look if viewed from the perspective of the satellite. Lower resolution multispectral bands are sharpened by the super-resolved panchromatic band. Final image products are sampled at 50 cm resolution. These products are designed for simple and direct visual inspection, and can be used and ingested directly into a Geographic Information System or application.
Additional details about formatting, calibration, and data scheme are available in the [Imagery Product Specification document](https://planet.widen.net/s/np6knvxnzh/planet-userdocument-combinedimagery-productspec). Planet customers can review our quarterly SkySat image reports [here](https://support.planet.com/hc/en-us/articles/360037649594-L1-Data-Quality-Report-for-the-SkySat-Constellation).
### SkySat Video Asset Types
Download the SkySat Video for an overview of supported assets by SkySatVideo item type [here](https://docs.planet.com/data/imagery/skysat/item-types/skysatvideo.md).
**Video File** (`video_file`) assets are video mp4 files, produced with Basic L1a Panchromatic scene assets captured as part of the full-motion video. Currently, no stabilization is applied to video.
**Video Frames** (`video_frames`) assets are compressed folders which include all of the frames used to create the Video File, packaged as Basic L1a Panchromatic scene assets with accompanying rational polynomial coefficients (RPCs). These products are designed primarily for customers interested in using video frames for 3D reconstruction.
### Product Naming
The name of each acquired SkySat image is unique and allows for easier recognition and sorting of the imagery. Currently, it includes the date and approximate time of capture, as well as the satellite id that captured it. The name of each downloaded image product is composed of the following elements:
#### SkySatScene
{acquisition date}\_{acquisition time}\_{satellite\_id}{camera\_id}\_{frame\_id}\_{asset}.{extension}
Example: **20200814\_162132\_ssc4d3\_0021\_analytic.tif**
#### SkySat Collect
{acquisition date}\_{acquisition time}\_{satellite\_id}\_{frame\_id}\_{bandProduct}.{extension}
Example: **20200815\_091045\_ssc6\_u0002\_visual.tif**
note
A `frame_id` with a leading `u`, as in `u0002` above, indicates a Collect product. A `frame_id` that is only a number, as in `0021`, indicates an individual Scene product.
#### SkySat Video
{acquisition date}\_{acquisition time}\_{satellite\_id}{camera\_id}\_video.mp4
Example: **20200808\_133717\_ssc3d1\_video.mp4**
## Processing
Several processing steps are applied to SkySat imagery to produce the set of data products available for download.
SkySat Processing
### Sensor & Radiometric Calibration
**Darkfield/Offset Correction:** Corrects for sensor bias and dark noise. Master offset tables are created by averaging on-orbit darkfield collects across 5-10 degree temperature bins and applied to scenes during processing based on the CCD temperature at acquisition time.
**Flat Field Correction:** Flat fields are collected for each optical instrument prior to launch. These fields are used to correct image lighting and CCD element effects to match the optimal response area of the sensor. Flat fields are routinely updated on-orbit during the satellite lifetime.
**Camera Acquisition Parameter Correction:** Determines a common radiometric response for each image (regardless of exposure time, number of TDI stages, gain, camera temperature and other camera parameters).
**Inter-Sensor Radiometric Response (Intra-Camera):** Cross calibrates the 3 sensors in each camera to a common relative radiometric response. The offsets between each sensor is derived using on-orbit cloud flats and the overlap regions between sensors on SkySat spacecraft.
**Super Resolution (Level 1B Processing):** Super resolution is the process of creating an improved resolution image by fusing information from low resolution images, with the created higher resolution image being a better description of the scene.
### Orthorectification
Removes terrain distortions. This process consists of two steps:
1. The rectification tiedown process wherein tie points are identified across the source images and a collection of reference images (ALOS, NAIP, Landsat) and RPCs are generated.
2. The actual orthorectification of the scenes using the RPCs, to remove terrain distortions. The terrain model used for the orthorectification process is derived from multiple sources (Intermap, NED, SRTM and other local elevation datasets) which are periodically updated. Snapshots of the elevation datasets used are archived (helps in identifying the DEM that was used for any given scene at any given point).
### Visual Product Processing
Presents the imagery as natural color, optimized as seen by the human eye. This process consists of three steps:
1. Nominalization - Sun angle correction, to account for differences in latitude and time of acquisition. This makes the imagery appear to look like it was acquired at the same sun angle by converting the exposure time to the nominal time (noon).
2. Unsharp mask (sharpening filter) applied before the warp process.
3. Custom color curve applied post warping.
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | --------------------------------------------------------- |
| Data API | ✅ | |
| Orders API | ✅ | See orders docs and bundle reference for more information |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/item-types/skysatcollect/)
# SkySatCollect
## SkySatCollect Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/item-types/skysatscene/)
# SkySatScene
## SkySatScene Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/item-types/skysatvideo/)
# SkySatVideo
## SkySatVideo Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/sandbox/)
# SkySat Sandbox Data
This Planet Sandbox Data collection for SkySat provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| -------------------------------- | ---------------------------- | ----------------------------------------- | ----------------------- |
| Ortho\_analytic (analytic\_udm2) | Planet Sandbox Data - SkySat | BYOC-fc704520-fc81-439f-9016-5e162c32e736 | 2021-01-01 - 2022-12-31 |
## Planet Sandbox Data Areas
This collection includes 61 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 61 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| --------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Madre de Dios, Province of Tambopata, Peru | 25 | 2021-08-11 – 2022-08-15 | -12.94, -70.04 |
| Madre de Dios, Province of Tambopata, Peru | 25 | 2021-08-17 – 2022-08-15 | -12.93, -70.09 |
| Madre de Dios, Province of Manú, Peru | 25 | 2021-08-17 – 2022-08-22 | -12.76, -70.56 |
| Madre de Dios, Province of Manú, Peru | 25 | 2021-09-11 – 2021-10-28 | -12.60, -70.15 |
| Acre, North Region, Brazil | 25 | 2022-10-05 – 2022-10-13 | -8.15, -70.29 |
| Madre de Dios, Province of Tambopata, Peru | 33 | 2021-09-06 – 2022-08-19 | -12.98, -69.90 |
| Madre de Dios, Province of Tambopata, Peru | 45 | 2021-08-11 – 2021-11-26 | -12.87, -70.01 |
| Amazonas, North Region, Brazil | 25 | 2022-05-28 – 2022-07-13 | -4.73, -61.34 |
| Amazonas, North Region, Brazil | 22 | 2021-05-06 – 2022-09-20 | -3.57, -69.23 |
| Suriname | 81 | 2022-04-05 – 2022-08-12 | 5.10, -54.48 |
| Paraná, South Region, Brazil | 23 | 2021-04-20 – 2021-05-04 | -24.36, -51.23 |
| São Paulo, Southeast Region, Brazil | 25 | 2021-01-05 – 2022-12-31 | -23.61, -46.48 |
| Goiás, Central-West Region, Brazil | 14 | 2022-08-05 – 2022-08-05 | -16.60, -48.80 |
| Bahia, Northeast Region, Brazil | 25 | 2021-01-04 – 2022-12-28 | -9.47, -40.83 |
| Paraíba, Northeast Region, Brazil | 14 | 2022-10-01 – 2022-10-04 | -7.41, -36.35 |
| Cross River State, Nigeria | 25 | 2021-01-03 – 2022-11-30 | 6.66, 9.17 |
| Borno State, Nigeria | 20 | 2021-10-31 – 2021-11-01 | 10.60, 11.98 |
| Castile-La Mancha, Spain | 25 | 2021-02-01 – 2022-12-25 | 40.09, -4.49 |
| Galicia, Spain | 25 | 2021-06-03 – 2022-09-15 | 43.10, -8.42 |
| Autonomous Community of the Basque Country, Spain | 23 | 2021-06-11 – 2022-08-30 | 43.24, -3.02 |
| Veneto, Italy | 25 | 2022-09-01 – 2022-10-12 | 45.90, 12.29 |
| Auvergne-Rhône-Alpes, Metropolitan France, France | 25 | 2021-02-19 – 2021-09-07 | 46.33, 2.60 |
| Ile-de-France, Metropolitan France, France | 19 | 2022-06-11 – 2022-06-11 | 48.31, 3.02 |
| England, United Kingdom | 20 | 2022-08-12 – 2022-08-12 | 50.83, -3.81 |
| Lower Saxony, Germany | 25 | 2021-04-30 – 2021-10-25 | 52.25, 9.24 |
| Flevoland, Netherlands | 25 | 2021-11-18 – 2022-12-29 | 52.34, 5.52 |
| England, United Kingdom | 25 | 2021-04-07 – 2022-06-26 | 53.76, -1.33 |
| Central District, Botswana | 14 | 2022-12-05 – 2022-12-27 | -21.65, 24.49 |
| Oshikoto, Namibia | 25 | 2021-05-18 – 2022-10-26 | -19.02, 16.74 |
| Malanje Province, Angola | 21 | 2021-09-13 – 2022-02-11 | -9.56, 16.33 |
| Western Bahr el Ghazal State, South Sudan | 25 | 2021-01-03 – 2022-12-01 | 7.71, 27.98 |
| Borno State, Nigeria | 24 | 2021-03-05 – 2022-05-02 | 11.78, 13.17 |
| Borno State, Nigeria | 25 | 2021-02-05 – 2022-04-14 | 12.67, 13.60 |
| Bulgaria | 25 | 2021-06-04 – 2021-07-11 | 42.39, 25.96 |
| Bulgaria | 23 | 2021-08-10 – 2022-05-23 | 43.79, 23.30 |
| Southwest, Czechia | 24 | 2021-06-25 – 2021-06-25 | 49.29, 14.50 |
| Czechia | 13 | 2022-12-16 – 2022-12-16 | 49.74, 15.48 |
| Brandenburg, Germany | 25 | 2021-02-12 – 2022-02-21 | 52.94, 12.64 |
| KwaZulu-Natal, South Africa | 19 | 2021-03-05 – 2022-12-14 | -28.94, 31.54 |
| Tigray, Ethiopia | 44 | 2021-03-31 – 2022-08-29 | 14.07, 36.57 |
| Cairo, Egypt | 25 | 2021-04-16 – 2022-09-22 | 30.06, 31.47 |
| Gaza Strip, Palestinian Territories | 25 | 2021-05-20 – 2022-12-18 | 31.28, 34.27 |
| Kursk Oblast, Central Federal District, Russia | 20 | 2022-04-10 – 2022-04-15 | 51.98, 35.60 |
| Tver Oblast, Central Federal District, Russia | 21 | 2021-02-08 – 2022-03-22 | 56.38, 34.11 |
| Galgaduud, Somalia | 24 | 2021-01-03 – 2022-12-01 | 6.15, 46.63 |
| Baghdad Governorate, Iraq | 25 | 2021-01-26 – 2022-10-04 | 33.32, 44.45 |
| West Azerbaijan Province, Iran | 23 | 2021-11-09 – 2022-05-01 | 36.15, 45.48 |
| Eastern Anatolia Region, Turkey | 25 | 2022-06-24 – 2022-12-21 | 38.34, 38.15 |
| Karabakh, Azerbaijan | 25 | 2021-02-12 – 2022-11-13 | 39.82, 46.75 |
| Karabakh, Azerbaijan | 25 | 2022-08-20 – 2022-08-20 | 40.03, 46.69 |
| Astrakhan Oblast, Southern Federal District, Russia | 25 | 2021-02-18 – 2022-03-24 | 47.76, 46.40 |
| Western Australia, Australia | 25 | 2021-02-14 – 2022-10-05 | -32.34, 115.80 |
| Western Australia, Australia | 25 | 2021-01-01 – 2022-12-28 | -32.11, 116.01 |
| Stung Treng, Cambodia | 20 | 2021-03-06 – 2021-08-06 | 13.18, 105.85 |
| Maharashtra, India | 25 | 2022-09-03 – 2022-09-03 | 17.21, 73.64 |
| Chattogram Division, Bangladesh | 25 | 2021-03-23 – 2022-09-23 | 21.19, 92.18 |
| Jharkhand, India | 25 | 2021-01-13 – 2022-11-07 | 22.78, 86.07 |
| Sikkim, India | 25 | 2022-08-12 – 2022-08-15 | 27.30, 88.32 |
| Surxondaryo Region, Uzbekistan | 16 | 2021-09-05 – 2021-09-05 | 37.37, 66.73 |
| North Pyongan, North Korea | 25 | 2021-03-22 – 2022-06-15 | 39.99, 124.61 |
| Japan | 15 | 2021-09-07 – 2021-09-07 | 40.16, 140.92 |
[Download GeoJSON](https://docs.planet.com/data/imagery/skysat/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-9.46769\&lng=-40.83146\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-05-07T00%3A00%3A00.000Z\&toTime=2022-05-07T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Bahia, Brazil
2021-01-04 to 2022-12-28
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-9.46769\&lng=-40.83146\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-05-07T00%3A00%3A00.000Z\&toTime=2022-05-07T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=30.05862\&lng=31.47\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-08-19T00%3A00%3A00.000Z\&toTime=2022-08-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Cairo, Egypt
2021-04-16 to 2022-09-22
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=30.05862\&lng=31.47\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-08-19T00%3A00%3A00.000Z\&toTime=2022-08-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-32.1112\&lng=116.0231\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-10-19T00%3A00%3A00.000Z\&toTime=2022-10-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
Perth, Australia
2021-01-01 to 2022-12-28
25km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-32.1112\&lng=116.0231\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Fc0d9df19-9fb2-4191-89bd-4168678def5d\&datasetId=fc704520-fc81-439f-9016-5e162c32e736\&fromTime=2022-10-19T00%3A00%3A00.000Z\&toTime=2022-10-19T23%3A59%3A59.999Z\&layerId=TRUE-COLOR\&demSource3D="MAPZEN")
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/skysat/techspec/)
# Technical Specification
### Download the PDF
[Download Planet Imagery Product Specifications →](https://assets.planet.com/docs/Planet_Combined_Imagery_Product_Specs_letter_screen.pdf)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/superres/)
# SuperRes Overview
Planet SuperRes uses the Enhanced Super-Resolution Generative Adversarial Network (ESRGAN) with a collection of 120,000 pairs of SkySat and PlanetScope imagery with a perceptual loss training technique to produce imagery that looks natural and remains faithful to the ground truth. We include a confidence layer to help assess the degree of accuracy of the generated pixel by evaluating various sources of error.
Planet SuperRes is currently available as SuperRes [Mosaics](https://docs.planet.com/data/imagery/mosaics.md#superres-mosaics) and SuperRes [PlanetScope Scenes](https://docs.planet.com/data/imagery/planetscope/psscene.md). To learn more about Planet SuperRes, visit [Planet University - Introduction to Planet SuperRes](https://university.planet.com/introduction-to-planet-superres). They share the model features described below:
Vinkeveen-Utrecht, Netherlands SuperRes Visual Mosaic November 2025
| | |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Product Specifications | - - 2 meter resolution prediction: AI-enhanced resolution (reprojected to 2.4 m at the equator).- - Confidence layer: A per-pixel map identifying areas where the AI has high certainty versus where it made inferences.* * Self-service access: Direct access through familiar APIs and tools. |
## The Training Dataset
The training dataset is the foundation of Planet Visual SuperRes. It consists of 120,476 high-quality image pairs, each comprising a 3 m PlanetScope scene and a 0.5 m SkySat scene of the same location. Dataset quality is ensured through strict curation standards:
* **Temporal consistency:** Every pair was captured within a 12-hour window to minimize change on the ground between acquisitions.
* **Geometric precision:** Sub-pixel co-registration was achieved via phase correlation; pairs with a phase correlation error exceeding 0.2 were discarded.
* **Radiometric normalization:** Per-pixel normalization aligns the SkySat spectral response to PlanetScope, preventing radiometric artifacts in the model output.
* **Clarity:** A minimum 95% clear-sky requirement was applied to both images in every pair, eliminating cloud contamination.
The dataset spans diverse geographies, seasons, and land cover types — providing the broad training signal needed for reliable performance at a global scale. It is split into 100,476 training pairs, 10,000 validation pairs, and a held-out test set of 10,000 pairs.
## Model Architecture and Training
Planet Visual SuperRes uses an Enhanced Super-Resolution Generative Adversarial Network (ESRGAN), a leading generative AI approach for single-image super-resolution.
SuperRes Visual Mosaic, October 2025
Key architectural elements include:
* Residual-in-Residual Dense Blocks (RRDBs): Replace traditional residual blocks with denser connections for improved feature representation and training stability.
* Perceptual Loss Function: Combines pixel-wise loss with perceptual loss derived from a pre-trained deep network, training the model to produce outputs that look sharp and natural to the human eye — not just pixel-accurate.
* Adversarial Training: A discriminator network enforces realistic textures and fine details, enabling sharper outputs than traditional bicubic or convolutional methods.
The production 1.5x model was further optimized for deployment: input channels were reduced from 8 to 4 bands with no performance loss, iterative pruning reduced the computational footprint, and the final model was quantized to half-precision (float16) for efficient inference at scale.
## The Confidence Layer
The Confidence Layer is an auxiliary output channel added to the ESRGAN generator network. It is trained concurrently with the primary super-resolution task to predict the expected Mean Absolute Error (MAE) between the model's output and ground truth image, using an L1 loss function. At inference time, the layer produces a per-pixel MAE estimate from the low-resolution input alone with no reference high-resolution image required. The raw MAE output is rescaled to a 0–100 confidence score:
* Confidence = 100 \* 1 - min((MAE / 2500), 1)
SuperRes Visual Mosaic, October 2025
## Reliable Performance
The production 1.5x model was evaluated against the 10,000-image held-out test set. Our primary metric is Learned Perceptual Image Patch Similarity (LPIPS), which evaluates image similarity based on deep network feature maps (AlexNet) and aligns most closely with human visual perception. We report 1 − LPIPS so that higher scores indicate better perceptual quality.
| Metric | Score |
| ----------------------------------------------------- | ----- |
| 1 − Learned Perceptual Image Patch Similarity (LPIPS) | 0.961 |
| Peak Signal-to-Noise Ratio (PSNR) | 33.53 |
| Structural Similarity Index Measure (SSIM) | 0.876 |
| Confidence Layer Accuracy\* | 0.993 |
\**Confidence Layer Accuracy provides a direct comparison between the ground truth MAE and our predicted MAE.*
In a world where the gap between coverage and clarity has constrained what satellite imagery can deliver, Planet Visual SuperRes offers something new: the persistent, near-daily global reach of PlanetScope, with sharper imagery that makes features easier to see, characterize, and monitor at scale. With a purpose-built training dataset, a model tuned for human visual perception, and a built-in Confidence Layer that provides per-pixel transparency, Planet SuperRes gives analysts a clearer view of the world — and more time to focus on what they see in it.
## Disclaimer
Neural networks, including the processes used to create SuperRes Mosaics are a form of artificial intelligence (AI). While the per-pixel confidence layer (noted above) is intended to help Licensee identify the accuracy of each pixel of SuperRes, the SuperRes neural network may generate incorrect, incomplete, or misleading information, and may fail to identify (or may hallucinate) features or objects depicted. Planet does not warrant or guarantee the accuracy, completeness, or suitability of SuperRes Mosaics. Licensee is solely responsible for reviewing, validating, and approving any SuperRes pixel, particularly before Licensee takes action based on such SuperRes pixel, including, without limitation, visual comparison of each pixel with the corresponding standard visual mosaic.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/tanager/)
# Tanager
### Constellation & Sensor Overview
The Tanager satellite is an imaging spectrometer capturing approximately 426 Bands with \~5 nm spacing between an approximate range of 380-2500 nm at 30 meters per pixel resolution, with the first launched in August 2024. Planet intends to launch additional Tanager satellites to meet market demands over the coming years.
Each satellite is 3-axis stabilized and agile enough to slew between different targets of interest. Each satellite has a single electric propulsion (EP) thruster for orbital control, along with four reaction wheels and three magnetic torquers for attitude control.
All Tanagers contain three-mirror anastigmat (TMA) telescopes with a focal length of 400 mm and Dyson form spectrometers, with a 640x480 pixel Mercury-Cadmium-Telluride (MCT) detector as the focal plane array.
#### Sensitivity Collection Modes
Tanager's hyperspectral imaging employs a minimum integration time of 8 ms, resulting in an approximately 58 m along-track pixel length in pushbroom mode, which causes pixels in geometrically corrected images to be rectangular, and for most use cases this pixel stretching is generally an undesirable effect.
To mitigate this elongation and enhance signal-to-noise ratio (SNR), Tanager utilizes a technique called 'back-nodding.' This maneuver allows imaging to begin before and continue after the satellite passes directly over the target area, extending capture time and improving SNR for smaller regions. Find the table summary below describing each mode's minimum to maximum length.
| TANAGER SENSITIVITY MODE DIMENSIONS | | |
| ----------------------------------- | ----------------------------------------- | ----- |
| Mode | Minimum to Maximum Collection Length (km) | Width |
| Maximum Sensitivity (4x8ms) | 18 to 65.9 km | 18 km |
| High Sensitivity (3x8ms) | 18 to 91.5 km | 18 km |
| Medium Sensitivity (2x8ms) | 18 to 153.1 km | 18 km |
| Standard Sensitivity (1x8ms) | 18 to 481.2 km | 18 km |
| Glint (1x8) | 18 to 481.2 km | 18 km |
##### Standard Sensitivity Collection Mode
In the Standard Sensitivity collection mode, also referred to as 1x8 ms, Tanager will perform back nodding to slow down its ground scan rate just enough to avoid pixel stretching. The goal of this mode is to maximize the swath length while still maintaining square pixels.
##### Maximum Sensitivity Collection Mode
In the Maximum Sensitivity collection mode, also referred to as 4x8 ms, Tanager will perform much faster back nodding to drastically slow down its ground scan rate to achieve the highest possible SNR, allowing each point to be “seen” for a \~4 times longer duration. Because of this, the effective frame rate that is achieved is equivalent to 32 ms of exposure. The goal of this variant is to optimize SNR while remaining within the envelope of Tanager’s agility and orbital geometry.
### Tanager Imagery Products
#### Tanager Chunking Strategy
A single Tanager collection can be quite long and in order to process and deliver Tanager assets with more reasonable file sizes, the collections will be dynamically chunked. Each collect will be separated into TanagerScenes based on a set of rules:
1. A scene is at least 325 lines long.
2. A scene is at most 750 lines long.
3. The strategy seeks to produce square-ish scenes.
4. All scenes within a single collection are approximately the same size. The worst case scenario is that a collect will have only two different scene sizes. These two sizes will vary by only a single line.
Example chunking below. Each | BOX | is a TanagerScene.
1700 line collect: | 0:567 | 567:1134 | 1134:1700 |
2600 line collect: | 0:650 | 650:1300 | 1300:1950 | 1950:2600 |
#### Imagery Item Type
Tanager Imagery products are available as either individual Basic or Ortho Scenes and Radiance or Surface Reflectance. Tanager imagery utilizes a native file format of HDF5. These products can be obtained from the Planet APIs through the TanagerScene item type.
A **Tanager Scene Product** is an individual framed scene within a strip, captured by the satellite in its line-scan of the Earth.
Tanager Scene products have a swath width of 18km and the length is variable in size dependent on Planet chunking. They are represented in the Planet Platform as the `TanagerScene` item type.
#### Imagery Asset Types
Tanager Scene products are available for download in the form of imagery assets. Multiple asset types are made available for Scene and Collect products, each with differences in radiometric processing and/or rectification.
Asset Type availability varies by Item Type. You can find an overview of supported assets by item type here:
[TanagerScene Supported Assets-Types](https://docs.planet.com/data/imagery/tanager/item-types/tanagerscene.md)
You can find our complete [Imagery Product Specification here](https://planet.widen.net/s/wq9dsgzvv6/planet-userdocumentation-tanager).
### Tanager Methane Products
#### Methane Item Type
Each TanagerMethane item has had an automated methane detection algorithm run on it, derived from a matched filter (doi:10.5194/amt-8-4383-2015).
TanagerMethane products are only offered in their orthorectified format. These products can be obtained from the Planet APIs through the TanagerScene item type.
A **Tanager Methane Product** is representative of a methane detection attempt on a TanagerScene item. They have the same extent as a TanagerScene. They are represented in the Planet Platform as the `TanagerMethane` item type.
#### Methane Asset Types
Tanager Methane products are available for download in the form of imagery and geographic feature assets. Multiple asset types are made available for Methane products, each with differences in publication latency.
Asset Type availability varies by Item Type. You can find an overview of supported assets by item type here:
[TanagerMethane Supported Assets-Types](https://docs.planet.com/data/imagery/tanager/item-types/tanagermethane.md)
### Product Naming
The name of each Tanager image and methane product is designed to be unique and allow for easier recognition and sorting. The name of each downloaded image product is composed of the following elements:
*TanagerScene*
`{acquisition-date}_{acquisition-time}_{acquisition-time-seconds-hundredths}_{satellite-id}_{asset-type}.{ext}`
* Example: `20241005_062757_84_4001_ortho_radiance_hdf5.h5`
* Searchable product in Data API is: TanagerScene `20241005_062757_84_4001`
*TanagerMethane*
TanagerMethane uses the same naming convention as TanagerScene. All TanagerMethane items have a corresponding TanagerScene item. However, TanagerMethane is only created where methane detection was requested, so many TanagerScene items will not have a corresponding TanagerMethane item.
`{acquisition-date}_{acquisition-time}_{acquisition-time-seconds-hundredths}_{satellite-id}_{asset-type}.{ext}`
* Example: `20241005_062752_00_4001_ortho_ql_ch4.tif`
* Searchable product in Data API is: TanagerMethane `20241005_062752_00_4001`
### Processing
Several processing steps are applied to Tanager imagery to produce the set of data products available for download.
| TANAGER PROCESSING STEPS | |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Step | Description |
| Dark Subtraction | Corrects for sensor bias and dark level to ensure that zero illumination corresponds to zero radiance. The correction is updated frequently by averaging dark frames acquired over the non-sunlit side of Earth. |
| Pedestal Correction | Subtracts remaining residual error in the zero point after the dark frame is subtracted so that the numerical zero is equivalent to the radiometric zero. This residual is estimated by computing the median value of masked pixels located at the edges of the detector, which are physically blocked from external illumination. |
| Flat Field Correction | Corrects relative differences in pixel sensitivities to match those in the optimal response area of the sensor. Flat fields are collected for each optical instrument in lab conditions prior to launch, and are routinely updated on-orbit during the satellite lifetime. |
| Bad Pixel Correction | Fills in defective pixels on the detector following the method described in Chapman et al. (2019), which replaces pixels by linearly interpolating to the most similar spectrum within the frame. |
| Optical Scatter Correction | Removes stray light artifacts from scatter in the optical elements to bring the spectral response function (SRF) towards a Gaussian distribution. These artifacts are modeled as concentric Gaussians convolved with the original spectrum, so correction involves deconvolving the stray response components from the spectrum with a method outlined in Thompson et al. (2018a). |
| Optical Ghost Correction | Follows the correction approach of Zandbergen et al. (2020) to remove structured stray light artifacts (“ghosts”) that arise due to unwanted reflections within the optics. A ghost image is predicted for each frame and subsequently subtracted to remove the stray signal. |
| Absolute Radiometric Calibration | Converts the observations from Digital Number (DN) values into physical radiance units (W/(m²*sr*μm)). |
| Order Sorting Filter (OSF) Seam Correction | Interpolates over the radiometrically suspect rows where the order sorting filter (OSF) seams are located. |
| Visual Product Processing | Presents the imagery as natural color, as seen by the human eye. Only applied to the ortho\_visual asset type. |
| Orthorectification | The orthorectification process is a method to correct the geographic location of imagery. The orthorectification process depends on the accuracy of the reference imagery, the terrain model, satellite and sensor parameters. OneAtlas Airbus imagery is used as reference images during Tanager orthorectification and the terrain model used for the orthorectification process is derived from multiple sources (SRTM, Intermap, and other local elevation datasets) which are periodically updated. The orthorectification process consists of two key steps. The first step is a feature-based approach for coarse model refinement followed by area-based matching for fine model refinement. The algorithm provides an improved sensor model of the satellite state and sensor, allowing for more accurate georectification. |
| Atmospheric Correction | Removes atmospheric effects and estimates surface reflectance. Per pixel surface reflectance values are calculated using the ISOFIT (v2.9.5) (Imaging Spectrometer Optimal FITting) python package. This uses an optimal estimation method for simultaneously solving for both the atmospheric composition and surface reflectance values using hyperspectral radiance imagery as the input. |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/tanager/item-types/tanagermethane/)
# TanagerMethane
## Methane Products Overview
Each TanagerMethane item has an automated methane detection algorithm run on it, derived from a matched filter (doi:10.5194/amt-8-4383-2015).
TanagerMethane products are only offered in their orthorectified format. These products can be obtained from the Planet APIs using the TanagerMethane item type.
A **Tanager Methane Product** is representative of a methane detection attempt on a TanagerScene item. They have the same extent as a TanagerScene. They are represented in the Planet Platform as the `TanagerMethane` item type.
The Methane QuickLook (MQL) bundle is designed for easy interpretation by methane experts with limited remote sensing knowledge. Within each bundle, you can access multiple imagery assets listed below for their purposes.
### Tanager Methane QuickLook Products
Tanager’s Methane QuickLook is a low-latency, derived methane product that reveals point source emission locations and estimates of magnitude in kg/hr for observed plumes. It will be delivered to customers within 72 hours of acquisition, enabling you to identify and take action quickly when emissions are detected.
## Methane Plume Metadata
Relevant for `ql_ch4_json` TanagerMethane assets.
| Parameter | Description | Type |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| plume\_id | Unique identifier for each plume. The format is `_`. The “part” postfix (For example, A, B, C) identifies multiple plumes captured in the same image in the order they were detected. | string |
| plume\_quality | \*\* This field is used for Methane QuickLook, ql\_ch4\_json asset-type. \*\* Qualitative assessment of plume quality captured by a human operator during the plume detection process (good, questionable, or bad). More on the Plume quality classification below. | string |
| plume\_provider | Identifies the organization who identified the plume. | string |
| plume\_provider\_id | Plume ID according to the `plume_provider`. Planet assigns a new plume ID to match existing naming conventions. | string |
| plume\_provider\_version | Plume provenance information. This information is not directly useful to customers, but can be used by Planet and the `plume_provider` to inspect data quality issues. | string |
| datetime | Date and time of the acquisition in Coordinated Universal Time (UTC). | datetime |
| ime | The total kilograms (kg) of methane in a plume above the background concentration at the time of image capture. | float |
| fetch | Plume length, meters (m) | float |
| emission | Quantified emission rate of a plume, estimated using the Integrated Methane Enhancement method. (Duren et al., 2019 - "California's Methane Super-Emitters", Nature) | |
| emission\_uncertainty | The uncertainty in an emission rate is derived from uncertainty in IME and wind speed. | |
| wind\_speed\_avg | Mean wind speed m/s | float |
| wind\_speed\_std | Standard deviation wind speed m/s | float |
| wind\_direction\_avg | Wind direction (degrees) | float |
| wind\_direction\_std | Wind direction standard deviation (degrees) | float |
| wind\_source | Wind source from reanalysis. (For example, Openmeteo, HRRR, ERA5) | string |
| strip\_id | Strip ID of the Tanager collect used for plume detection. | string |
### Plume Quality Classification
Planet classifies detected plumes into three categories: `Good`, `Questionable`, and `Bad`, based on the following criteria:
* `Good`: The plume is unambiguous, with a well-defined shape and minimal artifacts, making it reliable for further analysis.
* `Questionable`: The plume is clearly present, but there are issues. For example: irregular shape or retrieval artifacts that could affect the accuracy of quantification. A post-emission QC process will also assess whether `Questionable` plumes are suitable for publishing an emission rate or if only the detection will be reported.
* `Bad`: It is unclear whether the detected feature is a plume. However, this is not a final state. After an initial review, a secondary post-emission quality control process is conducted. This review determines whether the detection should be discarded or reclassified as `Questionable`.
## TanagerMethane Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/tanager/item-types/tanagerscene/)
# TanagerScene
## Imagery Products Overview
The TanagerScene products include Visual, Radiance, and Surface Reflectance hyperspectral imagery in HDF5 file format.
### Tanager Chunking Strategy
A single Tanager collection can be long and to process and deliver Tanager assets with more reasonable file sizes, the collections are dynamically chunked. Each collect is separated into TanagerScenes based on the following set of rules:
1. A scene is at least 325 lines long.
2. A scene is at most 750 lines long.
3. The strategy seeks to produce square-ish scenes.
4. All scenes within a single collection are approximately the same size. The worst case scenario is that a collect will have only two different scene sizes. These two sizes will vary by only a single line.
Example chunking below. Each | BOX | is a TanagerScene.
1700 line collect: | 0:567 | 567:1134 | 1134:1700 |
2600 line collect: | 0:650 | 650:1300 | 1300:1950 | 1950:2600 |
### Tanager Ortho Products
The Tanager Ortho Scene product is orthorectified and the product was designed for a wide variety of applications that require imagery with an accurate geolocation and cartographic projection. It has been processed to remove distortions caused by terrain and can be used for cartographic purposes. The Ortho Scenes are delivered as visual (RGB), top-of-atmosphere radiance and surface reflectance products. Ortho Scenes are radiometrically-, sensor-, and geometrically-corrected products that are projected to a cartographic map projection. The geometric correction uses fine Digital Elevation Models (DEMs) with a post spacing of between 10 and 90 meters.
Ground Control Points (GCPs) are used in the creation of every image and the accuracy of the product will vary from region to region based on available GCPs. Computer vision algorithms are used for extracting feature points such as OpenCV’s STAR keypoint detector and FREAK keypoint extractor. The GCP and tiepoint matching is done using a combination of RANSAC, phase correlation and mutual information.
### Tanager Basic Products
The Tanager Basic Scene products are unorthorectified, providing imagery as seen from Tanager without any geolocation corrections inherent in the imaging process. It has a scene based framing, and is not mapped to a cartographic projection. This product line is available in HDF-EOS5 format.
The Tanager Basic Scene product contains the hyperspectral data in image space and a separate geolocation array (longitude and latitude information) that has been processed to remove distortions caused by terrain and geometric sensor distortions. The Basic Scene product is designed for users that want to orthorectify the product themselves with the help of the provided geolocation array or for users with advanced image processing capabilities and a desire to geometrically correct the product themselves.
## TanagerScene Item Type
Loading resource data...
Loading...
## Item Properties
| Field | Description | Data Type |
| ----- | ----------- | --------- |
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/tanager/techspec/)
# Technical Specification
### Download the PDF
[Download Tanager Product Specifications →](https://planet.widen.net/s/g7hkc69nvr/planet-userdocumentation-tanager)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/imagery/udm/)
# Usable Data Mask
## Overview
Clouds, aerosols, and other surface conditions can impact the radiometry and usability of Earth observation data. To improve the consistency of data analysis of satellite imagery for research or commercial applications, Planet provides the Usable Data Mask (UDM) to accurately classify these phenomena in every image published in the Planet data catalog.
UDM classifies each pixel in an image as Clear, Cloud, Haze, Cloud Shadow or Snow, allowing users to determine which pixels are usable for their analysis. UDM2.1 is the latest version developed by Planet, provided in multiband GeoTIFF format, with each band corresponding to a different semantic class and two additional bands offering supplementary information.
## Archive Availability
As of November 29, 2023 all PlanetScope and SkySat imagery will be processed by UDM2.1. Any imagery acquired prior to November 29, 2023 were processed by UDM2.0.
**Planetscope:** Usable Data Masks are available globally for PlanetScope imagery beginning in August, 2018. In specific agricultural regions, UDMs are available from January 2018. A small percentage of PlanetScope imagery after August 2018 will not include the UDM2 asset due to rectification or image processing failures.
**SkySat:** Usable Data Masks are available for the SkySat imagery beginning from 2017. In rare instances, a UDM2 asset may not be available for specific SkySat items.
**Pelican:** All Usable Data Masks for Pelican imagery will be processed by UDM2.1.
## Key differences between UDM2.1 and UDM2.0
Planet published a new Usable Data Mask version (UDM2.1) in November, 2023. UDM2.1 has significantly improved classification accuracy compared to previous versions of the product. In addition, there are some key differences between the UDM versions:
* The classification schema for UDM was modified for UDM2.1 to contain a single Haze class, producing a more consistent, accurate, and understood product.
* The Heavy Haze class from UDM2.0 has been deprecated in UDM2.1. This class had lower predictive accuracy, and was commonly misclassified with the Cloud and Light Haze classes.
* A new dataset of ground truth images was labelled to train new models with the updated classification schema. See [Methodology](#udm21-classification-methodology) for more detail.
* The Cloud class is defined as regions of a scene containing opaque atmospheric interference; objects on the ground cannot be seen through Cloud. Alternatively, Haze is defined as any interference that *can* be seen through to the ground.
* In some instances, the Near-Infrared (NIR) band is required to distinguish between Cloud and Haze, due to the "atmospheric window" of infrared wavelengths. As a result, Haze classifications in UDM will occasionally appear opaque in a Visual product, but are transparent when viewed as a false color image with the NIR band.
note
The formatting has not changed between UDM2.0 to UDM2.1; the product still contains 8-bands for backwards compatibility. The prior Light Haze band (band 4) now contains the UDM2.1 Haze classification values. The values for the Heavy Haze band (band 5) and the heavy\_haze\_percent metadata will always be 0 for UDM2.1.
## UDM2.1 product bands
The UDM2.1 asset is delivered as a 8-band GeoTIFF file, with the following bands and values:
| Band | Class | Pixel Value Range | Description |
| ---- | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Clear | 0,1 | Regions of a scene that are free of cloud, haze, cloud shadow and/or snow. |
| 2 | Snow | 0,1 | Regions of a scene that are covered with snow or ice. |
| 3 | Cloud Shadow | 0,1 | Shadows caused by clouds or haze and not by mountains, buildings, or other terrain features. |
| 4 | Light Haze | 0,1 | Regions of a scene with thin, filamentous clouds, soot, dust, and smoke. You can see ground objects through haze. |
| 5 | Heavy Haze | 0,1 | UDM2.1 does not support a heavy haze class, but this class name persists to support functional backwards compatibility with UDM2.0. Pixels will never be classified as Heavy Haze with UDM2.1. |
| 6 | Cloud | 0,1 | Regions of a scene that contain opaque clouds. You cannot see ground objects through clouds. |
| 7 | Confidence | 0-100 | Pixel-wise model prediction probability score. This is an estimate of how confident the model is that a pixel classification is correct. |
| 8 | Unusable Pixels | 0-255 | Equivalent to the UDM1 asset (Bitwise-encoded). The bits are as follows. Bit 0: Blackfill; Bit 1: Likely cloud; Bit 2: Blue (Band 2) is anomalous; Bit 3: Green (Band 4) is anomalous; Bit 4: Red (Band 6) is anomalous; Bit 5: Red Edge (Band 7) is anomalous; Bit 6: NIR (Band 8) is anomalous; Bit 7: Coastal Aerosol (Band 1) and/or Green-I (Band 3) and/or Yellow (Band 5) is anomalous. See [Planet's Imagery Specification](https://assets.planet.com/docs/Planet_Combined_Imagery_Product_Specs_letter_screen.pdf) for complete details. |
## Model confidence
The UDM2.1 classification model outputs a prediction probability score for each pixel in the image, estimating confidence or certainty that a pixel classification is correct.
The confidence score can be used to define thresholds as to whether to use a given pixel’s classification. For example, if you want to increase the likelihood that all Cloud pixels in an image are masked, you can use a low confidence value to threshold all pixels classified in the Cloud class. Alternatively, a higher confidence threshold could be set for all Clear pixels, increasing the likelihood that usable pixels are correctly classified prior to an analysis.
note
There will be times where the model confidence for a given classification is high, but the prediction is still incorrect. For example, a pixel could be classified with high confidence as Clear, when in fact it is Cloudy. In these particular cases, we may need additional training data to improve the model accuracy under these conditions. Users are encouraged to report any issues to their Customer Support Representative so Planet can continue to improve the product.
## Metadata fields
These metadata fields are based on the UDM product, and can be used to construct filters when searching for Planet imagery. To learn more, refer to the Planet help page [Search Filters](https://docs.planet.com/develop/apis/data/item-search.md#filters).
| Field | Type | Value Range | Description |
| ---------------------------- | ---- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear\_percent | int | \[0-100] | Percent of clear values in the image. Clear values represents Regions of a scene that are free of cloud, haze, cloud shadow and/or snow |
| clear\_confidence\_percent | int | \[0-100] | percentage value: aggregated algorithmic confidence in 'clear' pixel classifications |
| cloud\_percent | int | \[0-100] | Percent of cloud values in the image. Cloud values represent regions of a scene that contain thick clouds. You cannot see ground objects through clouds. |
| heavy\_haze\_percent | int | \[0-100] | **Note:** UDM2.1 does not include a heavy haze classification. Any non-zero values for this field were generated by the UDM2.0 product.
**For UDM2.0:** Percent of heavy haze values in the image. Heavy haze values represent scene content areas that contain thin low altitude clouds, higher altitude cirrus clouds, soot and dust which allow fair recognition of land cover features, but not having reliable interpretation of the radiometry or surface reflectance. |
| light\_haze\_percent | int | \[0-100] | Percent of haze values in the image. Haze values represent regions of a scene with thin, filamentous clouds, soot, dust, and smoke. You can see ground objects through haze. |
| shadow\_percent | int | \[0-100] | Percent of cloud shadow values in the image. Shadow values represent regions of the scene that are covered by shadows caused by clouds. |
| snow\_ice\_percent | int | \[0-100] | Percent of snow and ice values in the image. Snow\_ice values represent regions of the scene that are hidden below snow and/or ice. |
| visible\_percent | int | \[0-100] | Visible values represent the fraction of the scene content (excluding the portion of the image which contains blackfill) which comprises clear, light haze, shadow, snow/ice categories, and is given as a percentage ranging from zero to one hundred. |
| visible\_confidence\_percent | int | \[0-100] | Average of confidence percent for clear\_percent, light\_haze\_percent, shadow\_percent and snow\_ice\_percent |
\* Blackfill content refers to empty regions of a scene file that have no value
## UDM2.1 classification methodology
Planet’s UDM2.1 classification approach is based on supervised machine learning techniques that use observation data from Planet satellites to train a classification model.
The architecture for UDM2.1 is a modified UNET, a deep learning supervised segmentation model, that runs on 4-band (RGB-NIR) top-of-atmosphere radiance imagery. A diverse corpus containing tens of thousands of PlanetScope and SkySat images were hand-labeled to mark each pixel into one of the 5 classes noted above. The model was then trained using this labeled dataset so that it can classify new imagery into those same 5 classes.
To ensure that the truth scenes dataset are representative of the global catalog of Planet images, Planet draws from a diversity of satellites, scene content, seasonality, geography and cloud types to contribute to the truth scene curation and classification process.
  
## Model Accuracy
Planet evaluates the UDM by comparing model predictions to a sample of held-out labeled data called a validation dataset or ground truth dataset. We perform a quantitative evaluation of model accuracy by computing precision, recall and F1 metrics on a per class basis. For our validation datasets of thousands of images, we observed the following F1, precision and recall metrics:
**PlanetScope**
| Class | F1 | Precision | Recall |
| ------------ | ----- | --------- | ------ |
| Clear | 0.892 | 0.855 | 0.933 |
| Snow | 0.829 | 0.836 | 0.822 |
| Cloud Shadow | 0.602 | 0.597 | 0.607 |
| Light Haze | 0.602 | 0.586 | 0.619 |
| Heavy Haze | n/a | n/a | n/a |
| Cloud | 0.948 | 0.933 | 0.964 |
**Pelican**
| Class | F1 | Precision | Recall |
| ------------ | ----- | --------- | ------ |
| Clear | 0.910 | 0.877 | 0.946 |
| Snow | 0.849 | 0.827 | 0.872 |
| Cloud Shadow | 0.528 | 0.494 | 0.567 |
| Light Haze | 0.607 | 0.586 | 0.630 |
| Heavy Haze | n/a | n/a | n/a |
| Cloud | 0.962 | 0.955 | 0.970 |
**SkySat**
| Class | F1 | Precision | Recall |
| ------------ | ----- | --------- | ------ |
| Clear | 0.848 | 0.816 | 0.883 |
| Snow | 0.803 | 0.780 | 0.87 |
| Cloud Shadow | 0.442 | 0.391 | 0.508 |
| Light Haze | 0.619 | 0.581 | 0.662 |
| Heavy Haze | n/a | n/a | n/a |
| Cloud | 0.924 | 0.905 | 0.944 |
Planet engineering teams regularly review UDM cloud masks to identify new scenes to be added to our ground truth datasets. Additionally, customer reports of regions and specific scenes with poorly performing UDMs are an integral part of the feedback process to improve our training data and model performance.
note
Planet publishes imagery globally. Our goal is to ensure the highest quality in our model accuracy, but there can be anomalous behavior. If you observe poor quality, please contact your Customer Support Representative so Planet can address these issues with quarterly iterations of the model.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planet-sandbox-data/)
# Planet Sandbox Data
Planet Sandbox Data is a series of Data Collections that allow you to test Planet datasets. The data is made available under a [CC-BY-NC](https://creativecommons.org/licenses/by-nc/4.0/) license and is available for users with a paid subscription or [trial](https://insights.planet.com/sign-up/) accounts.
Planet has made this data available for you to test out workflows, train a model, or see what a dataset looks like prior to [making a purchase](https://planet.com/pricing). We've set up data in a variety of locations to make it possible to test out different use cases.
Requirements
Planet Sandbox Data is available for all accounts which have processing units, both paid and trial. You can [sign up for a trial here](https://insights.planet.com/sign-up/). If you need more assistance, you can [contact our sales team](https://planet.com/contact-sales).
## Using Planet Sandbox Data
To get started with using Planet Sandbox Data, you can use the following resources.
### [Explore Planet Sandbox Data via Browser →](https://insights.planet.com/analyze/browser/?tutorialIdToShow=PSD_TUTORIAL)
[Quickly explore data through a web application and view pre-selected highlights.](https://insights.planet.com/analyze/browser/?tutorialIdToShow=PSD_TUTORIAL)
### [Explore Planet Sandbox Data via API →](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks#planet-sandbox-data)
[Deep dive into analysis workflows in Jupyter Notebooks from Planet's Github.](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks#planet-sandbox-data)
## Planet Sandbox Data Locations
Planet Sandbox Data is available in a subset of the [WorldStrat locations](https://worldstrat.github.io/), ranging from 25 to 200 sq km in size. The locations are spread across the world, assuring a diverse representation of different use cases. Each location has a time stack of images across a range of dates that you can use to see changes over time.
Available locations of Planet Sandbox Data.
## Available Data Collections
The best way to find when and where data is available is to look at the respective sandbox data pages for each data layer in the documentation. You can find these pages below.
Each page contains a map that you can use to find areas of interest and see when data is available. Select an area to find links to either open the data in the Browser or to copy the geojson to use in the APIs.
[](https://docs.planet.com/data/imagery/arps/sandbox.md)
### [Analysis-Ready PlanetScope Sandbox Data](https://docs.planet.com/data/imagery/arps/sandbox.md)
[](https://docs.planet.com/data/imagery/mosaics/sandbox.md)
### [Mosaics Sandbox Data](https://docs.planet.com/data/imagery/mosaics/sandbox.md)
[](https://docs.planet.com/data/imagery/planetscope/sandbox.md)
### [PlanetScope Sandbox Data](https://docs.planet.com/data/imagery/planetscope/sandbox.md)
[](https://docs.planet.com/data/imagery/skysat/sandbox.md)
### [SkySat Sandbox Data](https://docs.planet.com/data/imagery/skysat/sandbox.md)
[](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/sandbox.md)
### [Forest Carbon Diligence Sandbox Data](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/sandbox.md)
[](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/sandbox.md)
### [Forest Carbon Monitoring Sandbox Data](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/sandbox.md)
[](https://docs.planet.com/data/planetary-variables/land-surface-temperature/sandbox.md)
### [Land Surface Temperature Sandbox Data](https://docs.planet.com/data/planetary-variables/land-surface-temperature/sandbox.md)
[](https://docs.planet.com/data/planetary-variables/soil-water-content/sandbox.md)
### [Soil Water Content Sandbox Data](https://docs.planet.com/data/planetary-variables/soil-water-content/sandbox.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/)
# Planetary Variables
[](https://docs.planet.com/data/planetary-variables/crop-biomass.md)
### [Crop Biomass](https://docs.planet.com/data/planetary-variables/crop-biomass.md)
[](https://docs.planet.com/data/planetary-variables/field-boundaries.md)
### [Field Boundaries](https://docs.planet.com/data/planetary-variables/field-boundaries.md)
[A set of polygons that represents the boundaries of agricultural fields.](https://docs.planet.com/data/planetary-variables/field-boundaries.md)
[](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence.md)
### [Forest Carbon Diligence](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence.md)
[Data on forest carbon in 30m resolution.](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence.md)
[](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring.md)
### [Forest Carbon Monitoring](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring.md)
[Data on forest carbon in 3m resolution.](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring.md)
[](https://docs.planet.com/data/planetary-variables/land-surface-temperature.md)
### [Land Surface Temperature](https://docs.planet.com/data/planetary-variables/land-surface-temperature.md)
[](https://docs.planet.com/data/planetary-variables/soil-water-content.md)
### [Soil Water Content](https://docs.planet.com/data/planetary-variables/soil-water-content.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/crop-biomass/)
# Crop Biomass
Crop Biomass provides cloud-free, analysis-ready data every day. By combining optical (Sentinel-2 and PlanetScope) with radar data (Sentinel-1), this product offers users the opportunity to monitor agricultural fields, even during periods with a persistent cloud cover.
Crop Biomass users get a daily raster independently of weather conditions with the data from the most updated direct observation from the day before. Each pixel has a relative measure of biomass with values that range from 0 to 1. A detailed description of Crop Biomass' methodology can be found in [Burger et al. (2024)](https://doi.org/10.3390/rs16050835).
Extensive validation has been conducted on different crops. Examples of this validation can be found for grain crops in [Guillevic et al. (2024)](https://doi.org/10.1016/j.fcr.2024.109511) and for alfalfa in [Lucero et al. (2024)](https://www.mdpi.com/2072-4292/16/18/3379).
## Use Cases
**Monitor crop growth and development** - You can track the growth and development of crops throughout the growing season, helping them to identify any issues early on and take appropriate action.
**Detect and respond to stressors** - Frequent updates on Crop Biomass data can help you detect stressors such as pests, diseases, or nutrient deficiencies. Timely access to this information allows you to respond more quickly and effectively, minimizing potential negative impacts on crop health and yield.
**Optimize inputs and interventions** - By tracking biomass dynamics, you can make better-informed decisions about the timing and application of inputs such as fertilizers and pesticides, as well as plan targeted interventions to address issues in specific areas of the field.
**Improve harvest planning and efficiency** - Access to up-to-date Crop Biomass data can help you plan harvests more effectively, by identifying areas of the field with higher biomass that may require adjusted harvest strategies or equipment settings.
**Estimate crop yield** - Peer-reviewed scientific article in Field Crops Research: Planet’s Biomass Proxy for monitoring aboveground agricultural biomass and estimating crop yield [Guillevic et al., 2024](https://doi.org/10.1016/j.fcr.2024.109511)
## Published Scientific Peer-Reviewed Articles:
* The Biomass Proxy: Unlocking Global Agricultural Monitoring through Fusion of Sentinel-1 and Sentinel-2 [Burger et al., 2024](https://doi.org/10.3390/rs16050835)
* Planet’s Biomass Proxy for monitoring aboveground agricultural biomass and estimating crop yield [Guillevic et al., 2024](https://doi.org/10.1016/j.fcr.2024.109511)
## Blog Posts
* [Planet's Crop Biomass for Agriculture Monitoring and Yield Forecasting](https://medium.com/planet-stories/planets-crop-biomass-for-agriculture-monitoring-and-yield-forecasting-8211f03f14ca)
* [Next Generation Agriculture Monitoring at Scale with Planet's Crop Biomass](https://www.planet.com/pulse/next-generation-agriculture-monitoring-at-scale-with-planets-crop-biomass/)
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
#### Crop Biomass 3 m
Loading...
#### Crop Biomass 10 m
Loading...
The area of interest for Crop Biomass should correspond to a single agricultural field. If the AOI of a subscription includes multiple fields, whether they contain different crops or the same crop managed differently, the resulting Crop Biomass data will not accurately reflect conditions within any specific field.
For more information on the Subscriptions API and code samples, see the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
## Additional Resources
[🎓Planet University](https://university.planet.com/intro-to-crop-biomass)
[Learn the Crop Biomass basics with this introduction course.](https://university.planet.com/intro-to-crop-biomass)
[📖Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md)
[Get started with the Subscriptions API.](https://docs.planet.com/develop/apis/subscriptions.md)
[📓Jupyter Notebooks](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks/api_guides/subscriptions_api/crop_biomass)
[Access Crop Biomass and create visualizations with this tutorial.](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks/api_guides/subscriptions_api/crop_biomass)
[📖EvalScripts](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/crop-biomass/)
[Visualize Crop Biomass and extract insights with EvalScripts.](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/crop-biomass/)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/crop-biomass/products/)
# Products
## Crop Biomass 3 m
Loading...
## Crop Biomass 10 m
Loading...
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/crop-biomass/techspec/)
# Technical Specification
## Overview
The Crop Biomass is a fusion of microwave and optical satellite imagery, using the advantages of each to accurately estimate relative aboveground crop biomass regardless of cloud cover and at spatial resolutions of 3 and 10 meters. Crop Biomass is only available over agricultural fields.
This product integrates microwave data from the European Space Agency (ESA) Sentinel-1 satellites and optical images from Sentinel-2 and PlanetScope. The output from these combined data sources is fused in an algorithm designed to provide a reliable measurement of crop biomass over agricultural areas. This is a relative measure of biomass, so each pixel value has a value of 0 (low biomass) to 1 (high biomass). The product is provided daily and in near real time (latency less than 24 hours).
## Planet's Crop Biomass: A Planetary Variable
The Crop Biomass uses the vegetation signal derived from cross polarizations of microwave observations in combination with a vegetation index from Sentinel-2 and PlanetScope. The vegetation signal in the microwave region is different to the one in the optical domain. The microwave signal is a direct function of the vegetation water content, dielectric properties of the water within the vegetation, and the vegetation structure ([Ulaby et al., 1986](https://doi.org/10.1017/S0016756800015831); [Kerr et al., 1994](https://www.taylorfrancis.com/chapters/edit/10.1201/9781003424062-20/vegetation-models-observations-review-yann-kerr-jean-pierre-wigneron)). Considering the strong relationship between vegetation water content and vegetation biomass, this microwave information is, in this case, used as a biomass indicator for crops ([Vreugdenhil et al., 2018](https://doi.org/10.3390/rs10091396); [Khabbazan et al., 2019](https://doi.org/10.3390/rs11161887)). On the other hand, in optical imagery, spectral indices are used to estimate the vegetation conditions. The spectral measurements in the visible region are sensitive to the chlorophyll content, while the measurements in the near infrared are sensitive to the mesophyll structure of the leaves ([Townshend, 1993](https://catalogue.nla.gov.au/catalog/99070)).
Planet offers Crop Biomass with the following features:
* Daily for timely decision-making
* Cloud-free for continuous and consistent feed of observations
* Analysis-ready
* Mid-resolution (3 and 10 m)
*Figure 1: Measurements of Crop Biomass in eastern Mexico. The image above demonstrates both the spatial variability of the biomass for a single date (July 1, 2021), as well as the average biomass of the marked field over a timespan of four years.*
## Product Specifications
| Data Resource | Crop Biomass 3 m | Crop Biomass 10 m |
| --------------------- | ----------------------------------------------- | ----------------------------------------------- |
| Source ID | BIOMASS-PROXY\_V5.0\_3 | BIOMASS-PROXY\_V4.0\_10 |
| Unit | None (Typical Range 0 to 1) | None (Typical Range 0 to 1) |
| Pixel Size | 0.000027° (±3x3 m) - EPSG:4326 | 0.000089° (±10x10 m) - EPSG:4326 |
| Geographical Coverage | Global | Global |
| Temporal Resolution | daily (365 observations per year) | daily (365 observations per year) |
| Satellites Used | Sentinel-1, Sentinel-2, Dove (Planetscope) | Sentinel-1, Sentinel-2, Dove (Planetscope) |
| Data Availability | January 2024 – present | January 2019 - present |
| NRT Latency | Daily at 6am local time | Daily at 6am local time |
| Archive Latency | Less than 4 hours after creating a subscription | Less than 4 hours after creating a subscription |
Crop Biomass is a global product, but its geographic availability is limited in some areas between December 2021 and January 2025 due to the [failure and subsequent end of mission of Sentinel 1-B](https://www.esa.int/Applications/Observing_the_Earth/Copernicus/Sentinel-1/Mission_ends_for_Copernicus_Sentinel-1B_satellite).
### Metadata
The daily GeoTIFF files include metadata that provides transparency regarding how the product is constructed.
| Metadata | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AVERAGE\_NDVI | The average NDVI (Normalized Difference Vegetation Index) value for the date, derived from the optical data used in the product. |
| CLOUD\_PROBABILITY | The cloud probability (0 to 1) from the optical imagery used. Higher values indicate cloudier conditions that may affect data quality. Derived from Sentinel-2 data and available only when a corresponding observation exists for that date. |
| SURFACE\_WATER\_PROBABILITY | The probability of surface water within the field (0 to 1). Higher values indicate areas that may be affected by water or flooding. Derived from Sentinel-1 data and available only when a corresponding observation exists for that date. |
| SNOW\_PROBABILITY | The probability of snow within the field (0 to 1). Higher values indicate areas that may be covered by snow. Derived from Sentinel-2 data and available only when a corresponding observation exists for that date. |
| DATE\_LAST\_OPTICAL\_IMAGE\_USED | The date of the most recent optical image used in the product. This can support the understanding and interpretation of the signal, as it is an indication of the relative contribution of the optical data. |
| DATE\_LAST\_S1\_IMAGE\_USED | The date of the most recent Sentinel-1 SAR image used in the product. This can support the understanding and interpretation of the signal, as it is an indication of the relative contribution of the radar data. |
| LAST\_OPTICAL\_IMAGE\_SOURCE | The source of the most recent optical image used, either "PS" (PlanetScope) or "S2" (Sentinel-2). |
| PERCENTAGE\_PIXELS\_MASKED | The percentage of pixels in the dataset that were masked due to issues such as cloud cover, water, snow, roads, or buildings. A value of "0.0" indicates that no pixels were masked, meaning the data is complete and unaltered. |
| PRODUCT\_VERSION | The version of the product (for example, "v4" for 10 m, "v5" for 3 m), indicating the current version of the Crop Biomass product and reflecting the methodology and data processing used. |
| SOFTWARE\_VERSION | The version of the biomass\_proxy software used to generate the product. Useful for debugging and tracing product lineage. |
| WARNING | A warning message that appears when the field has been produced under extreme cloudy conditions. When present, it indicates that the spatial quality of the data may be impacted. |
Below is a Python code snippet on how to extract the metadata from the `.tif` file of interest.
```
from osgeo import gdal
def get_metadata_from_raster(file_path: str) -> dict:
dataset = gdal.Open(file_path)
metadata = dataset.GetMetadata()
return metadata
```
## Methodology
### Microwave data
#### Sentinel-1
The Crop Biomass product leverages Sentinel-1's Synthetic Aperture Radar (SAR) data, focusing on the Cross Ratio (CR) index derived from VH (Vertical-Horizontal) and VV (Vertical-Vertical) polarizations. Sentinel-1's ability to penetrate clouds and collect data under all weather conditions makes it invaluable for agricultural monitoring, especially in regions with frequent cloud cover.
The CR index highlights vegetation structure and water content while minimizing the influence of soil moisture and surface roughness, which can otherwise obscure the biomass signal. To ensure the accuracy of the CR index, the data undergoes preprocessing steps that include speckle filtering to reduce noise and orbit correction to normalize the effects of varying incidence angles and azimuth angles across different satellite passes.
The resulting CR time series is then scaled to match the range of the Normalized Difference Vegetation Index (NDVI) from optical data. This scaling is crucial for fusing the radar and optical signals, allowing for a more accurate representation of crop biomass over time.
### Optical data
#### Sentinel-2
Sentinel-2 provides high-resolution optical imagery, which is critical for capturing the spatial variability of crop biomass. The primary index used from Sentinel-2 is the Normalized Difference Vegetation Index (NDVI), calculated from the reflectance values in the red (Band 4) and near-infrared (Band 8) regions of the electromagnetic spectrum. NDVI is widely recognized for its sensitivity to chlorophyll content and vegetation health, making it an excellent proxy for biomass.
Sentinel-2 data is preprocessed to remove clouds, snow, and any man-made structures such as green houses, roads, or buildings. To address gaps in temporal coverage due to clouds or infrequent satellite passes, a dynamic interpolation method is used, extrapolating partially cloud-covered images by referencing the most recent cloud-free image. This approach ensures a continuous time series of NDVI values.
#### PlanetScope
PlanetScope imagery, with its higher revisit frequency, complements Sentinel-2 by filling in temporal gaps. This additional data source is especially valuable in regions with persistent cloud cover or during critical growing periods when timely biomass data is essential. The integration of PlanetScope data enhances the spatial and temporal resolution of the Crop Biomass product, making it more robust and reliable.
### Data Inputs
Table 1: List of inputs for Crop Biomass production
| Product | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Radar backscatter | C-Band Synthetic Aperture Radar (SAR) data from the Sentinel-1A Level-1 ground range detected (GRD) product, in the IW mode (downloaded with the SentinelHub Asynchronous API). The product consists of focused SAR data that has been detected, multi-looked, and projected to ground range using the Earth ellipsoid model WGS84. This GRD product has a pixel spacing of 10 x 10 meters. Before December 2021, Sentinel-1B was also in orbit and is part of the archive data for CB. Detailed information is available [here](https://sentiwiki.copernicus.eu/web/document-library#Product-Definition-and-Specification). |
| Reflectances Red and NIR bands (10 m) | Sentinel-2 Level-1C reflectances (downloaded with the SentinelHub Asynchronous API) for the two bands: red (around 665 nm) and NIR (near-infrared around 842 nm). This product provides orthorectified (geometric ortho-correction taking into account a DEM) Top Of Atmosphere reflectance (more details [here](https://sentiwiki.copernicus.eu/web/s2-processing)). The cloud masking is performed in-house using [S2Cloudless](https://www.pythonfmask.org/en/latest/). Detailed information is available [here](https://sentiwiki.copernicus.eu/web/document-library#Product-Specification-Documents). |
| Reflectances Red and NIR bands (3 m) | PlanetScope Ortho Scene product provides orthorectified, multispectral imagery from the PlanetScope constellation, for the red (around 665 nm) and NIR (near-infrared around 865 nm) bands. The imagery is collected by the SuperDove satellites at a 3-meter ground sample distance (GSD) at nadir and has a pixel size of approximately 3 meters after orthorectification. The product is processed to remove geometric distortions, using ground control points (GCPs) and digital elevation models (DEMs), ensuring a positional accuracy of less than 10 meters RMSE at the 90th percentile. The [UDM 2.1](https://docs.planet.com/data/imagery/udm.md) cloudmask is applied to the product. Detailed information is available [here](https://assets.planet.com/docs/Planet_PSScene_Imagery_Product_Spec_letter_screen.pdf). |
| Field Boundaries | Geospatial boundaries of agricultural fields, used to define the areas for biomass estimation. These boundaries are essential for accurate data fusion, as the product works at field-level. The boundaries are provided by the client in a GeoJSON format. |
### Data Fusion and Scaling
The core innovation of the Crop Biomass product lies in its data fusion methodology, which integrates the temporally consistent radar signal from Sentinel-1 with the spatially detailed optical signal from Sentinel-2 and PlanetScope.
You can read more about the methodology in the published paper: *The Biomass Proxy: Unlocking Global Agricultural Monitoring through Fusion of Sentinel-1 and Sentinel-2* ([Burger et al., 2024](https://doi.org/10.3390/rs16050835)).
This fusion process is conducted in two main steps:
1. **Temporal Fusion**: The CR and NDVI time series are combined at the field level using a dynamic weighting strategy. This strategy assigns more weight to the most reliable and recent observations, ensuring that the temporal evolution of the biomass signal is accurately captured.
2. **Spatial Fusion**: Once the temporal signal is established, it is downscaled to a 10-meter resolution by integrating the spatial patterns observed in the optical data. This step involves applying a spatial weighting function that accounts for the variations in both radar and optical signals across the field, resulting in a high-resolution biomass map that combines the strengths of both data sources.
## Data Quality
### Validation
We have rigorously evaluated the CB against both field measurements and other remote sensing products, such as NDVI. Given the wide range of potential use cases—such as crop monitoring, event detection, and yield forecasting—the validation process is an ongoing effort. To illustrate its value, we will briefly explore two common use cases: crop monitoring and yield forecasting.
NDVI is commonly used for crop monitoring as it effectively measures plant greenness. However, many widely cultivated crops change color as they approach the final stages of growth before harvest. For instance, barley (or other grains) and canola exhibit significant differences when comparing CB with NDVI. As barley ripens, it changes color from green to light brown, and canola’s yellow flowers reflect more red light, leading to a decrease in NDVI values. In contrast, the CB product accounts for the actual biomass of the crops, enabling a more accurate estimation of the harvest date. This capability to measure biomass directly distinguishes CB from NDVI, particularly in assessing crop maturity and planning harvests.
*Figure 2. The Crop Biomass and NDVI time series for barley and canola, demonstrating different features associated with color changes.* ([Burger et al., 2024](https://doi.org/10.3390/rs16050835))
You can read more about the yield-related validation in the published paper *Planet’s Biomass Proxy for monitoring aboveground agricultural biomass and estimating crop yield* ([Guillevic et al., 2024](https://doi.org/10.1016/j.fcr.2024.109511))
In the validation paper, you will find a comprehensive analysis of the product's performance in yield estimation for corn, wheat, and soybean—some of the most widely cultivated crops globally. The product's performance is assessed by correlating either the maximum or an aggregated value of biomass to the yield. Data points were collected from several fields in Mead, Nebraska, and Kellogg, Michigan. This analysis demonstrates both the Crop Biomass' ability to forecast yield before the end of the growing season, as well as to capture the intra-field variability of the biomass.
*Figure 3. Relationships between crop yield and three different yield indicators based on time series of Biomass Proxy (BP): the maximum value of BP through the crop season (a), the mean values of BP from crop emergence to BP max (b) and the mean value of BP over growing-degree-days (GDD) -based integration periods.*([Guillevic et al., 2024](https://doi.org/10.1016/j.fcr.2024.109511))
### Quality Control
Quality control of the Crop Biomass product is conducted on two levels: within the algorithm itself and through metadata. The algorithm ensures quality in several ways, beginning with the quality of the input data. Each observation is assigned a quality factor based on the number of valid pixels (for example, those without clouds, water, snow, roads, buildings, etc.) and this factor decreases over time. This mechanism, along with extensive preprocessing of all input data, ensures that the product remains as up-to-date and accurate as possible. See the [Metadata description](https://docs.planet.com/data/planetary-variables/crop-biomass/products.md#Metadata) for more details.
### Limitations
The following are some key limitations that need to be considered:
* Sentinel-1 signal is not NDVI: The agricultural market is “trained” on NDVI. The cross-ratio is an index derived from different Sentinel-1 polarizations. The differences in behavior between radar-based and optical index must be considered when offering this product.
* Behavior in pastures, grasslands and other low-growing vegetation: Crop Biomass is generally not recommended for pastures, grasslands, or other low-growing vegetation. The product relies heavily on Sentinel-1 C-band radar. When vegetation is low to the ground, the radar signal penetrates completely to the soil. As a result, the signal becomes dominated by soil moisture rather than actual vegetative biomass. This creates unreliable, artificial "spikes" in Crop Biomass values.
* Possible changes upon re-request: There may be relatively small changes in Crop Biomass values when re-requesting data for the same field and date. This is due to [subtle changes in the underlying PlanetScope data](https://docs.planet.com/data/imagery/planetscope.md#planetscope-publishing-lifecycle) that may occur as items are republished with quality improvements.
## Frequently Asked Questions
#### Will the Crop Biomass PV work for smallholder farms?
We tested the product in different regions with small-scale fields. While the data shows consistency up to 0.2 hectares, its quality will also depend on the presence of mixed crops.
#### Is there demo data available?
Demo data should be prepared by pre-sales on-demand.
#### Can customers use the Crop Biomass in Sentinel Hub?
Yes, subscriptions can be generated and visualized in the EO Browser. Also, subscriptions can be hosted in Sentinel Hub through Planet’s API.
#### Does Crop Biomass work for orchards and vineyards?
We tested our data in different crops including orchards and vineyards. As mentioned above, the behavior of Sentinel-1 derived indices is different from the ones from optical-derived sources. Our team can share information with prospective customers that are crop-specific.
#### How can I extract the metadata?
The simplest way to inspect the metadata is with the command line:
```
gdalinfo your_tif_file.tif
```
This will show a list of specifics of the file, such as the coordinate reference system, the pixel size, the extent, and the metadata. Alternatively, you can also do this in Python as shown in [the quality control section](#quality-control).
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/field-boundaries/)
# Field Boundaries
Field Boundaries is an enabling Planetary Variable that provides critical infrastructure required to answer many of the larger scale questions about agriculture production. Field delineation is the process of automatically tracing the boundaries of agricultural parcels from satellite or aerial imagery. An agricultural parcel is a spatially homogeneous land unit used for agricultural purposes, where a single crop is grown. The result of field delineation is field boundaries, a set of closed vector polygons marking the extent of each agricultural parcel. Such polygons are the input to a multitude of applications, ranging from the management of agricultural resources, such as Area Monitoring, precision farming, to the estimation of damages to crop yield due to natural disasters like drought and floods, and human-made disasters like war. Automatic estimation of parcels with high fidelity in a timely manner allows to characterize changes of agricultural landscapes due to agricultural practices and climate change consequences.
## Use Cases
* Yield estimation
* Agricultural Monitoring and Food Security
* Commodity Trading
* Sustainable Agriculture Monitoring (including CAP and EUDR)
* Supply Chain Monitoring
* Benchmarking
* Product Supply Forecasting
* Biofuels
* Environmental Impact Assessment
* Proof of Permit and Regulatory Compliance
* Risk Assessment
* Agricultural Insurance (underwriting, pricing, claims validation)
* E\&R (Scientific publications and research grants)
* Field Isolation
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
Loading...
Each request made using the Subscriptions API, delivers a GeoPackage that includes field boundaries for the specified TOI and AOI.
Polygons with an area lower than 50 sqm are removed from the output. Polygons with Maximum Inscribed Circle Diameter (MICD) lower than 30 m are flagged as unreliable.
For more information on the Subscriptions API and code samples, refer to the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
## Additional Resources
[📖Subscriptions API Guide](https://docs.planet.com/develop/apis/subscriptions.md)
[Learn how to work with Planet subscriptions API through the Quickstart guide.](https://docs.planet.com/develop/apis/subscriptions.md)
[🎓Planet University](https://university.planet.com/intro-to-field-boundaries)
[Explore video tutorials about Field Boundaries](https://university.planet.com/intro-to-field-boundaries)
[📰Field Delineation Release](https://medium.com/sentinel-hub/automatic-field-delineation-new-release-1c2938399f0)
[Research and development that led to the new version of Planet Field Boundaries.](https://medium.com/sentinel-hub/automatic-field-delineation-new-release-1c2938399f0)
[📰AI4Boundaries & EuroCrops](https://medium.com/sentinel-hub/utility-of-ai4boundaries-and-eurocrops-as-training-datasets-for-field-delineation-ff514471d067)
[Analysis of training datasets for field delineation.](https://medium.com/sentinel-hub/utility-of-ai4boundaries-and-eurocrops-as-training-datasets-for-field-delineation-ff514471d067)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/field-boundaries/products/)
# Products
## Field Boundaries
Loading...
### Assets
Loading...
### Attributes
More details are available in the [Technical Specification](https://docs.planet.com/data/planetary-variables/field-boundaries/techspec.md#attributes-description)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/field-boundaries/techspec/)
# Technical Specification
## Overview
## Planet's Field Boundaries: A Planetary Variable
The Field Boundaries (FB) dataset is a Planetary Variable™ containing a set of polygons that represents the boundaries of agricultural fields.
Field delineation is the process that generates FBs by automatically tracing the boundaries of agricultural fields from Sentinel-2 satellite imagery with 10 m spatial resolution. An agricultural field is a spatially homogeneous land unit utilized for agricultural purposes, where a single crop is grown.
Planet’s Field Boundaries algorithm leverages the similarity of spatial, spectral, and temporal properties of pixels belonging to the same field. A deep neural network based on the popular U-net architecture is used to estimate the field’s extent, boundary, and the distance of the segmented image pixels to the boundary. The estimated probability images are then combined into a single pseudo-probability image representing the extent of the fields.
In post-processing, the image prediction is converted into vector format, where each polygon represents the extent of a homogeneous agricultural field. The result is a set of closed vector polygons marking the extent of each agricultural field. Additionally, a quality assessment attribute is computed for each estimated FB polygon.
## Inputs
For the specified TOI, Sentinel-2 satellite images are downloaded as well as the cloud masks. Sentinel-2 bands at 10 m spatial resolution are used, specifically B02, B03, B04, and B08.
The dataMask band is used for handling pixels with no-data. No-data pixels are all pixels which lie outside of the area of interest, all pixels for which no source data was found, and all pixels for which source data was found but are invalid.
Additionally, utilized alongside the native Sentinel-2 bands is s2cloudless, a machine learning algorithm for computing cloud masks and probabilities on Sentinel-2 imagery, sampled at 160 m resolution. They are available as Sentinel-2 bands named CLP (cloud probabilities) and CLM (cloud masks).
## Field Boundaries Product
Information is available in the [Product Page](https://docs.planet.com/data/planetary-variables/field-boundaries/products.md)
### Attributes Description
To facilitate characterization and interpretability of the resulting polygons, some attributes are added and a quality assessment attribute is computed for each estimated FB polygon. The attributes are listed in the [table](https://docs.planet.com/data/planetary-variables/field-boundaries/products.md#attributes) and details on these are provided below.
**Polygon ID**
To facilitate downstream usage and indexing of the FB polygons, a unique integer identifier is assigned to each polygon. Uniqueness of the identifier is guaranteed only within a delivered GeoPackage file for a subscribed AOI. The same identifier will correspond to different polygons for different deliveries of the same AOI, or for different AOIs.
**Area**
The area of the polygon in hectares is included as an attribute (1 ha is 10,000 sqm). The area is computed before conversion to the common WGS84 coordinate reference system.
**Maximum Inscribed Circle Diameter (MICD)**
While the polygon area is a general descriptor for the size of a polygon, it carries no information about its shape. While evaluating and validating the FB product, it was observed that the shape of the polygon correlates more with the performance of the algorithm, rather than its size only. This has to do with the limitations in spatial resolution of the input imagery, which affect the minimum side (for example, height or width) of the polygon that can be detected.
A very narrow but long polygon can have a large value of area, but nevertheless cannot be reliably detected by the algorithm due to its narrower side. MICD was identified to be a suitable metric for estimating the polygon width. The maximum inscribed circle is the largest circle which can be inscribed within the polygon, see Figure 2. MICD is added as an attribute, and used to flag polygons of uncertain accuracy.
*Figure 1: Illustration of an example of MICD for three different polygons. The central polygon is unlikely to be correctly delineated despite its non-negligible area, due its width, which is smaller than the Sentinel-2 spatial resolution. This highlights that area is not a good proxy for performance of the algorithm.*
**Circumference-Area ratio (CA ratio)**
A normalized Circumference-Area ratio is added to each polygon to additionally describe its shape. The CA ratio can be used in conjunction to the Area and MICD attributes to identify polygons of circular shape (for example, with CA ratio close to 0), of squared shape (for example, with CA ratio around 1), or of more irregular shape, having CA ratio larger than 10. Examples of CA ratio are shown in Figure 3.
*Figure 2: Examples of polygons with different CA ratios: 0,08 (left), 1,05 (middle) and 45,47 (right).*
**Quality Assessment Attribute**
A quality assessment (QA) attribute denotes polygons with known limitations. The attribute is an unsigned integer. The values presented in the table below are provided for the current version of the FB product.
Table 4: Values and their description of the QA attribute.
| QA Value | Description |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | Polygons for which the validation scores are representative, for example with MICD > 30 m. |
| 1 | Polygons for which the validation scores are not representative, for example with MICD < 30 m. The quality for these polygons is likely to be low. |
| 2 | Polygons that are intersecting the border of the data availability grid. |
The provided example illustrates four types of polygons. Polygons outside of the AOI are removed from the output. The remaining ones (depicted with solid and diagonal fill) intersect with the AOI and are therefore kept in the output. Polygons that are intersecting the border of the data availability grid are also kept in the output and are assigned a value of qa==2. We suggest removing such polygons from further analyses, as they only partially cover the underlying field.
*Figure 3: Example of four types of polygons.*
### Data Availability
The additional output of the FB product includes a data availability map - a vector file suffixed \_da. This map consists of a grid, representing the customer's AOI split during processing. Each grid cell has an attribute called ‘has\_valid\_observations.’ When this attribute is set to ‘false,’ it indicates that there were no valid Sentinel-2 observations available for the TOI defined by the customer. Consequently, the model failed to predict field boundaries within that specific grid cell. On the other hand, when ‘has\_valid\_observations’ is set to ‘true,’ it indicates that valid observations were available for the specific grid cell, leading to the successful production of field boundaries.
Table 6: Data availability map specifications.
| Attribute | Description |
| ------------------------ | ------------------------------------- |
| Type of product | Vector |
| Input data source | Sentinel-2 (10 m) |
| Input data time interval | Output based on 1 month of data (TOI) |
| Attribute | has\_valid\_observations |
## Delivery
The output of FB is a GeoPackage (GPKG), which contains a vector data layer of delineated polygons representing fields within the chosen Area of Interest (AOI). Moreover, Planet provides a data availability map as an additional output.
FB is delivered through the Subscription API into a designated storage cloud bucket. Subsequently, the customer receives a notification regarding the availability of the data.
Table 7: Vector properties of FB outputs.
## Methodology
Planet carries out the following steps to produce boundaries of the agricultural fields:
* split the AOI into a grid to parallelize and speed up processing
* retrieve remote sensing imagery for the time period of interest
* spatially coregister the multiple images
* inference of the pre-trained deep learning model on the input imagery, obtaining pseudo-probability maps of field boundary estimates
* post-processing of the pseudo-probabilities to obtain a single vector file of merged agricultural field boundaries
* compute attributes
*Figure 4: Production pipeline.*
The AOI is split into a regular grid, which allows massive parallelization of the processing. For each grid cell, Planet performs data download, pre-processing, model prediction and post-processing. Predictions across all grid cells are merged in a complete map during the final stages of the process.
Accurate field delineation requires clear-sky observations. For the selected TOI, satellite images, as well as cloud and no-data masks are downloaded for each grid cell using Batch API. Estimates of cloud coverage are produced for each grid cell. If cloudless scenes exist (for example, with a cloud coverage below 10%), only these are considered to generate a consensus. If no cloudless scenes are available, a consensus is generated using all scenes in the grid cell, by only considering pixels not covered by clouds. This is performed in order to ensure that clouds and related artifacts do not affect the estimation of boundaries. When no valid Sentinel-2 observations are available for a specific grid cell during the TOI defined by the customer, the model fails to predict field boundaries within that specific grid cell. In the additional output Data Availability map these grid cells have the value of the has\_valid\_observations attribute set to false.
Co-registration of the input satellite time-series within a grid cell is applied to reduce frame-to-frame misalignments, and therefore to reduce noise when creating a temporal consensus.
Each input Sentinel-2 band is normalized using statistics pre-computed over a large area. Following normalization, a pretrained U-net network, inspired by [Waldner and Diakogiannis (2020)](https://doi.org/10.1016/j.rse.2020.111741), is employed to infer extent, boundary and distance to boundary of each detected agricultural field for each input observation of the time-series. The U-net network has been trained on pre-processed data from the EuroCrops dataset in a separate training phase. As the model is not trained on temporal data, and significant differences may exist in predictions made between different observations, different temporal predictions are temporally merged into a single prediction. The resulting image has continuous values that can be treated as a level set function, and can therefore be thresholded to obtain smooth contours. In the final step, Planet merges vector predictions over grid cells (and over UTM zones), resolving the duplication of vectors in overlapping regions of neighboring grid cells.
To correctly produce field boundaries, an assumption about the dimensional limits of the polygons needs to be made. Polygons of area lower than 50 sqm, for example half the size of a Sentinel-2 pixel, are removed from the database. These are noisy predictions mostly due to post-processing. Very large and very long polygons that spread over large distances may also present an issue for producing accurate results. Maximum Inscribed Circle Diameter (MICD) is the largest circle which can be inscribed within the polygon, and is an intuitive proxy for the width of a field. We mark polygons as unreliable (qa value 1) in Quality Assessment attribute if their MICD is less than 30 meters, which essentially means their minimum/shorter side is less than 30 meters.
For each estimated polygon, Planet computes attributes that facilitate the characterization and analysis of the results for downstream applications. The provided attributes for each polygon are: an ID, area in hectares, MICD, which is used to compute the Quality Assessment attribute, and the Circumference-Area ratio. These attributes can be combined to filter polygons of lower quality by the end user.
### Validation
We evaluated the FB product extensively on the largest source of reference data in Europe, for example, EuroCrops dataset. The dataset is based on GSAA polygons, which have known quality limitations (described in [Utility of AI4Boundaries and EuroCrops as training datasets for field delineation](https://medium.com/sentinel-hub/utility-of-ai4boundaries-and-eurocrops-as-training-datasets-for-field-delineation-ff514471d067) blog post), leading to under-estimation of the delineation performance. However, such a dataset allows us to evaluate the algorithm on a diverse set of samples, in terms of sizes, shapes and semantic definitions. As can be expected due to the limitations of the spatial resolution of the input imagery, the performance increases as the size of the fields increases, with median IoU scores greater than 0.8 for fields having minimum side larger than 150m, reaching a IoU up to 0.98 for for fields with minimum side larger than 240m.
Check out the [validation report](https://planet.widen.net/s/wbbfbnznlv/planet-whitepaper-fieldboundariesvalidationreport-letter) for more detailed information.
### Limitations
When assessing the FB dataset it is crucial to consider the following points about the model:
1. TRAINED FOR DELINEATING ARABLE LAND: the deep learning model was trained to delineate arable land;
2. TRAINING DATA SOURCE: The model was trained on GeoSpatial Aid Application (GSAA) data, annual crop declarations made by European farmers for Common Agricultural Policy (CAP) area-based support measures. This data is not always aligned with boundaries seen on the ground at a certain acquisition and can be incomplete and outdated, since national paying agencies are not yet obliged to maintain such a dataset;
3. RESOLUTION LIMITATION: Predictions are based on Sentinel-2 imagery with a 10 m spatial resolution.
The following limitations have been identified:
* The majority of the EuroCrops data covers central and northern European countries, therefore the model has been primarily exposed to, and trained on, data from these regions.
* The model was trained to delineate agricultural areas (for example, annual crops), therefore the quality of field boundaries over grassland (pastures, meadows) and areas with permanent crops (orchards, vineyards, olive groves) is lower.
* The FBs are constructed from cloud-free observations over the AOI from the time interval of one month. In some cases over cloudy areas the single-month approach might not produce fields over some areas, as shown in the availability maps. A vector file containing a data availability map that highlights areas lacking valid Sentinel-2 observations for field boundary prediction is provided. It assists customers in identifying data gaps.
* The performance is less favorable in arid regions, particularly evident in Mediterranean countries, attributed to the challenge of less distinct field boundaries in arid landscapes, and a lack of training samples in such areas.
* Due to the model being based on Sentinel-2 imagery with a 10 m resolution, predictions for fields with MICD less than 30 m may be of low quality or, in some cases, may be missing. For this reason, a data quality flag will identify such polygons.
* Some resulting field boundaries might be joined at either end of the field as a result of the super-resolution layers. This generates larger field boundaries that are however not fully disconnected.
* Predictions might present holes, which in some cases can correspond to actual non-arable land objects, such as trees, large boulders or wind mills, but can also in some cases correspond to uncertain boundaries not completely detected.
*Figure 5: Example of undesired holes due to uncertain boundaries on the left, while the right figure shows holes that correctly detect non-arable land objects.*
* The FB dataset might not be suitable for variable rate application, as the polygons can not compare to digitized polygons in terms of quality and size, due to limitations of the spatial resolution of the input Sentinel-2 imagery. They tend to be systematically smaller than the ground truth field boundaries, and they exhibit rounded corners.
## Frequently Asked Questions
#### What imagery is used to create the Field Boundaries PV and why?
The first version of Field Boundaries uses data from Sentinel-2 with 10 m resolution. Historically, FBs were created by Sinergise within an European Commission funded research project on Sentinel-2, and the results for large fields are reliable even with using Sentinel-2 data.
#### Which TOI is recommended?
We generally suggest choosing a month that represents the early growing phase of crops, such as May or June for the northern hemisphere.
#### Does the Field Boundary PV work for smallholder farms?
V1 of the Field Boundary PV is not well suited to smallholder farms due to the 10m resolution of the Sentinel data that was used to create this first version of the product.
#### Field Boundaries fault towards underestimation of area versus overestimation. How much area is underestimated on average?
There is high variability depending on the shape and size of the polygons, but on average around 10 %.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/)
# Forest Carbon Diligence
The Forest Carbon Diligence product is composed of a bundle of data resources: Canopy Height, Canopy Cover, and Aboveground Live Carbon at 30-meter spatial resolution. These data resources are produced annually over the entire landmass of the Earth (between 75° N and 60° S). We use an extensive library of airborne LiDAR to train deep learning models to predict canopy height and canopy cover from satellite imagery. We use these predictions paired with 11 million spaceborne lidar (GEDI) footprints to train a model to estimate aboveground live carbon. The archive currently extends back to 2013. See the Technical Specification for more details.
## Basic Facts
| **Property** | **Info** |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spatial resolution | 30 m |
| Sensor/Input Data | Airborne LiDAR, LiDAR (GEDI), Landsat 8, Sentinel 2, ALOS-PALSAR-2, Wood density, Digital Elevation Model (DEM) |
| Revisit time | Annual |
| Spatial coverage | Global |
| Data availability | Global since 2013 |
| Available measurements | Canopy Height, Canopy Cover, and Aboveground Live Carbon |
| Common usage/purpose | Planet's Forest Carbon Diligence products quantify—globally and annually—how much carbon is stored in trees, the area occupied by trees, and how tall they are. |
Forest Carbon Diligence Data Releases
New Forest Carbon Diligence data is released mid year, depending on the release of [ALOS PALSAR data](https://www.eorc.jaxa.jp/ALOS/en/dataset/fnf_e.htm). See the [changelog](https://docs.planet.com/develop/changelog.md) for the latest releases and to stay notified of new releases.
## Use Cases
**Forest Carbon Projects** - Forest Carbon Diligence enables the quantification of carbon stocks and forest area over time to accurately quantify losses and gains. The accuracy is comparable to airborne approaches but the data is orders of magnitude less expensive while being globally available, providing a cost-effective solution for comprehensive monitoring. The high precision, accuracy, and granularity offered by the Forest Carbon Diligence provides an objective foundation for identifying and implementing improvements in carbon initiatives.
**Deforestation Monitoring for Supply Chains** - Forest Carbon Diligence data provides comprehensive monitoring by quantifying deforestation on a high-frequency cadence. Stakeholders can report on their supply chains to forests globally with unprecedented granularity and confidence. In the context of the EU Deforestation Regulation (EUDR), the Forest Carbon Diligence dataset offers more precise data, aligning with the regulation’s focus on defining deforestation boundaries and providing crucial context regarding forest degradation and carbon loss.
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
#### Canopy Height 30m
Loading...
#### Canopy Cover 30m
Loading...
#### Aboveground Carbon Density 30m
Loading...
For each request you make using the Subscriptions API, you'll get a dataset that includes forest carbon estimations for the specified TOI and AOI.
For more information on the Subscriptions API and code samples, see the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
### Subscriptions Time of Interest
The table below provides an example of the temporal periods and the date tags associated with Forest Carbon Diligence data. When creating a subscription, the 'start\_time' must be set to the date tag or earlier, while the 'end\_time' must be set to a date after the date tag.
| **Year** | **Start** | **End** | **Date Tag** |
| -------- | ---------- | ---------- | -------------------- |
| 2023 | 2023-01-01 | 2023-12-31 | 2023-01-01T00:00:00Z |
## Example Workflows
Below are links to a series of Python workflows that highlight ways you can access and analyze the Forest Carbon Diligence data.
## Analyze Historical Trends Without Downloading Data
This workflow walks you through how to create a subscription with the Subscriptions API, deliver the data to a cloud bucket, and then retrieve and analyze the data directly from the cloud (for example, without having to download it locally).
[Go to Guide →](https://docs.planet.com/guides/analyze-historical-forest-carbon.md)
## Mapping Forest Cover Change via Planet Insights Platform
This workflow demonstrates how to map changes in forest cover between two dates based on the Forest Carbon Diligence product using the Processing API.
[Go to Guide →](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/use_cases/forest_carbon_dilligence/pv-forest-change.ipynb)
## Additional Resources
[📖Technical Specification](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/techspec.md)
[Get the details in the Forest Carbon Diligence Technical Specification](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/techspec.md)
[🎓Planet University](https://university.planet.com/intro-to-forest-carbon-diligence-and-monitoring)
[Get Started with Planet’s Forest Carbon Planetary Variable product for: global tree height, canopy cover and carbon raster.](https://university.planet.com/intro-to-forest-carbon-diligence-and-monitoring)
[📓Guides](https://docs.planet.com/guides.md)
[Visit our Guides page to find related Jupyter Notebooks for hands-on learning.](https://docs.planet.com/guides.md)
[📚APIs](https://docs.planet.com/develop/apis/subscriptions.md)
[Learn more about the Planet Subscriptions API to obtain Forest Carbon data.](https://docs.planet.com/develop/apis/subscriptions.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/products/)
# Products
Below you will find a list of Data Resources available for the Forest Carbon Diligence product. Each Data Resource has a series of associated Data Assets. We are continuously working to improve the product, and periodically release new versions. We provide access to older versions of our products, but only produce data using the latest version at new timesteps. We recommend using the latest product version and reviewing the [version history in the changelog](https://docs.planet.com/develop/changelog.md?tag=forestCarbonDiligence) associated with each release.
## Canopy Height 30m
Loading...
## Canopy Cover 30m
Loading...
## Aboveground Carbon Density 30m
Loading...
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/sandbox/)
# Forest Carbon Diligence Sandbox Data
This Planet Sandbox Data collection for Forest Carbon Diligence provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| ---------------------------------------- | ----------------------------------------------- | ----------------------------------------- | ----------------------- |
| CANOPY\_HEIGHT\_v1.1.0\_30 | Planet Sandbox Data - PV FCD Canopy Height | BYOC-f3312c82-edea-42a1-8c9d-ada86ddcc857 | 2013-01-01 - 2017-01-01 |
| CANOPY\_COVER\_v1.1.0\_30 | Planet Sandbox Data - PV FCD Canopy Cover | BYOC-e3d2a21c-cb75-4311-86ac-024385c85b9c | 2013-01-01 - 2017-01-01 |
| ABOVEGROUND\_CARBON\_DENSITY\_v1.1.0\_30 | Planet Sandbox Data - PV FCD Aboveground Carbon | BYOC-cc31cada-80d8-46fe-a746-43ac2f87b5da | 2013-01-01 - 2017-01-01 |
## Planet Sandbox Data Areas
This collection includes 4 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 4 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ----------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Pará, North Region, Brazil | 568 | 2015-01-01 – 2017-01-01 | -6.77, -52.37 |
| Iowa, United States | 581 | 2015-01-01 – 2017-01-01 | 41.30, -93.95 |
| Western Australia, Australia | 587 | 2015-01-01 – 2017-01-01 | -31.92, 116.15 |
| Nouvelle-Aquitaine, Metropolitan France, France | 599 | 2015-01-01 – 2017-01-01 | 44.73, -0.68 |
[Download GeoJSON](https://docs.planet.com/data/planetary-variables/forest_carbon_diligence/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=44.7345\&lng=-0.676\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=cc31cada-80d8-46fe-a746-43ac2f87b5da\&fromTime=2017-01-01T00%3A00%3A00.000Z\&toTime=2017-01-01T23%3A59%3A59.999Z\&layerId=ABOVEGROUND-CARBON-DENSITY\&demSource3D=%22MAPZEN%22)
Bordeaux, France
2015-01-01 to 2017-01-01
599km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=44.7345\&lng=-0.676\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=cc31cada-80d8-46fe-a746-43ac2f87b5da\&fromTime=2017-01-01T00%3A00%3A00.000Z\&toTime=2017-01-01T23%3A59%3A59.999Z\&layerId=ABOVEGROUND-CARBON-DENSITY\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=-6.7652\&lng=-52.3763\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=e3d2a21c-cb75-4311-86ac-024385c85b9c\&fromTime=2017-01-01T00%3A00%3A00.000Z\&toTime=2017-01-01T23%3A59%3A59.999Z\&layerId=CANOPY-COVER\&demSource3D=%22MAPZEN%22)
São Félix do Xingu, Brazil
2015-01-01 to 2017-01-01
568km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=-6.7652\&lng=-52.3763\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=e3d2a21c-cb75-4311-86ac-024385c85b9c\&fromTime=2017-01-01T00%3A00%3A00.000Z\&toTime=2017-01-01T23%3A59%3A59.999Z\&layerId=CANOPY-COVER\&demSource3D=%22MAPZEN%22)
[](https://insights.planet.com/analyze/browser/?zoom=12\&lat=41.2969\&lng=-93.959\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=f3312c82-edea-42a1-8c9d-ada86ddcc857\&fromTime=2016-01-01T00%3A00%3A00.000Z\&toTime=2016-01-01T23%3A59%3A59.999Z\&layerId=CANOPY-HEIGHT\&demSource3D=%22MAPZEN%22)
Des Moines, USA
2015-01-01 to 2017-01-01
581km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=12\&lat=41.2969\&lng=-93.959\&themeId=PLANET_SANDBOX\&visualizationUrl=https%3A%2F%2Fservices.sentinel-hub.com%2Fogc%2Fwms%2Ff006c031-60da-4262-bdf7-6fc4f1532d13\&datasetId=f3312c82-edea-42a1-8c9d-ada86ddcc857\&fromTime=2016-01-01T00%3A00%3A00.000Z\&toTime=2016-01-01T23%3A59%3A59.999Z\&layerId=CANOPY-HEIGHT\&demSource3D=%22MAPZEN%22)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/techspec/)
# Technical Specification
Figure 1: Changes in total aboveground carbon stocks over a simulated forest carbon project boundary in Ucayali, Peru.
This document describes the Planet Forest Carbon Diligence product. It is intended for users of geospatial data interested in working with Forest Carbon Diligence, which estimates aboveground carbon density, canopy height, and canopy cover.
Planet’s Forest Carbon Diligence products quantify—globally and annually—how much carbon is stored in trees, the area occupied by trees, and how tall they are. This is done using cutting edge machine learning models that fuse a rich archive of historical satellite observations with high quality, laser-derived reference data. Modeling benchmarks include an extensive archive of high resolution airborne LiDAR data for training and evaluating the height and cover models, and a global carbon dataset derived from two spaceborne LiDAR missions.
This novel approach builds on decades of open data and open science, and was designed to maximize accuracy, transparency, and trust based on well-known standards.
Mapping and monitoring forest carbon dynamics comes with uncertainty. Forest Carbon Diligence embraces uncertainty by reporting multiple pixel-level uncertainty metrics, including observation quality scores and prediction intervals for each dataset, each designed to support uncertainty propagation into user workflows.
Jurisdictional and voluntary carbon monitoring programs require high quality, accessible, and globally consistent data on the state of the world’s forests, and how they are changing. The Forest Carbon Diligence products were designed to support these needs. Planet is committed to transparency and open science, and has published a full methods and validation report describing this product ([Anderson et al., 2025](https://doi.org/10.32942/X2KW7H)).
**The features of Planet’s Forest Carbon Diligence data:**
* A multi-year, GEDI-like forest carbon data product with wall-to-wall spatial coverage.
* 12-year series quantifying annual patterns of aboveground carbon density, canopy cover and canopy height.
* Full global coverage of the terrestrial biosphere at 30m resolution.
* All models calibrated and evaluated with high quality reference data.
* \>2 million km2 of airborne LiDAR used to train canopy cover and canopy height models.
* \>80 million spaceborne LiDAR (GEDI, ICESat-2) samples used to train aboveground carbon model.
* Novel cloud masking, pixel selection, multi-sensor fusion, and temporal harmonization techniques developed to minimize year-over-year measurement variability.
* Calibrated, pixel-level prediction intervals support uncertainty propagation to downstream analyses.
* Day-of-measurement and satellite data quality scores provide insights into prediction timing and quality.
* GEDI-based model calibration enables independent validation of our product and simplifies intercomparison with a well-known global standard.
## Product Specifications
Table 1: Forest Carbon Diligence product specification
| Specification | Value |
| ------------------- | ------------------------------------------------------- |
| Metrics | Canopy cover, canopy height, aboveground carbon density |
| Spatial extent | Global land mass > -60S and < 75N, excluding ice sheets |
| Spatial resolution | 0.00025° (± 30 x 30 m) |
| Temporal extent | 2013 - Present. |
| Temporal resolution | Annual |
| Temporal period | Jan 01 - Dec 31. |
Canopy cover quantifies the percentage of area occupied by trees within a pixel, where a tree is defined as vegetation 5 meters or taller. This metric will be most sensitive to tree clearing events like timber harvest or deforestation, but is also sensitive to seasonal leaf-on variation and to drought.
Canopy height quantifies the average stand height of trees within each pixel. Because this is a spatial average over a moderate resolution, the modeled height values are shorter than the tallest individual tree within a pixel.
Aboveground carbon density quantifies the expected density of carbon stored in woody biomass across the landscape, measured in mass per area (megagrams of carbon per hectare). It is not a direct estimate of the total carbon in that pixel, as the spatial resolution of each pixel is less than one hectare. To estimate total carbon in a pixel, users should normalize these values to account for the size of each pixel, or average the density values to 1 hectare in an equal area projection.
## Asset Properties
This tables specifies the properties of the data assets delivered by the [Planet Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md).
Table 2: Forest Carbon Diligence data resource properties
| Metric | Asset Name | Units | Type | Typical Range | No Data Value | Band Count |
| -------------------------- | ---------- | ----- | ----- | ------------- | ------------- | ---------- |
| Canopy Cover | cc | % | UINT8 | 0 - 100 | 255 | 1 |
| Canopy Height | ch | m | UINT8 | 0 - 50 | 255 | 1 |
| Aboveground Carbon Density | acd | Mg/ha | INT16 | 0 - 300 | 32767 | 1 |
| CC Uncertainty | cc-uc | % | UINT8 | 0 - 100 | 255 | 2 |
| CH Uncertainty | ch-uc | m | UINT8 | 0 - 80 | 255 | 2 |
| ACD Uncertainty | acd-uc | Mg/ha | INT16 | 0 - 400 | 32767 | 2 |
| CC Change Detection | cc-change | n/a | UINT8 | 0 - 2 | 255 | 1 |
| CH Change Detection | ch-change | n/a | UINT8 | 0 - 2 | 255 | 1 |
| Quality Flags | acd-qa | n/a | UINT8 | 0 - 224 | 255 | 1 |
| Day of Year | acd-doy | day | INT16 | 0 - 366 | 32767 | 1 |
The `cc`, `ch`, and `acd` assets contain the predicted values of canopy cover, canopy height, and aboveground carbon density in their natural units. Quality flag and day of year data are provided for all metrics (for example, `cc-qa`, `ch-qa`, `acd-qa`). They are only listed once in the table because they contain duplicate information across metrics.
### Uncertainty Bounds
Table 3. Uncertainty band descriptions
| Uncertainty Band | Description |
| ---------------- | ---------------------------------------- |
| Q05 (band 1) | Lower prediction bound (5th percentile) |
| Q95 (band 2) | Upper prediction bound (95th percentile) |
Uncertainty data are provided as calibrated 90% prediction intervals for each pixel in each year. These values are provided in the same units as their respective reference data. In other words, the pixel values and units are consistent between ACD and ACD-UC, between CC and CC-UC, and between CH and CH-UC.
### Change Assets
Table 4. Change detection asset pixel values
| Pixel Value | Description |
| ----------- | -------------------------------------------------------------------- |
| 0 | No change observed |
| 1 | Fast change observed, such as deforestation or wildfire disturbance |
| 2 | Slow change observed, such as reforestation or natural forest growth |
The cc-change and ch-change assets classify annual changes that occur. These are the product of a time series model, which estimates whether a pixel experiences no change, fast change, or slow change from year to year.
### Quality Flags
Table 5. QA pixel values
| Pixel Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0-100 | Estimated observation quality. Low values indicate low quality observations, like hazy, cloudy, or off-season measurements. High values indicate high quality observations, like clear, cloud-free measurements captured during peak greenness. |
| 213-214 | Year of closest available measurement. Some parts of the world experience persistent cloud cover or haze year-round, resulting in 0 valid measurements in a year. In these cases, the nearest-in- time clear observation is used. For example, 213 refers to 2013, and 222 refers to 2022 |
Planet provides pixel-level QA data to indicate the relative quality of each pixel’s satellite data observation. These values are provided to diagnose whether observed changes might be the result of low quality measurements.
### Day of Year
Table 6. DOY pixel values
| Pixel Value | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | No measurement available. These primarily occur over water bodies where data are not provided. |
| 1-366 | Julian day of the measurement. If this pixel has been filled with a nearest-in-time observation from a nearby year, the day of that year’s observation is reported. |
Day of year pixel values encode the calendar day of the satellite observation. Since the number and quality of observations vary with the number of cloud-free observations, differences in observation dates between adjacent pixels can be large. This information can indicate seasonal differences between observations. It can also indicate whether an observation occurred prior to or following a disturbance.
## Input Data
Figure 2: Extent and count of the airborne LiDAR data used for model training and evaluation.
The Forest Carbon Diligence product uses multi-source, multi-scale earth observations data from a series of publicly available resources and derivative data products. The metrics derived from airborne and spaceborne LiDAR were treated as response variables, which were modeled using optical, radar, and derived feature data.
Table 7: List of inputs for Forest Carbon Diligence production
| Product | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Airborne LiDAR | Point cloud data processed to canopy height and canopy cover rasters at 1m resolution then resampled to 30m resolution for model training |
| Spaceborne LiDAR | [GEDI L4A](https://doi.org/10.3334/ORNLDAAC/1907) and [ICESat-2 ATLAS](https://doi.org/10.5067/D2E2L5GK7ER3) encode modeled estimates of aboveground biomass density. GEDI provides coverage over mid latitudes (<51.6 N, >51.6 S) and ICESat-2 provides coverage for high latitudes (>44.4 N) |
| Surface Reflectance | The full scene archive of Landsat-8, Landsat-9, and Sentinel-2 were processed to BRDF-adjusted surface reflectance using FORCE ([Frantz 2019](http://doi.org/10.3390/rs11091124)). These scenes were masked for clouds, shadows, and haze and composited into annual best-available-pixel mosaics |
| L-band RaDAR backscatter | L-band SAR mosaics from [ALOS PALSAR-2](https://www.eorc.jaxa.jp/ALOS/en/dataset/fnf_e.htm). Both HH and HV polarizations were downloaded for each year. No rescaling or normalization was applied to these data |
| Wood density | Wood density estimates were used as features in the canopy height and canopy cover models. These estimates encode coarse scale (\~1 km) biogeographic information that might inform the mapping from remote sensing data to forest structural traits |
| Digital Elevation Model (DEM) | Copernicus [GLO-30](https://doi.org/10.5270/ESA-c5d3d65) DEM are used for most of the global landmass, ALOS [AW3D30](https://www.eorc.jaxa.jp/ALOS/en/dataset/aw3d30/aw3d30_e.htm) is used where GLO-30 does not provide data |
## Methods
Figure 3: Workflow diagram for Forest Carbon Diligence illustrating the flow of data for delivery.
The Forest Carbon Diligence products were created using multi-scale, publicly available EO data. These datasets were modeled in a stepwise process to balance the strengths and limitations of each dataset. Fully detailed methods, validation results, and data sources are described in [Anderson et al., 2025](https://doi.org/10.32942/X2KW7H).
### Airborne LiDAR Data
Point cloud data were downloaded from a series of open data platforms, reprojected to a consistent coordinate system (EPSG:6933) and normalized in the Z dimension to height above ground. Ground point classifications provided in the source data were used for normalization. Buildings, bridges, noise, and other non-vegetation classes were removed from processing using the point classifications provided in the source data, when present. For datasets with no prior classifications, custom building and noise classifiers were used. Canopy height and canopy cover were rasterized from the normalized point cloud data at 1 m native resolution. Overall, 2,234,400 km2 of LiDAR data were processed and extracted for model training and evaluation (Fig. 2).
Canopy height (m) was calculated as the tallest point within each grid cell using a modified pit-free canopy height model algorithm ([Khosravipour et al. 2014](https://doi.org/10.14358/PERS.80.9.863)). This is not restricted to trees as there is no height or size threshold for inclusion; the height of the tallest vegetation at each cell is recorded, be it grass, shrub, or tree.
Canopy cover (%), also referred to as canopy density, is calculated as the number of LiDAR returns 5m and above divided by the total number of returns within each grid cell. This threshold tracks overstory vegetation cover, and can be interpreted as a proxy for canopy closure; cover increases in proportion to overstory foliage volumes. It can be interpreted as the complement to canopy gap fraction (CC = 1 − GF; [Coomes et al. 2017](http://dx.doi.org/10.1016/j.rse.2017.03.017)).
Average resampling to a lower resolution reduces the range of observed canopy height values to approximately 0-40 m. Average resampling was selected because this implicitly weights pixel-level tree height measurements by crown diameter, and the combination of these variables is correlated with aboveground biomass across ecosystems ([Jucker et al. 2018](https://doi.org/10.1111/gcb.13388)).
### Spaceborne LiDAR Data
AGBD estimates from GEDI v2.1 ([Dubayah et al. 2022](https://doi.org/10.3334/ORNLDAAC/2056)) and ICESat-2 ATLAS ([Montesano et al. 2024](https://doi.org/10.5067/D2E2L5GK7ER3)) were downloaded, merged, and organized into a harmonized dataset using a global equal area tile grid (see Gridding and Sampling). These two sources of AGBD estimates are complementary, with overlap, as GEDI provides coverage over mid latitudes (<51.6 N, >51.6 S) and ICESat-2 provides coverage for high latitudes (>44.4 N).
A series of quality filters were applied to the GEDI observations, selecting samples from power beams, collected at night, excluding steep slopes, and excluding orbits with high geolocation error. ICESat-2 data were filtered by the data providers. Additional outlier detection was applied to both GEDI and ICESat-2 observations, which identified and removed anomalously tall RH98 observations, particularly over sparsely arbored areas.
Overall, 586 million GEDI observations and 15 million ICESat-2 observations were retained after filtering (30% and 99% of the original observations, respectively). A final spatially balanced random sampling step yielded 81.6 million waveforms to be used for training and evaluation, reducing bias in oversampled regions and better approximating a geographically uniform random sample ([Meyer and Pebesma 2022](https://doi.org/10.1038/s41467-022-29838-9)).
### Surface Reflectance
Multispectral surface reflectance data provided 6 of the 9 feature bands used for the forest structure models. Surface reflectance is sensitive to patterns of vegetation growth and structure, with optical variation driven by a combination of leaf-level and canopy-level growth and structure metrics ([Jordan 1969](https://doi.org/10.2307/1936256), [Knipling 1970](https://doi.org/10.1016/S0034-4257\(70\)80021-9), [Asner 1998](https://doi.org/10.1016/s0034-4257\(98\)00014-5), [Dalagnol et al. 2023](https://doi.org/10.5194/essd-15-345-2023)).
The full scene archives of Landsat-8, Landsat-9, Sentinel-2A and Sentinel-2B were downloaded from public cloud storage. Each scene was processed to nadir BRDF-adjusted surface reflectance using the FORCE atmospheric correction and normalization algorithm ([Frantz 2019](https://doi.org/10.3390/rs11091124)). FORCE produces a scene-level QA mask classifying cloud, shadow, haze, water, and snow using a modified version of FMask ([Qiu et al. 2019](https://doi.org/10.1016/j.rse.2022.113375), [Skakun et al. 2022](https://doi.org/10.1016/j.rse.2022.112990)). Sentinel-2 scenes were average resampled to match Landsat’s resolution. To reduce false negative cloud detections, a custom cloud and shadow mask was applied to update each scene’s QA mask. Only the six bands shared across instruments were retained: \[B, G, R, NIR, SWIR-1, SWIR-2].
Annual surface reflectance mosaics were created beginning in 2013, which marks the launch of Landsat-8 ([Roy et al. 2014](https://doi.org/10.1016/j.rse.2014.02.001)). These mosaics were created using a custom best-available-pixel compositing method, adapted from White et al. 2014. Best-pixel methods show strong temporal consistency compared to percentile-based composites, though this may come at the expense of radiometric uniformity ([Matasci et al. 2018](https://doi.org/10.1016/j.rse.2018.07.024)).
The following quality metrics were used:
* **Haze score**. Aerosol optical depth (AOD) estimates from FORCE were used to indicate haze. Quality scores were set inversely proportional to AOD scores, where lower AOD indicates a higher quality score.
* Distance to cloud score. Some cloud edges are not correctly classified by the strict cloud mask, so the euclidean distance to each cloudy pixel downranked pixels close to cloud detections.
* **Solar zenith angle score**. Sun-sensor geometry is the primary driver of variation in surface reflectance, leading to large differences in observation conditions over the year, especially at high or low latitudes. Solar zenith angle was used as a quality metric to prioritize scenes collected during well-lit observation conditions, which improves retrieval of vegetation structural information ([Dalagnol et al. 2023](https://doi.org/10.5194/essd-15-345-2023)).
* **Day of year score**. Because vegetation varies throughout the year in response to seasonal change, a day of year score was defined to prioritize spring measurements.
* **Sensor score**. Landsat scenes were ranked lower than Sentinel-2 scenes because the Sentinel-2 cloud mask reports higher precision scores and includes fewer false negatives ([Frantz et al. 2018](https://doi.org/10.1016/j.rse.2018.04.046)).
The pixel composite method addressed three needs.
First was to maximize consistency in the observation conditions for each pixel. The compositor included scoring factors based on sun angle, expected time of peak greenness, distance to clouds, aerosol density, and instrument type. Pixel quality increased as solar elevation increased, at times closest to peak greenness, as aerosol content decreased, and for Sentinel-2 observations over Landsat-8/9 observations.
The second goal of the compositor was to provide a quantitative flag for observation quality. Pixel quality scores provide information regarding the expected reliability of each observation, allowing users to filter or weight observations based on pixel quality.
Finally, the compositor records the Julian day of the best pixel, providing a timestamp for when each observation occurred.
### L-Band RaDAR, Wood Density, and Elevation Data
Annual, radiometrically balanced L-band Synthetic Aperture Radar mosaics from ALOS-PALSAR-2 were downloaded from JAXA’s HTTP server. The HH and HV polarizations comprise 2 of the 9 total predictor bands used for the canopy cover and canopy height models. Active microwave measurements are directly sensitive to aboveground plant water content, and L-Band measurements in particular are typically sensitive to the water content of large, woody biomass components, like tree trunks and branches, indirectly measuring key components of stand-level vegetation structure ([Shimada et al. 2011](https://doi.org/10.1109/JSTARS.2010.2077619), [Konings et al. 2019](http://dx.doi.org/10.1111/nph.15808)). The HH/HV polarization data were not transformed, save for data type and nodata value harmonization across datasets.
Global estimates of wood density were generated at a 1 km resolution via gradient boosted regression of field-observed wood density against principal-component normalized WorldClim and Soilgrids data. This is the final predictor used for the canopy cover and canopy height models, and was included as an index of plant community biogeography to identify non-stationary relationships between target and predictor variables by vegetation type ([Hawkins 2011](https://doi.org/10.1111/j.1365-2699.2011.02637.x)). In total 396,694 field inventory plots were used for training, including data from national forest inventories, ecological monitoring networks, research consortiums, and open data repositories.
Elevation data were used as a predictor for the aboveground carbon density model. This allowed the model to learn nonstationary carbon-topography relationships at local and regional scales, capturing fine-scale topoedaphic drivers of carbon storage in slopes and floodplains ([Marvin et al. 2014](https://doi.org/10.1073/pnas.1412999111), [Taylor et al. 2015](https://doi.org/10.1371/journal.pone.0126748), [Jucker et al. 2018](https://doi.org/10.1111/ele.12964)) and along elevation gradients ([Asner et al. 2014](https://doi.org/10.5194/bg-11-843-2014), [Mahli et al. 2017](https://doi.org/10.1111/nph.14189), [Marifatul Haq et al. 2022](https://doi.org/10.1016/j.foreco.2022.120442)). Elevation data were primarily sourced from the Global 30 m Copernicus Digital Elevation Model ([ESA 2022](https://dataspace.copernicus.eu/explore-data/data-collections/copernicus-contributing-missions/collections-description/COP-DEM)). Since this dataset does not include data over Armenia and Azerbaijan, values for those countries were derived from the ALOS World-3D DEM ([Tadono et al. 2014](https://www.eorc.jaxa.jp/ALOS/en/dataset/aw3d30/aw3d30_e.htm)).
### Canopy Height and Canopy Cover Models
Deep learning regression models were trained to predict mean canopy height and canopy cover independently at 30 m nominal resolution using surface reflectance, HH/VV backscatter, and wood density data as feature variables and airborne LiDAR as response variables. The feature and response variables were normalized to a common range using robust scaling. U-Net convolutional neural network architectures were selected for their robust performance in mapping ecological patterns from EO data ([Ronneberger et al. 2015](https://doi.org/10.1007/978-3-319-24574-4_28), [Broderick et al. 2019](https://doi.org/10.1016/j.tree.2019.03.006), [Kattenborn et al. 2021](https://doi.org/10.1016/j.isprsjprs.2020.12.010), [Wagner et al. 2024](https://doi.org/10.3390/rs12101544)).
Training data were generated by randomly sampling 128x128 pixel tiles from regions with coincident airborne LiDAR data. The year of the satellite data closest to the LiDAR acquisition was used for temporal matching. A total of 1,099,559 samples were extracted at an average sample density of 2 points per square kilometer using uniform random geographic sampling. Samples were randomly assigned to training/validation sets (67%) or interval calibration/testing (33%) sets. The training/validation data were then randomly split 70/30, and the interval calibration/testing data were randomly split 20/80.
Training data were used to fit model parameters. Validation data were used to approximate out of sample predictive performance during training. Interval calibration data were used in conformal inference to generate 90% prediction intervals. Test data were used to evaluate predictive performance.
### Time Series Model
Figure 4: Statistical model for estimating canopy height and canopy cover over time. (A) A time series is generated from the raw predictions for times t=1, … T. (B) Three models are fit for each pixel: a constant model to represent the mean (blue), a changepoint model to represent sudden change (red), and a spline model to represent gradual change (orange). (C) The preferred model for each pixel is used to generate expected values (green) and standard errors (blue) for each time step.
The Diligence U-net models predict height and cover independently for each year, and these predictions contain non-structural variation related to phenology, illumination, and sensor calibration. This residual prediction variation was minimized using statistical models. For each pixel, three models were fit (Fig. 4):
* A constant-in-time model, which represents stability over time
* A spline model, which represents gradual change
* A changepoint model, which represents fast change
The constant model assumes that all variation in predictions is due to noise, and assumes height or cover remains stable over time or when changes are minimal relative to prediction noise (for example, slow growth that is not detectable). The spline and changepoint models capture slow and fast changes, respectively. Regularized B-splines are used to estimate non-linear trends, while the changepoint model included an additional discrete change point parameter at the timestep with the greatest change in predicted height or cover.
The preferred model for each pixel was selected using Akaike's Information Criteria (AIC). An additional heuristic was applied to reduce noise: if the coefficient of variation (CV) over time for the selected model's predictions is below a threshold, the constant-in-time model was selected. This CV threshold is a hyperparameter tuned alongside the AIC threshold. Once a preferred model was selected for each pixel, predictions were generated and the standard errors were used to quantify pixel-level uncertainty for height and cover.
Time series outputs for each year are provided as an additional data asset, with categorical classes mapping no change, fast change, and gradual change (classes \[0, 1, 2], respectively).
### Canopy Height and Canopy Cover Uncertainty
Standard errors from the height and cover time series models were used to construct 90% prediction intervals:
$[y_{pred} - \widehat{q} \cdot \sigma_{pred}, y_{pred} + \widehat{q} \cdot \sigma_{pred}]$
where $y_{pred}$ is a predicted value from the time series model, $\sigma_{pred}$ is the standard error of the prediction, and $\widehat{q}$ is a parameter estimated using withheld data via split conformal inference.
Split conformal inference uses disjoint partitions of a dataset to produce well-calibrated prediction intervals. These are 90% prediction intervals that contain the true value approximately 90% of the time ([Angelopolous and Bates 2021](https://doi.org/10.48550/arXiv.2107.07511)).
A calibration dataset is used to estimate $\widehat{q}$, a scalar quantity that determines the width of the interval relative to the standard error to achieve 90% coverage. After generating predictions with $\widehat{q}$, empirical interval coverage is quantified on a spatially non-overlapping test set. Test set coverage was 90.0% for canopy cover and 90.1% for canopy height.
### Aboveground Carbon Density Model
Light gradient-boosting machine (LightGBM) regression models were trained to predict GEDI L4A and ICESat-2 aboveground biomass as a function of predicted mean canopy height, canopy cover, elevation, and location. Location data were encoded using SatCLIP positional embeddings ([Klemmer et al. 2023](https://doi.org/10.48550/arXiv.2311.17179)).
The relationships between forest structure and aboveground biomass vary across plant communities, biomes, and topographic gradients, and these shifting relationships are explicitly encoded in the GEDI L4A biomass algorithm ([Jucker et al. 2018](https://doi.org/10.1111/gcb.13388), [Duncanson et al. 2022](https://doi.org/10.1016/j.rse.2021.112845), [Kellner et al. 2023](https://doi.org/10.1029/2022EA002516), [Ma et al. 2023](https://doi.org/10.1038/s41477-023-01543-5)). Incorporating location features into a tree-based regression model can represent multiple nonstationary relationships: specifically, between predictors and both the mean biomass density and its associated uncertainty ([Hawkins, 2011](https://doi.org/10.1111/j.1365-2699.2011.02637.x)).
10-fold spatial cross validation was used to assess out-of-sample predictive performance, where each of the 7,408 tiles containing GEDI or ICESat-2 biomass estimates were assigned to one of ten partitions ([Meyer and Pebesma 2022](https://doi.org/10.1038/s41467-022-29838-9)). For each fold, 5% of the training data were randomly withheld for uncertainty calibration.
Model hyperparameters were evaluated using Bayesian optimization of cross-validation RMSE on a random 25% of data. The number of trees, the leaves in each tree, as well as both L1 and L2 regularization were modified. Final hyperparameter selection was also informed by visual inspection of predictions and external intercomparisons.
Uncertainty was quantified via conformalized quantile regression, which yielded 90% prediction intervals where interval widths vary nonlinearly as a function of model predictors ([Romano et al. 2019](https://doi.org/10.48550/arXiv.1905.03222)). In particular, LightGBM quantile regressors were fit to estimate the 5% and 95% quantiles, then conformalized to obtain prediction intervals with strong coverage guarantees on unseen data ([Angelopolous and Bates 2021](https://doi.org/10.48550/ARXIV.2107.07511)).
Conformalized quantile regression was selected for two reasons. First, nonstationary errors were expected to vary nonlinearly as a function of model inputs, including location. Second, reported uncertainties for footprint-level biomass estimates generally underestimate on-orbit uncertainties that arise from error in relative height estimates (Duncanson et al. 2022). Prediction intervals from conformal inference, in contrast, reflect the empirical distribution of on-orbit data, propagating both measurement- and model-based uncertainty.
Finally, aboveground biomass density is converted to aboveground carbon density by multiplying by the global mean carbon concentration: 0.476 ([Martin et al. 2018](https://doi.org/10.1038/s41561-018-0246-x)).
### Post Processing
Estimates of height, cover, and aboveground carbon density were minimally post-processed using simple heuristics. To reduce low noise, canopy cover values < 5% were set to zero. If canopy cover was zero at both the beginning and the end of the time series, then all annual cover values were set to zero. Where canopy cover was estimated as zero, canopy height and aboveground carbon density were also set to zero.
## Data Quality
Figure 5: Model performance evaluated on withheld samples (n=360,853 tiles) for (A) mean canopy height and (B) canopy cover at 30 m resolution. Performance metrics were computed using the full withheld datasets but the plots were subset to 1 million random samples for visualization. (C) Aboveground biomass model performance evaluated against GEDI L4B data at 1 km resolution. A minimum of 20 points per grid cell were used for visualization.
The evaluation framework for this product includes two primary components: withheld data evaluation, and intercomparison. Withheld data evaluation refers to comparisons with samples of directly comparable observations, like airborne or spaceborne LiDAR data. Intercomparison evaluates modeled Diligence estimates against modeled estimates from external sources, like field plots and third party satellite observations. This distinction is particularly important when comparing carbon density or biomass density data. To fully evaluate the quality of this product, we hihgly recommend reading the full methods and validation report describing this product ([Anderson et al., 2025](https://doi.org/10.32942/X2KW7H)).
### Airborne LiDAR Comparison
The canopy height model has a root mean squared error (RMSE) of $2.9\ m$, mean absolute error (MAE) of $1.5\ m$, bias of $0.04\ m$, and an $r^2$ value of $0.83$ (Fig. 5A). The canopy cover model has $RMSE = 14.3%$, $MAE = 8.25%$, $bias = 0.4%$, and $r^2 = 0.79$ (Fig. 5B).
### GEDI L4A and ICESat-2 Comparison
Based on 10-fold geographic cross validation, the aboveground biomass model has a mean RMSE of $55.27\ Mg \cdot ha^{-1}\ (sd = 2.18)$, mean MAE of $24.2\ Mg \cdot ha^{-1}\ (sd = 0.87)$, mean bias of $-0.06\ (sd = 0.39)$, and a mean $r^2$ value of $0.638\ (sd = 0.01)$. Uncertainty estimation showed empirical interval coverage on withheld data was 92.07%, and the mean interval width is $100.9\ Mg \cdot ha^{-1}$.
### GEDI L4B Comparison
Comparing mean aboveground biomass density at a 1 km scale against GEDI L4B — a product that statistically aggregates L4A footprints and is not independent from the training data — reports model performance scores of $RMSE = 30.77\ Mg \cdot ha^{-1}$, $MAE = 13.49 Mg \cdot ha^{-1}$, $bias = -5.0 Mg \cdot ha^{-1}$, and $r^2 = 0.819$ (Fig. 5C). Further resampling to 1 degree grid cells shows strong agreement between Diligence and GEDI L4B ($r=0.98$, $bias=-5.0$, $RMSE=14.03$, $MAE=8.37$) but identifies particularly high disagreement in mountainous regions. These results demonstrate the benefits of spatial aggregation, reducing noise in both the model predictions and the L4A footprints.
## Known Limitations and Caveats
**Unmasked clouds/shadows/haze** may occur in certain cases. Significant effort went into developing minimizing cloud and atmospheric contamination from surface reflectance data, but in some cases commission errors can still be an issue. This is most common over the Congo Basin, which experiences year-round cloudy and smoky conditions.
**Circular spatial artifacts** in model predictions arise due to the pixel selection logic that downweights pixel quality scores by distance to cloud edges. This can lead to large temporal differences between adjacent pixels. Information on expected pixel quality and the day of observation are encoded in the QA and DOY products, which can be used to filter out low quality observations from a change analysis.
**Square spatial artifacts** are the result of the tile-based U-Net architecture, and are most prominent over heavily forested areas in the canopy height predictions. These artifacts are often predicted to be 1-2m taller than surrounding pixels, and are typically well within the uncertainty bounds, but are visually distinctive. Downsampling typically minimizes this effect.
**Occasional over-prediction over the built environment** due to high rates of double-bounce radar backscattering among buildings. Interpret values over urban areas with caution.
**Prediction intervals can be asymmetric**. For example, since carbon model predictions typically underestimate stocks, upper prediction intervals (p95) are often wider than the lower prediction interval (p05). On average, the prediction intervals will contain the true pixel value with probability of 0.9.
## Coverage Map
Figure 7. Data availability map for the forest carbon diligence product. Land above 75 North or below 60 South are excluded. Some small islands were excluded
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/validation/)
# Validation Report
This document provides validation and intercomparison results for the Planet Forest Carbon Diligence products. It is intended for users of geospatial data interested in working with Forest Carbon Diligence data, which estimates aboveground carbon density, canopy cover, and canopy height.
The Forest Carbon Diligence products quantify — globally and annually — the density of carbon stored in trees, the area occupied by trees, and stand-level mean canopy height. These estimates are produced from machine learning models trained on historical satellite observations, airborne LiDAR data, and spaceborne LiDAR data. See the [Forest Carbon Diligence Technical Specification](https://docs.planet.com/data/planetary-variables/forest-carbon-diligence/techspec.md) for more information about methods.
[Download Planet Forest Carbon Diligence Validation Report →](https://planet.widen.net/s/d669jncqld/planet-userdocumentation-forestcarbonvalidation)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/)
# Forest Carbon Monitoring
The Forest Carbon Monitoring product is composed of a bundle of data resources: Canopy Height, Canopy Cover, and Aboveground Live Carbon at 3-meter spatial resolution. These data resources are produced quarterly over the entire landmass of the Earth (between 75° N and 60° S). The archive currently extends back to 2021. See the Technical Specification for more details.
## Basic Facts
| **Property** | **Info** |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spatial resolution | 3 m |
| Sensor/Input Data | Airborne LiDAR, LiDAR (GEDI), PlanetScope surface reflectance, Forest Carbon Diligence, Digital Elevation Model (DEM) |
| Revisit time | Quarterly |
| Spatial coverage | Global |
| Data availability | Q1 2021 - present |
| Available measurements | Canopy Height, Canopy Cover, and Aboveground Live Carbon |
| Common usage/purpose | Planet's Forest Carbon Monitoring products provides timely, operational, near-tree-scale insights into global changes in canopy cover, canopy height, and above carbon density. |
Forest Carbon Monitoring Data Releases
New Forest Carbon Monitoring data are released quarterly (March, June, September, December) on the last day of the month.
## Use Cases
**Reforestation Monitoring** - Forest Carbon Monitoring provides comprehensive data to identify and analyze reforestation and restoration projects. These efforts help trap carbon, support sustainable harvesting efforts, and may provide local economic benefits through tourism, public funding, or renewable resources. Stakeholders can use Forest Carbon to identify potential reforestation sites and monitor, analyze, and report on ongoing projects.
**Degradation Monitoring** - Detect single tree selective harvest or other small disturbances with our 3m resolution product. Brings powerful monitoring capacity to REDD+ and improved forest management (IFM) based carbon projects. With updates every quarter, you and your stakeholders will no longer have to wait years to know if a project is on track.
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
#### Canopy Height 3m
Loading...
#### Canopy Cover 3m
Loading...
#### Aboveground Carbon Density 3m
Loading...
For each request you make using the Subscriptions API, you'll get a dataset that includes forest carbon estimations for the specified TOI and AOI.
For more information on the Subscriptions API and code samples, see the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
### Subscriptions Time of Interest
The table below provides an example of the temporal periods and the date tags associated with Forest Carbon Monitoring data. When creating a subscription, the 'start\_time' must be set to the date tag or earlier, while the 'end\_time' must be set to a date after the date tag.
| **Season** | **Quarter** | **Start** | **End** | **Date Tag** |
| ---------- | ----------- | ---------- | ---------- | -------------------- |
| Winter | Q1 2024 | 2023-12-21 | 2024-03-20 | 2023-12-21T00:00:00Z |
| Spring | Q2 2024 | 2024-03-21 | 2024-06-20 | 2024-03-21T00:00:00Z |
| Summer | Q3 2024 | 2024-06-21 | 2024-09-20 | 2024-06-21T00:00:00Z |
| Fall | Q4 2024 | 2024-09-21 | 2024-12-20 | 2024-09-21T00:00:00Z |
## Additional Resources
[📖Technical Specification](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/techspec.md)
[Get the details in the Forest Carbon Monitoring Technical Specification](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/techspec.md)
[🎓Planet University](https://university.planet.com/intro-to-forest-carbon-diligence-and-monitoring)
[Get Started with Planet’s Forest Carbon Planetary Variable product for: global tree height, canopy cover and carbon raster.](https://university.planet.com/intro-to-forest-carbon-diligence-and-monitoring)
[📓Guides](https://docs.planet.com/guides.md)
[Visit our Guides page to find a collection of Jupyter Notebooks for hands-on learning.](https://docs.planet.com/guides.md)
[📚APIs](https://docs.planet.com/develop/apis/subscriptions.md)
[Learn more about the Planet Subscriptions API to obtain Forest Carbon data.](https://docs.planet.com/develop/apis/subscriptions.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/products/)
# Products
Below you will find a list of Data Resources available for the Forest Carbon Monitoring product.Each Data Resource has a series of associated Data Assets. We are continuoulsy working to improve the product, and periodically release new versions. We provide access to older versions of our products, but only produce data using the latest version at new timesteps. We recommend using the latest product version and reviewing the [version history in the changelog](https://docs.planet.com/develop/changelog.md?tag=forestCarbonMonitoring) associated with each release.
## Canopy Height 3m
Loading...
## Canopy Cover 3m
Loading...
## Aboveground Carbon Density 3m
Loading...
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/sandbox/)
# Forest Carbon Monitoring Sandbox Data
This Planet Sandbox Data collection for Forest Carbon Monitoring provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| --------------------------------------- | ----------------------------------------------- | ----------------------------------------- | ----------------------- |
| CANOPY\_HEIGHT\_v1.0.0\_3 | Planet Sandbox Data - PV FCM Canopy Height | BYOC-d09d8fd8-a3b3-49fb-9d78-47f3a5cc8ecc | 2020-12-31 - 2023-12-20 |
| CANOPY\_COVER\_v1.1.0\_3 | Planet Sandbox Data - PV FCM Canopy Cover | BYOC-ca501757-cf8e-43a8-b1a4-1aa59ae22425 | 2020-12-31 - 2023-12-20 |
| ABOVEGROUND\_CARBON\_DENSITY\_v1.0.0\_3 | Planet Sandbox Data - PV FCM Aboveground Carbon | BYOC-d4a2a179-0c1a-4426-8d54-e2ac82830e83 | 2020-12-31 - 2023-12-20 |
## Planet Sandbox Data Areas
This collection includes 16 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 16 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Quintana Roo, Mexico | 7 | 2020-12-21 – 2023-09-21 | 20.55, -87.24 |
| Iowa, United States | 569 | 2020-12-21 – 2023-09-21 | 41.30, -93.96 |
| California, United States | 15 | 2020-12-21 – 2023-09-21 | 41.37, -124.05 |
| Idaho, United States | 20 | 2020-12-21 – 2023-09-21 | 47.71, -116.33 |
| Amazonas, North Region, Brazil | 36 | 2020-12-21 – 2023-09-21 | -4.42, -60.37 |
| Georgia, United States | 4 | 2020-12-21 – 2023-09-21 | 32.68, -84.99 |
| New Jersey, United States | 20 | 2020-12-21 – 2023-09-21 | 40.56, -74.32 |
| Pará, North Region, Brazil | 567 | 2020-12-21 – 2023-09-21 | -6.77, -52.37 |
| Ogooué-Lolo Province, Gabon | 162 | 2020-12-21 – 2023-09-21 | -1.07, 11.83 |
| Nouvelle-Aquitaine, Metropolitan France, France | 565 | 2020-12-21 – 2023-09-21 | 44.73, -0.68 |
| Atsimo-Andrefana, Province de Toliara, Madagascar | 25 | 2020-12-21 – 2023-09-21 | -22.25, 43.79 |
| Kitui County, Kenya | 29 | 2020-12-21 – 2023-09-21 | -0.26, 38.23 |
| Tshopo, Democratic Republic of the Congo | 288 | 2020-12-21 – 2023-09-21 | 1.22, 25.64 |
| Western Australia, Australia | 575 | 2020-12-21 – 2023-09-21 | -31.92, 116.15 |
| Riau, Sumatra, Indonesia | 20 | 2020-12-21 – 2023-09-21 | -0.18, 102.41 |
| Khammouane, Laos | 20 | 2020-12-21 – 2023-09-21 | 17.15, 105.82 |
[Download GeoJSON](https://docs.planet.com/data/planetary-variables/forest_carbon_monitoring/polygons.geojson)
## Highlights
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=17.1481\&lng=105.82251\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX1%2Fa%2Bw4wG8eIVfMgk%2FvDmhHxrovEwT%2FEvdBTkh4WvmXCd68%2Fq06VUwKIkmD5TMpuNJSzHZ6vxk3aqMvRO%2FyXNDbNLXZoCl0eD8yclCUNEhnG53w9KwWdSo%2Fe\&datasetId=d4a2a179-0c1a-4426-8d54-e2ac82830e83\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=ABOVEGROUND-CARBON-DENSITY\&demSource3D="MAPZEN")
Khammouane, Laos
2020-12-21 - 2023-09-21
20km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=17.1481\&lng=105.82251\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX1%2Fa%2Bw4wG8eIVfMgk%2FvDmhHxrovEwT%2FEvdBTkh4WvmXCd68%2Fq06VUwKIkmD5TMpuNJSzHZ6vxk3aqMvRO%2FyXNDbNLXZoCl0eD8yclCUNEhnG53w9KwWdSo%2Fe\&datasetId=d4a2a179-0c1a-4426-8d54-e2ac82830e83\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=ABOVEGROUND-CARBON-DENSITY\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-22.2323\&lng=43.78691\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX180XBAZynT8rOzF%2BQ44Xiaw0jjWE8kZ4I4pmiR8Z9sTnzKRpS3xqSik8pvp2FciGQyx1D8A9ooKBbyeflbMS55w3D%2FaBiRog85G13XWTnBALO%2BDzwYhV60n\&datasetId=ca501757-cf8e-43a8-b1a4-1aa59ae22425\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=CANOPY-COVER\&demSource3D="MAPZEN")
Atsimo-Andrefana, Madagascar
2020-12-21 - 2023-09-21
26km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=14\&lat=-22.2323\&lng=43.78691\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX180XBAZynT8rOzF%2BQ44Xiaw0jjWE8kZ4I4pmiR8Z9sTnzKRpS3xqSik8pvp2FciGQyx1D8A9ooKBbyeflbMS55w3D%2FaBiRog85G13XWTnBALO%2BDzwYhV60n\&datasetId=ca501757-cf8e-43a8-b1a4-1aa59ae22425\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=CANOPY-COVER\&demSource3D="MAPZEN")
[](https://insights.planet.com/analyze/browser/?zoom=13\&lat=47.70965\&lng=-116.34633\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX1%2B8RQf7awJj1vqgAQjivr9mg3%2FjJskyAAugtAOVN9ARX24T1EVtjuDj5K2e2IIUVW6%2FNtCZBQPVqsaPDbZYlF4cFwsfsmNnc7W94%2BF7ISJa8ivVLR7aFFsM\&datasetId=d09d8fd8-a3b3-49fb-9d78-47f3a5cc8ecc\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=CANOPY-HEIGHT\&demSource3D="MAPZEN")
Idaho, USA
2020-12-21 - 2023-09-21
20km²
[Visualize in the Browser →](https://insights.planet.com/analyze/browser/?zoom=13\&lat=47.70965\&lng=-116.34633\&themeId=PLANET_SANDBOX\&visualizationUrl=U2FsdGVkX1%2B8RQf7awJj1vqgAQjivr9mg3%2FjJskyAAugtAOVN9ARX24T1EVtjuDj5K2e2IIUVW6%2FNtCZBQPVqsaPDbZYlF4cFwsfsmNnc7W94%2BF7ISJa8ivVLR7aFFsM\&datasetId=d09d8fd8-a3b3-49fb-9d78-47f3a5cc8ecc\&fromTime=2023-09-21T00%3A00%3A00.000Z\&toTime=2023-09-21T23%3A59%3A59.999Z\&layerId=CANOPY-HEIGHT\&demSource3D="MAPZEN")
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/techspec/)
# Technical Specification
Figure 1: Side-by-side view of PlanetScope Mosaics and aboveground carbon density data over the Amazon River in Amazonas, Brazil.
Forest Carbon Monitoring provides a series of data products for mapping forest change at high resolution worldwide. These products provide timely, operational insights into changes in canopy cover, canopy height, and aboveground carbon density with unprecedented detail, powered by Planet’s unique imaging constellation. The initial release includes quarterly observations starting in December 2020, providing rolling insights into forest structure and carbon.
The Forest Carbon Monitoring products were primarily designed to support project and jurisdictional MRV1, as well as supply chain risk evaluations for EUDR2 compliance. The leading project type in carbon markets follows the REDD+3 framework of avoiding deforestation, and Forest Carbon Monitoring excels at tracking forest loss at fine scales and quantifying the resulting carbon losses.
The power of quarterly, high resolution data is in detecting complex, diffuse patterns like degradation and regrowth. Not all forest loss is uniform, and it is crucial to map the selective harvests of individual trees or small groups of trees in order to accurately estimate forest inventories at scale.
While detecting changes early in a tree's life history is often challenging, Forest Carbon Monitoring is sensitive to young tree growth. These data can be combined with in situ data for digital MRV of natural regeneration or explicit ARR4 interventions.
When scaled up to sub-national or national scales, Forest Carbon Monitoring can support jurisdictional carbon accounting and policy implementations related to land-based climate mitigation.
Acronyms
1. MRV: Monitoring, reporting and verification 2. EUDR: European Union Deforestation Regulation 3. REDD+: Reducing emissions from deforestation and forest degradation 4. ARR: Afforestation, reforestation and restoration
## Product Specifications
Table 1: Forest Carbon Monitoring product specification
| Specification | Value |
| ------------------- | ------------------------------------------------------- |
| Metrics | Canopy cover, canopy height, aboveground carbon density |
| Spatial extent | Global land mass > -60S and < 75N, excluding ice sheets |
| Temporal extent | Dec. 2020 - Present |
| Temporal resolution | Quarterly |
| Temporal periods | Q1: Dec 21 - Mar 20 |
| | Q2: Mar 21 - Jun 20 |
| | Q3: Jun 21 - Sep 20 |
| | Q4: Sep 21 - Dec 20 |
Canopy cover (CC) quantifies the percentage of area occupied by trees within a pixel, where a tree is defined as vegetation 5 meters or taller. This metric will be most sensitive to tree loss events like timber harvest or deforestation, and to increases in tree cover due to regeneration or ARR.
Canopy height (CH) quantifies the average top-of-canopy height within each pixel. While this metric is sensitive to tree loss, it is less sensitive to large tree growth. Vertical growth is typically slower in mature trees compared to young trees, meaning quarter-over-quarter height increases are not frequently observed outside of regrowth contexts.
Aboveground carbon density (ACD) quantifies the expected density of carbon stored in woody biomass, measured in units of mass per area (megagrams of carbon per hectare). It is not a direct estimate of the total carbon in each pixel or each tree, but an estimate of area-based carbon density.
## Asset Properties
This tables specifies the properties of the data assets delivered by the [Planet Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md).
Table 2: Forest Carbon Monitoring data resource properties
| Metric | Asset Name | Units | Type | Typical Range | No Data Value | Band Count | Resolution |
| -------------------------- | ---------- | ----- | ----- | ------------- | ------------- | ---------- | ------------------- |
| Canopy Cover | cc | % | UINT8 | 0 - 100 | 255 | 1 | 0.000025° (±3x3 m) |
| Canopy Height | ch | m | UINT8 | 0 - 50 | 255 | 1 | 0.000025° (±3x3 m) |
| ACD: Minimum Mapping Unit | acd-mmu | Mg/ha | INT16 | 0 - 300 | 32767 | 1 | 0.00025° (±30x30 m) |
| ACD: Downscaled | acd | Mg/ha | INT16 | 0 - 300 | 32767 | 1 | 0.000025° (±3x3 m) |
| CC Uncertainty | cc-uc | % | UINT8 | 0 - 100 | 255 | 2 | 0.000025° (±3x3 m) |
| CH Uncertainty | ch-uc | m | UINT8 | 0 - 80 | 255 | 2 | 0.000025° (±3x3 m) |
| ACD MMU Uncertainty | acd-mmu-uc | Mg/ha | INT16 | 0 - 300 | 32767 | 2 | 0.00025° (±30x30 m) |
| ACD Downscaled Uncertainty | acd-uc | Mg/ha | INT16 | 0 - 300 | 32767 | 2 | 0.000025° (±3x3 m) |
Aboveground carbon density data are provided at two spatial resolutions.
The 30m Minimum Mapping Unit (MMU) data estimates carbon density at the native resolution of the model. This product is straightforward to analyze and validate, and aligns with best mapping practices recommended by the [Committee on Earth Observing Systems](https://lpvs.gsfc.nasa.gov/PDF/CEOS_WGCV_LPV_Biomass_Protocol_2021_V1.0.pdf) (CEOS).
The 3m Downscaled product provides carbon estimates that match the resolution of the canopy height and canopy cover products. The value of downscaled data is to quantify carbon density over small—but not sub-tree—areas, like smallholder farms, selective harvests, field plots, and carbon projects.
Because the downscaled data are provided at a spatial resolution finer than the size of most tree crowns, downscaled carbon estimates should be aggregated across multiple pixels, which greatly improves prediction quality and interpretability. This product empowers users to flexibly aggregate data to the scales that fit their needs, particularly in use cases where coarse, gridded data pose analytical challenges. See the [Carbon Downscaling Method](#carbon-downscaling) section for more details on the downscaling approach, and the [Minimum Mapping Units](#minimum-mapping-units) section for guidance on aggregation.
Table 3. Uncertainty band descriptions
| Uncertainty band | Description |
| ---------------- | ---------------------------------------- |
| Q05 (band 1) | Lower prediction bound (5th percentile) |
| Q95 (band 2) | Upper prediction bound (95th percentile) |
Uncertainty data are provided as calibrated 90% prediction intervals for each pixel in each quarter. These values are provided in the same units as their respective reference data. In other words, the pixel values and units are consistent between the "cc" and "cc-uc" assets.
### Input Data
Canopy height and canopy cover are estimated at high resolution using computer vision models. Airborne LiDAR data are the response variables, and a series of satellite-derived datasets are the feature variables.
Forest carbon density is first estimated at 30m resolution using a gradient boosting regression model, then downscaled using a linear [downscaling model](#carbon-downscaling). GEDI L4A data are the response variable, and canopy height, canopy cover, and elevation data are the feature variables.
Table 4: List of inputs for Forest Carbon Monitoring production
| Product | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Airborne LiDAR | Point cloud data processed to rasters of canopy height and canopy cover at 1m resolution, then resampled to match the Surface Reflectance data. |
| GEDI L4A | [GEDI L4A](https://doi.org/10.3334/ORNLDAAC/1907) data encode modeled estimates of aboveground biomass density across most of the terrestrial biosphere. |
| Surface Reflectance | Quarterly, 4-band [PlanetScope Surface Reflectance Mosaics](https://assets.planet.com/products/basemap/planet-basemaps-product-specifications.pdf), spectrally normalized to Sentinel-2. |
| Forest Carbon Diligence | 30m canopy height and canopy cover data from the [Forest Carbon Diligence](https://planet.widen.net/s/rv77kqctqw/planet-userdocumentation-forestcarbon) product. |
| Digital Elevation Model (DEM) | Copernicus [GLO-30](https://doi.org/10.5270/ESA-c5d3d65) DEM are used for most of the global landmass, ALOS [AW3D30](https://www.eorc.jaxa.jp/ALOS/en/dataset/aw3d30/aw3d30_e.htm) is used where GLO-30 does not provide data. |
## Methods
Figure 2: Workflow diagram for Forest Carbon Monitoring illustrating the flow of data for delivery.
### Global Gridding and Co-alignment
A global grid was used to create deterministic, geographically independent samples, assigned to non-overlapping sets for model training, validation, and testing.
This grid was specified using the [EASE Grid 2.0](https://doi.org/10.3390/ijgi1010032) equal area projection (EPSG:6933) at 3.4m resolution. EASE Grid offers an efficient layout design, storing only 60% of the pixel count compared to a geographic coordinate system at a comparable resolution. This cylindrical projection preserves area but distorts shapes close to the poles, which could introduce spatial artifacts in the vision model. A large amount of training data was acquired at high latitudes to mitigate this effect.
Training data was generated by randomly sampling 128x128 pixel tiles from regions with high quality airborne LiDAR data, and a deterministic grid was used to define the sampling strategy. First, the grid was overlaid with the LiDAR extent, and tile centroids were sampled over non-overlapping valid data locations.
Once the tile locations were selected, a coarser grid was used to split data into training, validation, and testing groups. 2x2 quads were split so that samples within two of the tiles were used for model training, one for validation, and one for testing. This resulted in an approximately 50-25-25 split with no spatial overlap between tiles. In total, this produced 27.5 million hectares of data for training and evaluation, with 806,826 samples used for training, 253,497 for validation, and 352,870 for testing.
Quarterly, 4-band surface reflectance mosaics were produced starting in 2018 based on the quality and quantity of available PlanetScope data. Surface reflectance and LiDAR data were time matched to select temporally-coincident observations. LiDAR data collected prior to 2018 was matched to the 2018 surface reflectance mosaic. For LiDAR data with large or imprecise collection periods, the nearest leaf-on quarter was selected (corresponding to spring in the northern and southern hemisphere).
Training data were spatially resampled to align in shape and resolution. Each sample was a 128x128 array at 3.4m resolution, projected to EASE Grid. The response data—LiDAR-derived canopy height and canopy cover—were average resampled to this scale. The feature data—surface reflectace mosaics and the 30m Forest Carbon Diligence data—were extracted with nearest-neighbor resampling then concatenated in the channel dimension, creating a 6-band feature stack. Diligence data from the time-matched year was selected for each sample. The Diligence data were included to provide contextual information to the model regarding the absolute canopy height and canopy cover values for each sample, and to improve alignment across products.
### 2D Deep Learning
U-Net image regression models were trained to predict canopy height (m) and canopy cover (%) at 3.4m resolution, using surface reflectance mosaics and 30m maps of height and cover as predictors.
The height and cover response datasets were modeled simultaneously in a multi-task learning framework using Joint Task Training ([Crenshaw 2020](https://doi.org/10.48550/arXiv.2009.09796)). This approach optimized both accuracy and efficiency. There is strong but non-linear covariance between canopy height and canopy cover, and many of the spectral features used to estimate these patterns are shared across contexts, leading to efficient model training convergence.
Including canopy height and canopy cover maps from the Diligence product increased the overall feature dimensionality, improving predictive power. Sharing a joint encoder/decoder also improved consistency in the output prediction features, so post-processing harmonization was unnecessary. Multi-task learning reduced the overall saturation of canopy height predictions, increasing the predicted heights at the tall end of the distribution, though these effects are [still pronounced](#canopy-height-saturation).
The U-Net model architecture was modified to include ResNet blocks and a series of network-in-network connections ([Lin et al. 2013](https://doi.org/10.48550/arXiv.1312.4400), [Zhang et al. 2018](https://doi.org/10.1109/LGRS.2018.2802944)). The Log Cosh loss function was used to minimize the contributions of large residual errors to model convergence, which was found to improve canopy height predictions. Using spatially-independent validation data—instead of shuffling training and validation data at runtime—was found to improve model generalization, minimizing the difference between training and testing metrics.
Model inference was applied independently to each quarter's feature stack. As a result, seasonal vegetation patterns and sun-sensor observation variability introduce quarter-over-quarter variance to the raw model predictions. Experiments found that training models with just leaf-on observations improved generalization across quarters, compared to models trained using both leaf-on and leaf-off observations. This quarter-over-quarter variance is addressed downstream using time series models.
### Time Series Modeling
Figure 3: Statistical modeling for estimating canopy height and canopy cover over time. (A) An image time series is generated from the raw predictions of the vision model for times t=1, … T. (B) Three regression models are fit for each pixel: a constant model to represent the temporal mean (blue), a changepoint model to represent sudden change (red), and a spline model to represent gradual change (orange). A model is selected for each pixel, with the preferred model color coded in the image on the right. (C) The preferred model for each pixel is used to generate denoised predictions for each time step: expected values (green color ramp) and standard errors of the predictions (blue color ramp).
The vision model predicts height and cover for each quarter independently, and the predictions contain variation related to phenology, illumination, and sensor calibration. We minimize the variation in prediction sequences using statistical models.
For each pixel, three models are fit:
1. A constant-in-time model, which represents stability over time
2. A spline model, which represents gradual change
3. A changepoint model, which represents fast change
The constant-in-time model assumes that all variation in predictions is due to noise. This model is expected to perform well when height or cover remains stable over time or when changes are minimal relative to the noise in the predictions (for example, slow growth that is not detectable over a few years).
The spline and changepoint models are designed to capture slow and fast changes, respectively. Regularized B-splines are used to estimate non-linear trends, while the changepoint model includes a discrete change point parameter at the timestep with the greatest change in predicted height or cover.
The preferred model for each pixel is selected using Akaike's Information Criteria (AIC). An additional heuristic is applied to reduce noise: if the coefficient of variation (over time) for the preferred model's predictions is below a threshold, the constant-in-time model is selected. This coefficient of variation threshold is a hyperparameter tuned alongside the AIC threshold.
Once a preferred model is selected for each pixel, predictions are generated and predictive error is quantified using the standard errors of predicted values from the regression models. These standard errors are used downstream to quantify pixel-level uncertainty for height and cover.
### Carbon Downscaling
Figure 4: Overview of 3m aboveground carbon estimation. First, 3m height and cover data are average resampled to 30m. The 3m and 30m data are then provided separately as inputs to the AGC model (natively trained at 30m). This produces 3m and 30m carbon predictions. To ensure that the average of 3m AGC data equals the average of the 30m data, we apply a scale adjustment to the 3m data based on the ratio of 30m and unscaled 3m means.
Aboveground carbon density estimates are generated at 3m nominal resolution using statistical downscaling. This downscaling approach is designed to satisfy two criteria:
1. At fine scales, carbon estimates should be consistent with 3m height and cover.
2. At large scales, aggregated 3m carbon estimates should be consistent in expectation with 30m carbon estimates.
Simple linear downscaling of a model trained at 30m is used to meet these criteria. This 30m model is trained on L4A aboveground biomass estimates derived from NASA's Global Ecosystem Dynamics Investigation (GEDI) spaceborne lidar sensor. Given height and cover estimates, the model can predict aboveground biomass, which is converted to aboveground carbon by multiplying by a scalar representing the global mean carbon concentration. The details on model training, model performance, and scaling is described in more detail in the [Forest Carbon Diligence Technical Specification](https://planet.widen.net/s/rv77kqctqw/planet-userdocumentation-forestcarbon). 30m is considered the "native scale" of the carbon model.
To create 3m estimates from the 30m model, 3m height and cover are passed as inputs, generating raw 3m carbon predictions. These predictions are "raw" due to the scale mismatch between the model's training resolution (30m) and the deployment resolution (3m). Next, 3m height and cover are average resampled to 30m, and the 30m height and cover inputs are passed to the model to create 30m carbon estimates at the native resolution. Mean carbon is then computed for both the raw 3m and native 30m predictions, and the ratio of means is used to compute a scale adjustment. Final 3m carbon predictions are computed by scaling raw 3m carbon estimates, ensuring that the average carbon of the 30m predictions equals the average carbon of the final 3m predictions.
### Pixel-level Uncertainty
Standard errors from the pixel-level time series models are used to construct 90% prediction intervals for height and cover.
Intervals are constructed as:
$[y_{pred} - \widehat{q} \cdot \sigma_{pred}, y_{pred} + \widehat{q} \cdot \sigma_{pred}]$
where $y_{pred}$ is a predicted value from the time series model, $\sigma_{pred}$ is the standard error of the prediction, and $\widehat{q}$ is a parameter estimated using withheld data via split conformal inference.
Split conformal inference uses disjoint partitions of a dataset to produce well-calibrated prediction intervals. These are 90% prediction intervals that contain the true value approximately 90% of the time ([Angelopolous and Bates 2021](https://doi.org/10.48550/arXiv.2107.07511)).
A calibration dataset is used to estimate $\widehat{q}$, a scalar quantity that determines the width of the interval relative to the standard error to achieve 90% coverage. After generating predictions with $\widehat{q}$, empirical interval coverage is quantified on a spatially non-overlapping test set. Test set coverage was 90.3% for canopy cover and 91.7% for canopy height.
## Data Quality
### Deep Learning Model Performance
Figure 5: Scatter plots for canopy height predictions at 3m (left), 10m (middle) and 30m (right) resolutions.
There are several drivers of prediction uncertainty, including model variance, observation quality, and orthorectification quality. These drivers are difficult to disentangle, but we provide a comparison of multi-scale model performance below to illustrate how model performance improves with aggregation.
Users are encouraged to analyze the data at the scale that fits their analysis. This is often at the original scale of the data. But in contexts where prediction accuracy is critical, aggregating forest structure data provides meaningful improvmeents. High resolution data is valuable beyond providing detailed maps; aggregating high resoultion data can capture subtle, fine-scale dynamics more precisely at scale than direct observations at lower resolution.
Table 5. Multi-scale model performance comparison
| Metric | Resolution | R2 | MAE | RMSE |
| ------------- | ---------- | ---- | ---- | ---- |
| Canopy height | 3m | 0.68 | 2.4m | 4.2m |
| | 10m | 0.75 | 1.9m | 3.4m |
| | 30m | 0.81 | 1.6m | 2.9m |
| Canopy cover | 3m | 0.70 | 12% | 20% |
| | 10m | 0.78 | 9% | 16% |
| | 30m | 0.84 | 7% | 12% |
### Canopy Height Saturation
Figure 6: Binned residual error plots for canopy height show attenuated signal for taller trees. The residual errors for each test data observation were binned in 5 meter increments for this box plot, showing canopy height predictions are systematically lower for tall trees. This plot is not normalized by sample frequency.
Signal saturation is a well-known challenge to estimating canopy height using optical satellite data ([Mutanga et al., 2023](https://doi.org/10.1016/j.isprsjprs.2023.03.010)). This refers to the limited signal available in optical remote sensing data to predict tree heights beyond 25-30 meters above ground. While several modeling approaches were tested to minimize this effect (see [2D Deep Learning](#2d-deep-learning)), it remains visible in the residual error plots (Figure 6). This might pose a challenge for users who depend on unbiased canopy height estimates (in allometric regression models, for example).
In empirical use cases, signal saturation may not be as problematic. For example, the aboveground carbon density model used in this product estimates empirical relationships between predicted canopy height and canopy cover maps and the observed carbon density data. Practically, this results in strong model performance for the low and mid range of carbon estimates, though predictions in the most carbon-dense forests will likely be underestimated.
Figure 7: Residual error histograms for canopy height (left) and canopy cover (right).
Overall, the deep learning model converged to predict both canopy height and canopy with low total bias across the full test data set. Although there is signal saturation among taller trees, higher predictions at lower heights balance the overall predictions, driving low population-level bias.
This effect further demonstrates the value of spatial aggregation. While bias may occur at any one point across the landscape, these biases decrease with aggregation, and the total bias over large areas is likely to be low.
### Minimum Mapping Units
The aboveground carbon density products are provided at multiple spatial resolutions: 30m and 3m. The reason for providing multiple assets is related to a geographic concept known as the minimum mapping unit. [Knight and Lunetta, 2003](https://doi.org/10.1109/TGRS.2003.816587) provide a short review of this topic.
The minimum mapping unit for forest carbon products refers to the smallest area over which carbon estimates can be reliably quantified and validated. Because the forest carbon data were fit using [GEDI L4A](#input-data) data and 30m feature data, the minimum mapping unit for the carbon model is 30m. This is approximately the size of a 0.1 ha field plot. Although the downscaled product is provided at 3m resolution—which can be smaller than the size of an individual tree—the minimum mapping unit for analysis remains 30m.
So why provide a data product at a scale finer than the minimum mapping unit?
The primary value proposition of high resolution data is to provide a flexible data product that can be aggregated to the appropriate scale of analysis, which varies by use case.
Current best practices recommend mapping carbon at 0.25 - 1 ha (50 - 100m) resolution in tropical forests, and 0.1-0.25 ha (30 - 50m) in boreal and temperate forests ([CEOS 2021](https://lpvs.gsfc.nasa.gov/PDF/CEOS_WGCV_LPV_Biomass_Protocol_2021_V1.0.pdf), [Frazer et al. 2011](https://doi.org/10.1016/j.rse.2010.10.008)). The Food and Agriculture Organization (FAO) developed a consensus forest definition, which specified minimum thresholds of areas with 10% canopy cover, 5 m tree height, covering at least 0.5 ha ([FAO 2000](https://www.fao.org/forest-resources-assessment/fra-2000/en)). Aggregation to 1 ha has been shown to minimize prediction uncertainty and identified as the optimal scale for accurately estimating forest carbon stocks from remote sensing ([Mascaro et al. 2011](https://doi.org/10.1016/j.rse.2011.07.019), [Chen et al. 2016](https://doi.org/10.1016/j.rse.2016.07.023)).
While each of these scales is greater than the 0.1 ha minimum mapping unit, data provided at that resolution may still prove prohibitive. Scale mismatches between field and satellite datasets has long been one of the primary drivers of uncertainty and barriers to effective validation, especially when validating plots that may only be one or two pixels in size or fall on borders between pixels ([Wu and Li, 2009](https://doi.org/10.3390/s90301768), [Anderson 2018](https://doi.org/10.1111/ele.13106), [Réjou-Méchain et al. 2019](https://doi.org/10.1007/s10712-019-09532-0)). Mismatches between satellite resolution and forest definitions make global forest change analysis prohibitively complex, too. This has become so acute that some researchers have called to change the FAO's global definition of forests to instead be defined by the 30m resolution of Landsat ([Zalles et al. 2024](https://doi.org/10.1038/s43247-024-01779-9)).
Instead of asking users to redefine their problems to accomodate their data, the downscaled product was developed to accomodate the wide range of contexts our users work in. It is straightfoward to resample the downscaled product over field plots, carbon projects, disturbed areas, or tree planting sites. The carbon estimates will be valid so long as the data are aggregated to at least the minimum mapping unit.
To demonstrate the value of high resolution carbon data, consider the case of carbon quantification over smallholder farms. Recent work found that smallholder farmers in Rwanda planted an average of 3 trees per farm over a decade of analysis, which added up to over 50 million new trees nation-wide ([Mugabowindekwe et al. 2024](https://doi.org/10.1038/s43247-024-01278-x), [Brandt et al. 2024](https://doi.org/10.1038/s44287-024-00116-8)). Individually, these contributions to a national carbon budget are minimal, and may not be detectible from lower resolution observations. But a full accounting of smallholder contributions could prove meaningful at jurisdictional scales. Developing cost-effective MRV tools for quantifying changes in carbon stocks was identified as a top priority for engaging smallholder farmers in carbon markets, and high resolution data uniquely addresses this need ([Schilling et al. 2023](https://hdl.handle.net/10419/278420)).
The 3m downscaled forest carbon product was not developed to provide sub-tree estimates of carbon density; it was designed to empower users to flexibly aggregate data to the scales that fit their needs, particularly in use cases where coarse, gridded data pose analytical challenges. The 30m MMU product supports direct carbon stock analyses, requiring no additional modifications by uses to derive meaningful carbon estimates. Both products should be analyzed at a minimum mapping unit of 30m, though that does not preclude aggregation to the appropriate scale of analysis for your use case.
## Known Issues
**Halo effects**. The time series model estimates forest structure patterns across the full temporal extent of data and updates all predictions simultaneously. This can create visually-distinct boundaries between areas where rapid changes were observed, which propagate back in time. As a result, post-change edge effects can appear in the data prior to the observed vegetation change. This will typically be captured by the pixel-level prediction intervals, showing higher prediction uncertainty on the borders of disturbances. Anecdotally, this effect appears to be largely visual, with low numerical differences.
**Pixel coregistration**. PlanetScope surface reflectance data are provided with some positional uncertainty, meaning pixel locations may shift slightly quarter-over-quarter. PlanetScope absolute positional uncertainty is quantified in Section 3.3 in the [Imagery Product Specification](https://assets.planet.com/docs/Planet_Combined_Imagery_Product_Specs_letter_screen.pdf). Practically, this presents as a slight decrease in pixel-level contrast, and predictions may not appear as crisp as expected.
**False positive changes in the most recent time step**. The time series model is an effective outlier filter, smoothing over noisy observations from unmasked clouds, snow, or missing data. These models rely on additional observations that follow the noisy observations, which indicate a change did not persist. Additional observations are not available for the most recent time step, which increases the rate of false positive changes. For time-sensitive use cases, we advise users to consult the uncertainty layer, which should show high uncertainty in areas with anomalous change. For less time-sensitive use cases, we advise using the previous quarter's data to minimize false positives. The most recent quarter's data will be updated once new observations are available to correct these issues.
**Most changes are observed at year-to-year boundaries**. Including the annual, 30m Forest Carbon Diligence data as predictive features improves prediction accuracy but introduces a temporal mismatch in production. New Diligence observations are included at Q1 of each year, but are not updated for each following quarter. Changes detected from Diligence—both growth and loss—may not be captured until the next year. This means that change detection primarily occurs at year-to-year boundaries when new 30m observations are included.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/forest-carbon-monitoring/validation/)
# Validation Report
Coming soon
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/land-surface-temperature/)
# Land Surface Temperature
Accurate monitoring of Earth's surface temperature through satellite-derived information supports the understanding of many of our planet’s ecosystems, including physical processes that govern the three major cycles: carbon, energy and water.
Leveraging multiple earth observation datasets and innovative patented technology, Planet provides a twice-daily, global, consistent and accurate Land Surface Temperature products.
These datasets are not just numbers; It is a valuable tool for monitoring changes in cities, or understanding plant health and water availability. Also, this data plays a crucial role in assessing climate and meteorological risks by tracking temperature anomalies and shifts over time using the long archive capability.
What makes the Planet Land Surface Temperature (LST) product stand out is its unique blend of microwave and optical data, allowing the observation of temperature regardless of the cloud condition, so data can be compared consistently over time and space, providing the detailed insights needed for various applications.
## Use Cases
**Crop Stress Monitoring** - Using LST as input in energy balanced-based evaporation models, crop stress can be detected early on and allows early intervention.
**Phenology development** - LST can be used as input for Growing Degree Days ([check out the blog post](https://www.planet.com/pulse/satellite-based-land-surface-temperature-for-deriving-growing-degree-days/)). Growing degree days (GDD) is a weather-based indicator for assessing crop development. Crop producers use a measure of heat accumulation (temperature) to predict plant and pest development rates as the date for when a crop reaches maturity. The advantage of LST-based GDD lies in its ability to specifically monitor crop conditions, providing insights into the growth and development of crops, as opposed to relying solely on environmental conditions derived from air temperature.
**Heatwave monitoring** - Planet LST is able to monitor hot and dry conditions. The relationship between soil moisture and temperature indicates the severity and extent of drought conditions and the effect it has on crops, ecosystems, and the human population.
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
#### Land Surface Temperature 20 m
warning
LST 20 m is a beta product. This means the product is still under active development and may undergo changes to its methodology, accuracy, or availability. While the data is available for use, users should be aware that the product may have limitations or may be updated based on ongoing validation and feedback.
Loading...
The area of interest for LST 20 m should correspond to a single agricultural field. If the AOI of a subscription includes multiple fields, whether they contain different crops or the same crop managed differently, the resulting LST data will not accurately reflect conditions within any specific field. Similarly, if the AOI of a subscription includes non-agricultural areas, such as urban areas or water bodies, the resulting LST data will not accurately reflect conditions within the AOI.
#### Land Surface Temperature 100 m
Loading...
#### Land Surface Temperature 1000 m
Loading...
For more information on the Subscriptions API and code samples, see the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
## Additional Resources
[🎓Planet University](https://university.planet.com/intro-to-land-surface-temperature)
[Learn the LST basics with this introduction course.](https://university.planet.com/intro-to-land-surface-temperature)
[💡Blog posts](https://www.planet.com/pulse/tag/land-surface-temperature/)
[Read the latest LST news and stories.](https://www.planet.com/pulse/tag/land-surface-temperature/)
[📖Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md)
[Get started with the Subscriptions API.](https://docs.planet.com/develop/apis/subscriptions.md)
[📓Jupyter Notebooks](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/api_guides/subscriptions_api/land_surface_temperature_subscription.ipynb)
[Access LST and create visualizations with this tutorial.](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/api_guides/subscriptions_api/land_surface_temperature_subscription.ipynb)
[📖EvalScripts](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/land-surface-temperature/)
[Visualize LST and extract insights with EvalScripts.](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/land-surface-temperature/)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/land-surface-temperature/products/)
# Products
## Land Surface Temperature 20 m
Loading...
## Land Surface Temperature 100 m
Loading...
## Land Surface Temperature 1000 m
Loading...
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/land-surface-temperature/sandbox/)
# Land Surface Temperature Sandbox Data
This Planet Sandbox Data collection for Land Surface Temperature provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| --------------------- | -------------------------------- | ----------------------------------------- | ----------------------- |
| LST-AMSR2\_V1.0\_1000 | Planet Sandbox Data - PV LST 1km | BYOC-6b613b07-410a-4312-93ad-d1751fdc55de | 2012-07-25 - 2023-12-31 |
## Planet Sandbox Data Areas
This collection includes 17 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 17 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Arizona, United States | 579 | 2012-07-25 – 2023-12-31 | 32.86, -111.85 |
| Alberta, Canada | 580 | 2012-07-25 – 2023-12-31 | 50.15, -111.78 |
| Iowa, United States | 2320 | 2012-07-25 – 2023-12-31 | 41.19, -93.81 |
| Goiás, Central-West Region, Brazil | 575 | 2012-07-25 – 2023-12-31 | -16.52, -48.83 |
| Autonomous Community of the Basque Country, Spain | 576 | 2012-07-25 – 2023-12-31 | 42.81, -2.51 |
| Nouvelle-Aquitaine, Metropolitan France, France | 2304 | 2012-07-25 – 2023-12-31 | 44.84, -0.52 |
| Flevoland, Netherlands | 579 | 2012-07-25 – 2023-12-31 | 52.50, 5.71 |
| Groningen, Netherlands | 576 | 2012-07-25 – 2023-12-31 | 53.15, 6.37 |
| Emilia-Romagna, Italy | 576 | 2012-07-25 – 2023-12-31 | 44.97, 9.81 |
| Epirus and Western Macedonia, Greece | 576 | 2012-07-25 – 2023-12-31 | 40.65, 21.76 |
| Attica, Greece | 576 | 2012-07-25 – 2023-12-31 | 38.02, 23.92 |
| Kitui County, Kenya | 578 | 2012-07-25 – 2023-12-31 | -1.34, 37.85 |
| Al Jawf Region, Saudi Arabia | 576 | 2012-07-25 – 2023-12-31 | 30.05, 38.42 |
| Haryana, India | 578 | 2012-07-25 – 2023-12-31 | 27.86, 77.36 |
| Thái Bình Province, Vietnam | 576 | 2012-07-25 – 2023-12-31 | 20.51, 106.30 |
| Guizhou, Tongren, China | 575 | 2012-07-25 – 2023-12-31 | 28.09, 109.21 |
| New South Wales, Australia | 581 | 2012-07-25 – 2023-12-31 | -34.52, 146.13 |
[Download GeoJSON](https://docs.planet.com/data/planetary-variables/land-surface-temperature/polygons.geojson)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/land-surface-temperature/techspec/)
# Technical Specification
## Overview
Land surface temperature (LST) represents the thermodynamic temperature of Earth's surface and characterizes the radiative temperature emitted by the surface, offering insights into surface energy fluxes and interactions with the atmosphere.
The Earth's surface absorbs solar radiation, leading to the heating of the land while the temperature emitted by the surface varies as a result of the heterogeneity of the meteorological forcing, land cover, soil and vegetation water content, surface radiative properties and topography. Therefore, LST is highly variable in both space and time ([Prata et al., 1995](https://doi.org/10.1080/02757259509532285)). Because of the high spatio-temporal variability, LST derived from satellite data offers several advantages over in situ LST measurements such as global availability, consistency and spatially distributed measurements leading to a cost-effective and efficient data stream.
The information provided is the temperature from a satellite’s point of view. Thus, the "surface" is whatever the sensor sees when it looks through the atmosphere to the ground, for instance, top of the canopy for vegetated areas, soil for non-vegetated areas or roof in urban environments. Therefore, LST is not the same as the air temperature that is included in the daily weather report. LST can provide insights on a variety of applications: evaporation monitoring ([Miralles et al., 2011](https://doi.org/10.5194/hess-15-453-2011)), climate change studies ([IPCC, 2021](https://www.ipcc.ch/report/ar6/wg1/downloads/report/IPCC_AR6_WGI_SPM_final.pdf)), soil moisture estimation ([Merlin et al., 2008](https://doi.org/10.1016/j.rse.2008.06.012)), vegetation monitoring ([Kogan, 2001](https://doi.org/10.1175/1520-0477\(2001\)082%3C1949:OSTFGV%3E2.3.CO;2)), urban studies ([Voogt and Oke, 2003](https://doi.org/10.1016/S0034-4257\(03\)00079-8)), to name a few.
The Planet Land Surface Temperature product provides a measurement of the Earth’s skin temperature at a global level. By combining overlapping observations from multiple public satellite sensors that measure passive microwave radiation from the earth surface, Planet creates downscaled LST observations. Initial observations represent several kilometers of the Earth’s surface in any given pixel of data, but the Planet patented algorithm enhances the spatial resolution of the passive microwave observations. Optical imagery from Sentinel-2 is used to further improve the spatial resolution.
Planet offers two products: long archive (1 km) since 2002 and enhanced resolution (100 m) since 2017, with the following features:
* Available within 6 to 12 hours after the microwave satellite overpass for timely decision-making
* Available twice a day: at 01.30 and 13.30 solar local time
* Not hindered by clouds, leading to continuous and consistent feed of observations
* Accurate over the majority of land surface, with the exception of snow and frozen areas
* Based on a proprietary method to provide data at improved spatial resolutions
*Figure 1: Measurements of Land Surface Temperature southeast of Berlin, Germany. The image above represents the skin temperature from a single day, with each pixel representing a 100 x 100 meter area. Below, the measurements of Land Surface Temperature of a single point are plotted over 5 years with the baseline climatology, showing how temperature levels compare to the expected average for the area.*
## Product Specifications
warning
LST 20 m is a beta product. This means the product is still under active development and may undergo changes to its methodology, accuracy, or availability. While the data is available for use, users should be aware that the product may have limitations or may be updated based on ongoing validation and feedback.
*Table 1: LST 20 m product specification*
| Data Resource | LST 20 m |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Source ID | LST-field\_V1.0\_20 |
| Version | 1.0 |
| Unit | Kelvin |
| Pixel Size | 20 m |
| Temporal Resolution | 0° latitude: 205 to 228 observations per overpass time per year
40° latitude: 274 to 292 observations per overpass time per year |
| Overpass Time | 01:30 and 13:30 local solar time |
| Geographical Coverage | Global |
| Data Availability | 2018-01-01 - Present |
| Satellites Used | AMSR-2, Sentinel-2 |
| NRT latency (p90) | 24 hours |
| Archive latency | Within 30 days after creating a subscription |
*Table 2: LST 100 m product specification*
| Data Resource | LST 100 m |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Source ID | LST-AMSR2\_V1.0\_100 |
| Version | 1.0 |
| Unit | Kelvin |
| Pixel Size | 0.00089° (±100x100 m) |
| Temporal Resolution | 0° latitude: 205 to 228 observations per overpass time per year
40° latitude: 274 to 292 observations per overpass time per year |
| Overpass Time | 01:30 and 13:30 local solar time |
| Geographical Coverage | Global |
| Data Availability | 2017-07-01 - Present |
| Satellites Used | AMSR-2, Sentinel-2 |
| NRT latency (p90) | 24 hours |
| Archive latency | Within 30 days after creating a subscription |
*Table 3: LST 1000 m product specification*
| Data Resource | LST 1000 m |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Source ID | LST-AMSR2\_V1.0\_1000 (2012 - present)
LST-AMSRE\_V1.0\_1000 (2002-2011) |
| Version | 1.0 |
| Unit | Kelvin |
| Pixel Size | 0.00901° (±1000x1000 m) |
| Temporal Resolution | 0° latitude: 205 to 228 observations per overpass time per year
40° latitude: 274 to 292 observations per overpass time per year |
| Overpass Time | 01:30 and 13:30 local solar time |
| Geographical Coverage | Global |
| Data Availability | 2002-06-15 - Present
Data gap:
2011-10-04 to 2012-07-25 |
| Satellites Used | AMSR-2, AMSR-E |
| NRT latency (p90) | 24 hours |
| Archive latency | Within 30 days after creating a subscription |
## Asset Properties
Assets differ between field-based and tile-based data resources:
* **LST 20 m (field-based)**: Each observation is delivered as a single-band asset with metadata embedded in the GeoTIFF.
* **LST 100 m and LST 1000 m (tile-based)**: Each observation is delivered as a LST data asset (`*lst.tif`) with metadata provided in a separate quality flag asset (`*lst-qf.tif`).
*Table 4: Asset properties of LST 20 m data resources*
| Asset Name | Band Name | Unit | Type | Typical Range | No Data Value | Scale | Format |
| ---------- | --------- | ------ | ------ | ------------- | ------------- | ----- | ------- |
| lst | Band 1 | kelvin | UINT16 | 263-340 | 65535 | 0.01 | GeoTIFF |
*Table 5: Asset properties of LST 100 m and LST 1000 m data resources*
| Asset Name | Band Name | Unit | Type | Typical Range | No Data Value | Scale | Format |
| ---------- | --------- | -------- | ------ | ------------- | ------------- | ----- | ------- |
| lst | Band 1 | kelvin | UINT16 | 263 - 340 | 65535 | 0.01 | GeoTIFF |
| lst | Band 2 | kelvin | UINT16 | 250 - 360 | 65535 | 0.01 | GeoTIFF |
| lst-qf | Band 1 | unitless | UINT16 | NA | 0 | 1 | GeoTIFF |
You can find below a Python code snippet that converts a temperature from Kelvin to Celsius and Fahrenheit:
```
def kelvin_to_celsius(kelvin):
return kelvin - 273.15
def kelvin_to_fahrenheit(kelvin):
celsius = kelvin - 273.15
return (celsius * 9/5) + 32
```
## Methodology
### Passive Microwaves and Downscaling Method
The Ka band (±36.5 GHz) vertical polarized brightness temperature is used to derive LST because it is considered the most appropriate microwave frequency for temperature retrieval. This channel balances a reduced sensitivity to soil surface characteristics with a relatively high atmospheric transmissivity. It is shown that with a simple linear relationship, accurate values for LST can be obtained from this frequency [Holmes et al., 2009](https://doi.org/10.1029/2008JD010257).
The downscaling patented technology ([US10643098](https://patentimages.storage.googleapis.com/1a/6f/1c/8cf51399ee7eaa/US10643098.pdf), [EP3469516B1](https://patentimages.storage.googleapis.com/f1/6c/0b/55cad50731d3e0/EP3469516B1.pdf)) aims to improve the resolution of sensor data, in this case, the brightness temperatures observed by passive microwave sensors. The technique redefines the exact geolocation and reconstructs the antenna footprints of each observation. It uses the abundance of overlaps between these footprints for downscaling at a target resolution. Based on the footprint center, microwave frequency, incidence angle, azimuth angle, and footprint size for a given intensity, footprints are created and disaggregated in equal interval ellipses using an internal gaussian distribution. Within the ellipse-shaped footprints, the center of the footprint contributes more to the observed values than the edges. Water bodies will have a fixed value and will be considered; thus, the land brightness temperature can be retrieved more accurately. This method elucidates the exact source of the signal of each observation point. The output of the downscaling method is brightness temperature for a given frequency at the target resolution.
### Enhancements Using Optical Data
Land Surface Temperature is also highly variable in space, mainly due to soil properties, topography, agricultural practices, and land cover heterogeneity. Space-borne optical/thermal sensors can help retrieve high-resolution surface parameters. Several studies ([Lobell & Asner 2002](https://doi.org/10.2136/sssaj2002.7220), [Fensholt and Sandholt 2003](https://www.sciencedirect.com/science/article/abs/pii/S0034425703001895), [Sadeghi et al. 2017](https://doi.org/10.1016/j.rse.2017.05.041), [Yue et al. 2019](https://doi.org/10.1016/j.isprsjprs.2019.06.012)) found that soil and plant water content greatly influences the reflection in the shortwave infrared (SWIR) part of the spectrum. The SWIR, combined with the Near-Infrared (NIR) reflectance, which is affected by internal leaf structure and leaf dry matter content but not by water content, will enhance the LST retrieval from reflectances.
We produce a daily NDSWIR composite using a backward Gaussian weighted distribution. This composite integrates into the downscaling framework by attributing the weight of a brightness temperature to each pixel within the footprint. The output format remains similar to that of the downscaling algorithm without NDSWIR input.
The Sentinel-2 data is extracted from L2A - Bottom of the atmosphere (BOA) - reflectance in the [Sentinel-2 dataset documentation](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md).
### Input Data
*Table 6: List of inputs for Land Surface Temperature production*
| Product | Description |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Brightness Temperature Ka band | AMSR-E and AMSR-2 Level-1B Radiometer Ka band Brightness Temperatures (downloaded from [JAXA G-portal](https://gportal.jaxa.jp/gpr/?lang=en) in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 36.5 GHz with a footprint size of 7x12 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf). |
| Brightness Temperature W band | AMSR-E and AMSR-2 Level-1B Radiometer W band Brightness Temperatures (downloaded from JAXA G-portal in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 89 GHz with a footprint size of 3x5 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf). |
| Reflectances SWIR and NIR (for LST 20m/100 m) | Sentinel-2 Level-2A reflectance [data](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md) for two bands: SWIR (shortwave infrared around 1610 nm) and NIR (near infrared around 842 nm). |
| Digital Elevation Model | Digital elevation model (DEM) static map based on the Copernicus DEM GLO-90 product covering the full global landmass of the time frame of data acquisition (2011-2015). Detailed information is available in the link. |
| Land Cover Map | Custom global land classification including permanent water bodies based on the Copernicus Global Surface Water Bodies product from PROBA-V. Detailed information is available [here](https://land.copernicus.eu/global/) |
## Data Quality
### Validation
We have evaluated our LST products by comparing them to carefully ground data stations and other remotely sensed LST data across various land cover types and climates regions.
You can read more about the results in [this white paper](https://planet.widen.net/s/j9rl92dgpq).
Planet's 1 km LST product was validated over 114 locations from 2013-01-01 to 2022-12-31. We used an established network of in-situ stations from the United States Climate Reference Network (USCRN) and remotely sensed LST derived from MODIS AQUA. The Planet 1 km LST, MODIS AQUA 1 km LST and USCRN surface temperature were intercompared at 1:30 and 13:30, separately. The surface temperature at USCRN stations is measured over grassy or low vegetation (< 10 cm) surfaces and the stations cover many climatic and landscape conditions.
*Figure 2: Time series of nighttime (upper figures) and daytime (lower figures) land surface temperature for the in-situ observations from the United States Climate Reference Network (USCRN), MODIS and Planet’s 1 km products between 2013 and 2022 at the USCRN station Yuma (32.835, -114.1884), AZ, U.S. The scatterplots on the right compare single observations from MODIS’ and Planet’s LST against the in-situ observations for nighttime (Mean Absolute error (MAE) for MODIS: 1.28; MAE for Planet 1 km: 1.83) and daytime (MAE for MODIS: 3.40; MAE for Planet 1 km: 2.96).*
In the validation report, a spatial comparison of the Planet 100m LST against Landsat LST. The revisit time of Landsat is low with one observation every 8 days at best, since thermal-based LST is sensitive to cloud cover. The overpass time of Landsat is between 10:00 and 10:25 while Planet LST daytime is at 13:30. Due to the mismatch in observation time, the focus on the analysis is on the relative spatial variability, rather than the absolute comparison.
*Figure 3: Spatial comparison of 100 m LST compared to Landsat LST. The scatterplot on the left presents a comparison for agricultural fields on single day between Landsat and Planet LST, the right figures are the maps of the day compared. The area of interest are (top) Nordrhein Westfalen, near Düsseldorf in Germany and (bottom) southwest of Imperial, Nebraska, in the United States.*
### Metadata
#### LST 20 m
Metadata embedded in the GeoTIFF contains information about the quality of the observation. For example:
| Field | Type | Description | Example |
| ------------------- | ----------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
| `PRODUCT_VERSION` | String | Version identifier for the product specification | `v1` |
| `SOFTWARE_VERSION` | String | Version of the fbsl software that generated the output | `0.4.1` |
| `INPUT_ASSETS` | String | Comma-separated list of input data sources used | `NDSWIR_STATS,NDSWIR_RASTER,KA_V_DESC_STATS` |
| `LAST_NDSWIR_DATE` | String (ISO date) | Date of the last NDSWIR (Sentinel-2) observation with full coverage | `2024-01-19` |
| `LAST_NDSWIR_COV` | String (fraction) | Coverage fraction of the last NDSWIR observation used | `0.85` (= 85% coverage) |
| `QUALITY` | String | Overall quality assessment: `HIGH` if valid coverage > 80%, otherwise `LOW` | `HIGH` or `LOW` |
| `INVALID_RANGE_COV` | String (fraction) | Fraction of pixels outside valid LST range (250-340 K) | `0.02` (= 2% invalid) |
#### LST 100 m and LST 1000 m
Quality flag assets (`*lst-qf.tif`) provide metadata for each pixel using bitwise flags. Critical flags indicate unreliable data, with corresponding pixels in band 1 of the LST asset (`*lst.tif`) set to the no data value. The replaced LST value can be found in band 2 of the LST asset. Non-critical flags indicate that the data can be used with caution, taking into account the flag description.
Critical and non-critical flags are described in the tables below. For more information on how to access the quality flag asset, check out [subscribing to Planetary Variables](https://docs.planet.com/develop/apis/subscriptions/sources.md).
*Table 7: Non-critical flags*
| Bit | Flag layer | Description |
| --- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 4 | Possible severe precipitation | Part of the footprints touch an area flagged as severe precipitation. |
| 7 | Possible frozen soil | The surface may be frozen. These are pixels with a surface temperature between 263.15 K (-10°C) and 273.15 K (0°C). |
*Table 8: Critical flags*
| Bit | Flag layer | Description |
| --- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 8 | Frozen soil | The surface is considered frozen. Pixels with a temperature below 263.15 K (-10°C). |
| 9 | Severe precipitation | Severe precipitation is detected. |
| 11 | No overpass | The satellite did not pass over. |
| 13 | Instrumental flaws | Unrealistic values due to instrumental flaws. If the brightness temperature at 36.5 GHz V produces values either over 400K or under 0.9 \* the water temperature, the data is considered as unrealistic and is removed. |
| 14 | Out of valid range | Land Surface Temperature values are outside the valid range, meaning under 250 K or above 340 K. |
| 15 | Open water | Land Surface Temperature is not defined over water (retrieved from a land cover map). This data is filtered out during the processing of the raw satellite data. |
Here is a Python script to convert a quality flag pixel value into a list of corresponding quality flags. Note that one pixel may have multiple flags applied to it.
```
# lst_quality_flags.py
import argparse
LST_QUALITY_FLAGS = {
4: "Possible severe precipitation",
7: "Possible frozen soil",
8: "Frozen Soil (critical flag)",
9: "Severe precipitation (critical flag)",
11: "No overpass (critical flag)",
13: "Instrumental flaws (critical flag)",
14: "Out of valid range (critical flag)",
15: "Open water (critical flag)",
}
def convert_to_quality_flags(decimal_value: int) -> list[str]:
binary_string = format(decimal_value, "016b")
reversed_binary_string = binary_string[::-1]
return [
f"{i}. {LST_QUALITY_FLAGS.get(i, 'Unused flag')}"
for i, bit in enumerate(reversed_binary_string, start=1) if bit == "1"
]
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Convert a decimal value to quality flags.")
parser.add_argument("decimal_value", type=int, help="The decimal value to convert.")
args = parser.parse_args()
flags = convert_to_quality_flags(args.decimal_value)
print(*flags, sep="\n")
```
that you can call as follows, using value `8512` as example:
```
> python lst_quality_flags.py 8512
7. Possible frozen Soil
9. Severe precipitation (critical flag)
14. Out of valid range (critical flag)
```
### Other Limitations
The following are some key limitations that we have not flagged:
* Data should be considered unreliable over sloped terrain that is over 20 degrees. The microwave signal can be distorted by the angle of the slope, causing changes in the observed brightness temperature. This distortion leads to inaccuracies in the Land Surface Temperature estimates because the algorithms assume a flat surface.
* Dynamic water bodies may cause unrealistic Land Surface Temperature estimates. Water bodies influence the microwave observations and without proper mitigation they could result in unrealistic retrievals.
* Persistent cloud cover in highly dynamic landscape can decrease the downscaling method accuracy due to the optical observations by Sentinel-2 that are used for the LST 100 m products.
* False cloud/shadow detections may occur if surface conditions change very rapidly, during prolonged cloudiness, or over AOIs with significant terrain and shadowing. Significant effort has gone into developing automated techniques to differentiate between actual change and atmospheric contamination, but there may still be false detections.
## Frequently Asked Questions
### What do you actually measure?
We measure the skin temperature of the first thing in the line of sight of the satellite. This can be a roof, a tarmac road, a tree or crop canopy, bare soil or a mixture of land cover types.
### Do you measure the soil temperature?
No, we measure the temperature at the actual surface, the skin temperature. However, this is highly correlated to the soil temperature
### How accurate is the data?
Accuracy of the data is comparable with existing Land Surface Products products such as MODIS but we provide higher resolution and more valid data points. Check the [validation white paper](https://planet.widen.net/s/j9rl92dgpq) for actual numbers.
### How about frost use cases?
At the moment our LST should not be relied upon for below freezing point temperatures. Data below 263 kelvin (-10°C) is filtered out and data below 273 kelvin (0°C) should be treated with care.
### What type of satellites are used to determine Land Surface Temperature?
Most of the signal is from the passive microwave satellites (AMSR-2 and AMSR-E) and Sentinel-2 optical data is used to enhance to 100m. The passive microwave satellites measure microwave signals that are naturally radiating from the Earth’s surface. This enables observations to be acquired during cloudy conditions, because of the physical properties of waves transmitted in this spectrum’s range.
### What is the difference between the LST 100 m and 1000 m products?
Our LST 1000 m product is based on our patented disaggregation method where we make optimum use of the overlapping satellite footprints to refine the resolution from 36 km to 1 km. The LST 100 m product also uses the NIR and SWIR band from Sentinel-2 to add more spatial constraints to our disaggregation method.
### When is the data observed?
Currently, Planet uses the daytime and nighttime observations during the ascending and descending orbits, respectively. For AMSRE and AMSR2 this corresponds to 01:30 and 13:30 local solar time.
### What is the coverage of the data in terms of observations?
Each of the microwave satellites are on a sun-synchronous orbit. Using both orbit directions (ascending and descending) we can retrieve LST up to twice a day. The observation coverage is less frequent around the equator, where the Earth is ‘widest’ around its longitude belt, and more frequent at high latitudes, where the longitude belts are less wide.
One can expect between 180 (at equator) and 365 (above 50°N) daytime and nighttime measurements per year, depending on the geographical location.
*Land Surface Temperature animation of the 16-day AMSR2 cycle from 2024-06-02 to 2024-06-17*
### What about cloud cover?
The microwave part of the observations is not hindered by cloud cover. However, for downscaling to 100 m, we rely on near-infrared and shortwave infrared data that are sensitive to cloud cover. As such, there will be regions that will show artifacts in the 100 m data due to long periods with clouds. For all regions with > 70% cloud cover data should only be delivered to clients after a manual inspection (100 m only). This also means that the 100 m is less suitable for monitoring high temporal frequency changes (at the small scale) in cloudy regions.
### Can we measure water surface temperature?
No. The water bodies are removed from the signal because they may cause unrealistic Land Surface Temperature estimates. Water bodies influence the microwave observations and without proper mitigation they could result in unrealistic retrievals.
## Release notes
### Jun 1, 2025 - LST 20 m v1.0
New Features
* Increased spatial resolution (25x)
* Field-based processing
* Metadata as raster-level tags in each geotiff (1-band raster delivered per observation)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/soil-water-content/)
# Soil Water Content
Soil water content is the amount of water between the soil surface and the groundwater level in the unsaturated zone. This ratio of water volume to soil volume is crucial for understanding soil health, hydrological processes, and drought conditions.
The Planet Soil Water Content (SWC) product offers near-daily measurements with spatial resolutions of 20 m, 100 m, and 1000 m. Based on passive microwave observations, our data is consistent across time and space, strongly correlating with ground data and accurately reflecting weather patterns. This makes it a cost-effective and low-effort alternative to physical soil water content sensors.
## Use Cases
**Agriculture** - You can use SWC data to develop models that assess field conditions, enabling more informed decisions about irrigation and field operations. The data is also used to make yield and crop quality predictions at both regional and field scales.
**Drought Monitoring** - Tracking conditions over years and decades, SWC data provides a baseline understanding of normal and abnormal conditions for any given region. Leading reinsurers and brokers use the data in more than 20 countries to help protect farmers from drought impacts.
**Water Resource Management** - Near real-time SWC data aids in monitoring complex water systems by offering insights into water demand and storage capacity. With over two decades of archive data, water resource managers can track droughts, measure soil saturation, and assess intervention effects.
**Natural Disaster Risk Assessment** - Models incorporating vegetation, weather, and SWC data offer detailed insights into risks for wildfires, floods, and other natural disasters. The data also helps evaluate the impact of ecosystem restoration projects. Compared to in-situ sensors, SWC data provides a cost-effective and less labor-intensive method for risk assessment and remediation tracking.
## API Access Information
| API | Available | Notes |
| ----------------- | --------- | ----- |
| Data API | ❌ | |
| Orders API | ❌ | |
| Subscriptions API | ✅ | |
| Analytics API | ❌ | |
| Basemaps API | ❌ | |
### Subscriptions Access
#### Soil Water Content 20 m
warning
SWC 20 m is a beta product. This means the product is still under active development and may undergo changes to its methodology, accuracy, or availability. While the data is available for use, users should be aware that the product may have limitations or may be updated based on ongoing validation and feedback.
Loading...
The area of interest for SWC 20 m should correspond to a single agricultural field. If the AOI of a subscription includes multiple fields, whether they contain different crops or the same crop managed differently, the resulting SWC data will not accurately reflect conditions within any specific field. Similarly, if the AOI of a subscription includes non-agricultural areas, such as urban areas or water bodies, the resulting SWC data will not accurately reflect conditions within the AOI.
#### Soil Water Content 100 m
Loading...
#### Soil Water Content 1000 m
Loading...
For more information on the Subscriptions API and code samples, see the [API documentation](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types).
## Additional Resources
[🎓Planet University](https://university.planet.com/intro-to-soil-water-content)
[Learn the SWC basics with this introduction course.](https://university.planet.com/intro-to-soil-water-content)
[💡Blog posts](https://www.planet.com/pulse/tag/soil-water-content/)
[Read the latest SWC news and stories.](https://www.planet.com/pulse/tag/soil-water-content/)
[📖Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md)
[Get started with the Subscriptions API.](https://docs.planet.com/develop/apis/subscriptions.md)
[📓Jupyter Notebooks](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/api_guides/subscriptions_api/soil_water_content_gcp_delivery.ipynb)
[Access SWC and create visualizations with this tutorial.](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/api_guides/subscriptions_api/soil_water_content_gcp_delivery.ipynb)
[📖EvalScripts](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/soil-water-content/)
[Visualize SWC and extract insights with EvalScripts.](https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/soil-water-content/)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/soil-water-content/products/)
# Products
## Soil Water Content 20 m
Loading...
## Soil Water Content 100 m
Loading...
## Soil Water Content 1000 m
Loading...
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/soil-water-content/sandbox/)
# Soil Water Content Sandbox Data
This Planet Sandbox Data collection for Soil Water Content provides sample data over specific areas and times of interest. The data is available to paid and trial accounts that include processing units and is available under the CC-BY-NC license. Learn more about [Planet Sandbox Data](https://docs.planet.com/data/planet-sandbox-data.md).
## Data Collections Metadata
| Source ID | Collection Name | Collection ID | Time Range |
| ---------------------- | -------------------------------- | ----------------------------------------- | ----------------------- |
| SWC-SMAP-L\_V5.0\_1000 | Planet Sandbox Data - PV SWC 1km | BYOC-858254ae-0f29-4152-ac53-449efa00bbb0 | 2015-04-01 - 2023-12-31 |
## Planet Sandbox Data Areas
This collection includes 17 sandbox regions. Download the GeoJSON file below the map for exact polygon boundaries.
View all 17 regions
| Location | Area (km²) | Time Range | Center (lat, lon) |
| ------------------------------------------------- | ---------- | ----------------------- | ----------------- |
| Arizona, United States | 579 | 2015-04-01 – 2023-12-31 | 32.86, -111.85 |
| Alberta, Canada | 580 | 2015-04-01 – 2023-12-31 | 50.15, -111.78 |
| Iowa, United States | 2320 | 2015-04-01 – 2023-12-31 | 41.19, -93.81 |
| Goiás, Central-West Region, Brazil | 575 | 2015-04-01 – 2023-12-31 | -16.52, -48.83 |
| Autonomous Community of the Basque Country, Spain | 576 | 2015-04-01 – 2023-12-31 | 42.81, -2.51 |
| Nouvelle-Aquitaine, Metropolitan France, France | 2304 | 2015-04-01 – 2023-12-31 | 44.84, -0.52 |
| Flevoland, Netherlands | 579 | 2015-04-01 – 2023-12-31 | 52.50, 5.71 |
| Groningen, Netherlands | 576 | 2015-04-01 – 2023-12-31 | 53.15, 6.37 |
| Emilia-Romagna, Italy | 576 | 2015-04-01 – 2023-12-31 | 44.97, 9.81 |
| Epirus and Western Macedonia, Greece | 576 | 2015-04-01 – 2023-12-31 | 40.65, 21.76 |
| Attica, Greece | 576 | 2015-04-01 – 2023-12-31 | 38.02, 23.92 |
| Kitui County, Kenya | 578 | 2015-04-01 – 2023-12-31 | -1.34, 37.85 |
| Al Jawf Region, Saudi Arabia | 576 | 2015-04-01 – 2023-12-31 | 30.05, 38.42 |
| Haryana, India | 578 | 2015-04-01 – 2023-12-31 | 27.86, 77.36 |
| Thái Bình Province, Vietnam | 576 | 2015-04-01 – 2023-12-31 | 20.51, 106.30 |
| Guizhou, Tongren, China | 575 | 2015-04-01 – 2023-12-31 | 28.09, 109.21 |
| New South Wales, Australia | 581 | 2015-04-01 – 2023-12-31 | -34.52, 146.13 |
[Download GeoJSON](https://docs.planet.com/data/planetary-variables/soil-water-content/polygons.geojson)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/planetary-variables/soil-water-content/techspec/)
# Technical Specification
## Overview
Soil water content (SWC) is an essential component of the hydrologic cycle. Also known as soil moisture, it refers to the water between the soil surface and the groundwater level in the unsaturated zone. This water is replenished by precipitation, irrigation, or capillary rise from deeper layers, and depleted by percolation, soil evaporation, and plant transpiration.
The Planet Soil Water Content product is based on the microwave radiation naturally emitted by the Earth. This passive microwave radiation is related to the water content in the soil and provides a direct measurement of water in the top layer of the soil. It is not sensitive to cloud cover and, therefore, allows for consistent, frequent, and global coverage.
The Planet patented algorithm enhances the spatial resolution of the passive microwave observations and the physical-based Land Parameter Retrieval Model retrieves the soil water content. Optical imagery from Sentinel-2 is used to further improve the spatial resolution.
Planet provides SWC data at 20, 100, and 1000 meter resolutions. With an archive spanning over 20 years, the data is consistent across time and space, boasting a strong correlation with ground data and accurately reflecting weather patterns. It is a cost-effective and low-effort alternative for measuring soil water content with physical sensors, making it suitable for many use cases like agriculture, water management, and insurance.
*Figure 1: Measurements of SWC near Ahlen, in North Rhine-Westphalia, Germany. The measurements of SWC of a single point are plotted over 5 years with the baseline climatology, showing how soil water content levels compare to the expected average for the area.*
## Product Specifications
warning
SWC 20 m is a beta product. This means the product is still under active development and may undergo changes to its methodology, accuracy, or availability. While the data is available for use, users should be aware that the product may have limitations or may be updated based on ongoing validation and feedback.
*Table 1: SWC 20 m product specification*
| Data Resource | SWC 20 m |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Source ID | SWC-field\_V1.0\_20 |
| Satellites Used | AMSR-2, AMSR-E, SMAP, Sentinel-2 |
| Band | L, C and X-band |
| Version | 1.0 |
| Unit | m³/m³ |
| Sensing Depth | \~5 cm |
| Pixel Size | 20x20 m |
| Temporal Resolution | 267-364 observations/year |
| Overpass Time | 06:00 local solar time |
| Geographical Coverage | Global |
| Data Availability | 2018-01-01 - Present
Data Gaps:
2019-06-19 to 2019-07-24
2022-08-05 to 2022-09-24
2022-11-16 to 2022-11-18 |
*Table 2: SWC 100 m product specification*
| Data Resource | SWC 100 m L band | SWC 100 m C band | SWC 100 m X band |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Source ID | SWC-SMAP-L\_V2.0\_100 | SWC-AMSR2-C\_V2.0\_100 | SWC-AMSR2-X\_V2.0\_100 |
| Satellites Used | AMSR-2, SMAP, Sentinel-2 | AMSR-2, Sentinel-2 | AMSR-2, Sentinel-2 |
| Band | L band | C band | X band |
| Version | 2.0 | 2.0 | 2.0 |
| Unit | m³/m³ | m³/m³ | m³/m³ |
| Sensing Depth | \~5 cm | \~2 cm | \~1 cm |
| Pixel Size | 100x100 m | 100x100 m | 100x100 m |
| Temporal Resolution | 0° latitude: 137 to 183 observations per year
40° latitude: 183 to 228 observations per year | 0° latitude: 205 to 228 observations per year
40° latitude: 274 to 292 observations per year | 0° latitude: 205 to 228 observations per year
40° latitude: 274 to 292 observations per year |
| Overpass Time | 06:00 local solar time | 01:30 local solar time | 01:30 local solar time |
| Geographical Coverage | Global | Global | Global |
| Data Availability | 2017-07-01 - Present
Data Gaps:
2019-06-19 to 2019-07-24
2022-08-05 to 2022-09-24
2022-11-16 to 2022-11-18 | 2017-07-01 - Present | 2017-07-01 - Present |
| NRT latency (p90) | 72 hours | 48 hours | 48 hours |
| Archive latency | Within 30 days after creating a subscription | Within 30 days after creating a subscription | Within 30 days after creating a subscription |
*Table 3: SWC 1000 m product specification*
| Data Resource | SWC 1000 m L band | SWC 1000 m C band | SWC 1000 m X band |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Source ID | SWC-SMAP-L\_V5.0\_1000 | SWC-AMSR2-C\_V5.0\_1000
(2012 - present)
SWC-AMSRE-C\_V5.0\_1000
(2002 - 2011) | SWC-AMSR2-X\_V5.0\_1000
(2012 - present)
SWC-AMSRE-X\_V5.0\_1000
(2002 - 2011) |
| Version | 5.0 | 5.0 | 5.0 |
| Unit | m³/m³ | m³/m³ | m³/m³ |
| Sensing Depth | \~5 cm | \~2 cm | \~1 cm |
| Pixel Size | 1000x1000 m | 1000x1000 m | 1000x1000 m |
| Temporal Resolution | 0° latitude: 137 to 183 observations per year
40° latitude: 183 to 228 observations per year | 0° latitude: 205 to 228 observations per year
40° latitude: 274 to 292 observations per year | 0° latitude: 205 to 228 obs/year
40° latitude: 274 to 292 obs/year |
| Overpass Time | 06:00 local solar time | 01:30 local solar time | 01:30 local solar time |
| Geographical Coverage | Global | Global | Global |
| Data Availability | 2015-04-01 - Present
Data Gaps:
2019-06-19 to 2019-07-24
2022-08-05 to 2022-09-24
2022-11-16 to 2022-11-18 | 2002-06-15 - Present
Data gap:
2011-10-04 to 2012-07-25 | 2002-06-15 - Present
Data gap:
2011-10-04 to 2012-07-25 |
| Satellites Used | AMSR-2, SMAP | AMSR-E, AMSR-2 | AMSR-E, AMSR-2 |
| NRT latency (p90) | 72 hours | 24 hours | 24 hours |
| Archive latency | Within 30 days after creating a subscription | Within 30 days after creating a subscription | Within 30 days after creating a subscription |
The sensing depth described in the table is an estimation of the average condition. Several studies (For example, [Schmugge et al., 1986](https://ieeexplore.ieee.org/abstract/document/4072415); [Wang et al., 1987](https://ieeexplore.ieee.org/document/4072692); [Owe et al., 1998](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/98WR01469)) have shown that microwave-based soil water content penetration depth depends on the soil water content conditions and frequency. At 1.41 GHz the penetration depth varies from approximately 10 cm to 1 m for soil conditions ranging from saturated to dry, whereas at 10.7 GHz the penetration depth varies from less than a few mm to a little over 2 cm for similar conditions. Thus, the drier the soil, the deeper the sampling depth.
## Asset Properties
Assets differ between field-based and tile-based data resources:
* **SWC 20 m (field-based)**: Each observation is delivered as a single-band asset with metadata embedded in the GeoTIFF.
* **SWC 100 m and SWC 1000 m (tile-based)**: Each observation is delivered as a SWC data asset (`*swc.tif`) with metadata provided in a separate quality flag asset (`*swc-qf.tif`).
*Table 4: Asset properties of SWC 20 m data resources*
| Asset Name | Band Name | Unit | Type | Typical Range | No Data Value | Scale | Format |
| ---------- | --------- | ----- | ------ | ------------- | ------------- | ----- | ------- |
| swc | Band 1 | m3/m3 | UINT16 | 0 - 1 | 65535 | 0.001 | GeoTIFF |
*Table 5: Asset properties of SWC 100 m and SWC 1000 m data resources*
| Asset Name | Band Name | Unit | Type | Typical Range | No Data Value | Scale | Format |
| ---------- | --------- | -------- | ------ | ------------- | ------------- | ----- | ------- |
| swc | Band 1 | m3/m3 | UINT16 | 0 - 1 | 65535 | 0.001 | GeoTIFF |
| swc | Band 2 | m3/m3 | UINT16 | 0 - 1 | 65535 | 0.001 | GeoTIFF |
| swc-qf | Band 1 | unitless | UINT16 | NA | 0 | 1 | GeoTIFF |
## Methodology
### Passive Microwaves and Downscaling Method
The Planet Soil Water Content data is derived from satellite sensors that measure passive microwave radiation. Passive microwave technology detects natural microwave emissions from the Earth's surface, which are sensitive to soil water content.
Using a patented algorithm ([US10643098](https://patentimages.storage.googleapis.com/1a/6f/1c/8cf51399ee7eaa/US10643098.pdf), [EP3469516B1](https://patentimages.storage.googleapis.com/f1/6c/0b/55cad50731d3e0/EP3469516B1.pdf)), we combine and downscale observations from multiple satellite constellation to a spatial resolution of 1000 m. We create footprints based on the footprint center, microwave frequency, incidence angle, azimuth angle, and footprint size, and then disaggregate them into equal interval ellipses using an internal Gaussian distribution. Within these ellipse-shaped footprints, the center contributes more to the observed values than the edges. By using fixed values for water bodies and filtering out influences such as radio frequency interference (RFI), we ensure accurate brightness temperatures.
### Enhancements Using Optical Data
The microwave observations are further downscaled to a spatial resolution of 100 m based on the Normalized Difference Shortwave Infrared (NDSWIR) index. This index is constructed from Near-Infrared (NIR) and Shortwave Infrared (SWIR) bands of Sentinel-2, namely B08 (842 nm) and B11 (1610 nm).
Several studies ([Lobell & Asner 2002](https://doi.org/10.2136/sssaj2002.7220), [Fensholt and Sandholt 2003](https://www.sciencedirect.com/science/article/abs/pii/S0034425703001895), [Sadeghi et al. 2017](https://doi.org/10.1016/j.rse.2017.05.041), [Yue et al. 2019](https://doi.org/10.1016/j.isprsjprs.2019.06.012)) found that soil and plant water content significantly affect the reflection in the SWIR part of the spectrum. The NIR reflectance is influenced by the internal structure and dry matter content of leaves, but not by water content. By combining SWIR, which responds to water content, with NIR reflectance, we can more accurately retrieve water content from the reflectance data ([Gao 1996](https://doi.org/10.1016/S0034-4257\(96\)00067-3), [Ceccato et al. 2001](https://doi.org/10.1016/S0034-4257\(01\)00191-2)).
Planet produces a daily NDSWIR composite using a backward Gaussian weighted distribution. This composite integrates into the downscaling framework by attributing the weight of a brightness temperature to each pixel within the footprint. The output format remains similar to that of the downscaling algorithm without NDSWIR input.
The Sentinel-2 data is extracted from L2A - Bottom of the atmosphere (BOA) - reflectance in the [Sentinel-2 dataset documentation](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md).
### Physical-Based Land Parameter Retrieval Model
The downscaled high resolution microwave observations are converted to soil water content using the physical-based Land Parameter Retrieval Model (LPRM) ([Owe et al. 2001](https://ieeexplore.ieee.org/abstract/document/942542); [Owe et al. 2008](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2007JF000769); [De Jeu et al. 2014](https://www.sciencedirect.com/science/article/abs/pii/S0022169414001139), [Van der Schalie et al., 2018](https://www.mdpi.com/2072-4292/10/1/107), [Van der Schalie et al., 2018](https://www.mdpi.com/2072-4292/13/13/2480)).
The basis for the retrieval relies on the fact that thermal radiation in the microwave region is emitted by all natural surfaces as a function of temperature. The propagation of microwaves through the soil is then dependent on the soil dielectric constant, which has an almost linear relationship with soil water content. Microwave technology is the only remote sensing method that measures a direct response to the absolute amount of water in the soil, with a sensing depth ranging from millimeters for 37 GHz to tens of cm for 1.4 GHz. Vegetation also contributes to the microwave signal by absorbing, reflecting, and emitting radiation.
LPRM solves the radiative transfer equation at different frequencies and polarizations to retrieve soil water content and is currently the baseline algorithm for the ESA Climate Change Initiative (CCI) soil moisture products ([Scanlon et al., 2021](https://esa-soilmoisture-cci.org/sites/default/files/documents/public/CCI%20SM%20v06.1%20documentation/ESA_CCI_SM_RD_D2.1_v2_ATBD_v06.1_issue_1.1.pdf)).
### Input Data
*Table 6: List of inputs for Soil Water Content production*
| Product | Description |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Brightness Temperature L band | Soil Moisture Active Passive (SMAP) Level-1B Radiometer Half-Orbit Time-Ordered L band Brightness Temperatures, Version 5 (downloaded from [NSIDC](https://nsidc.org/data/spl1btb/) in HDF5 format). This Level-1B product provides calibrated estimates of time-ordered geolocated brightness temperatures at 1.41 GHz with a footprint size of 39x47 km. SMAP L band brightness temperatures are referenced to the Earth's surface with undesired and erroneous radiometric sources removed. Data has been available since April 2015 with a latency of 12 hours. Detailed information is available [here](https://nsidc.org/sites/default/files/smap_atbd_radiometerl1b_tb_rev-b_20150401.pdf). |
| Brightness Temperature X band | Advanced Microwave Scanning Radiometer for EOS (AMSR-E) and Advanced Microwave Scanning Radiometer 2 (AMSR-2) Level-1B Radiometer X band Brightness Temperatures (downloaded from [JAXA G-portal](https://gportal.jaxa.jp/gpr/?lang=en) in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 10.7 GHz with a footprint size of 24x42 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf) |
| Brightness Temperature C band | AMSR-E and AMSR-2 Level-1B Radiometer C band Brightness Temperatures (downloaded from [JAXA G-portal](https://gportal.jaxa.jp/gpr/?lang=en) in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 6.9 GHz with a footprint size of 35x62 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf). |
| Brightness Temperature Ka band | AMSR-E and AMSR-2 Level-1B Radiometer Ka band Brightness Temperatures (downloaded from [JAXA G-portal](https://gportal.jaxa.jp/gpr/?lang=en) in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 36.5 GHz with a footprint size of 7x12 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf). |
| Brightness Temperature W band | AMSR-E and AMSR-2 Level-1B Radiometer W band Brightness Temperatures (downloaded from JAXA G-portal in HDF5 format). This Level-1B product provides calibrated estimates of geolocated brightness temperatures at 89 GHz with a footprint size of 3x5 km. Data has been available from July 2002 to October 2011 (AMSR-E) and from June 2012 (AMSR-2) up to now with a latency of 12 hours. Detailed information is available [here](https://gportal.jaxa.jp/gpr/assets/mng_upload/GCOM-W/AMSR2_Level1_Product_Format_EN.pdf). |
| Reflectances SWIR and NIR (for SWC 20 m/100 m) | Sentinel-2 Level-2A reflectance [data](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md) for two bands: SWIR (shortwave infrared around 1610 nm) and NIR (near infrared around 842 nm). |
| Digital Elevation Model | Digital elevation model (DEM) static map resampled at 100 m based on the Copernicus DEM GLO-90 product covering the full global landmass of the time frame of data acquisition (2011-2015). Detailed information is available in the link. |
| Land Cover Map | Custom global land classification including permanent water bodies based on the Copernicus Global Surface Water Bodies product from PROBA-V. Detailed information is available [here](https://land.copernicus.eu/global/) |
| Soil Map | Soil property maps resampled at 100 m based on the SoilGrids product. SoilGrids was funded by the core funding of ISRIC with additional support from the EUH2020 CIRCASA project. Detailed information is available [here](https://www.isric.org/explore/soilgrids), |
## Data Quality
### Uncertainty
The accuracy of soil water content retrievals from passive microwave observations and in particular the performance of the Land Parameter Retrieval Model has been described widely in the scientific literature: it has been compared to ground stations, hydrological models, and other satellite-derived products (for example, [Van der Schalie et al., 2021](https://www.mdpi.com/2072-4292/13/13/2480); [Gruber et al., 2020](https://www.sciencedirect.com/science/article/pii/S0034425720301760); [Gevaert et al., 2018](https://hess.copernicus.org/articles/22/4605/2018/)).
The accuracy of the retrievals depends on the microwave frequency. L-band soil water content has the highest accuracy of approximately 0.04 m³/m³, which is comparable to the accuracy of ground sensors (for example, see [Ganjegunte et al., 2012](https://link.springer.com/article/10.1007/s13201-012-0032-7)). The accuracy of the C and X band based products is approximately 0.05 m³/m³. In addition, the accuracy is a direct function of the vegetation cover as demonstrated by [Van der Schalie et al., 2018](https://www.mdpi.com/2072-4292/10/1/107).
The X and C band based retrievals are most sensitive to the density of the vegetation cover and provide the most reliable values with short vegetation. L band retrievals perform well over the majority of land covers, with the exception of dense tropical rainforest.
### Validation
We have evaluated our SWC products by comparing them to carefully picked ground data stations across various land cover types. The Pearson correlation coefficient varied between 0.53 and 0.92, indicating strong relations with ground truth data. Figure 2 shows a comparison between SWC data and ground data.
You can read more about the results in [this white paper](https://planet.widen.net/s/drrxtldpwg).
*Figure 2: Time series of the average of 9 stations of the RAAM network, the Netherlands.*
### Metadata
#### SWC 20 m
Metadata embedded in the GeoTIFF contains information about the quality of the observation. For example:
| Field | Type | Description | Example |
| ------------------- | ----------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
| `PRODUCT_VERSION` | String | Version identifier for the product specification | `v1` |
| `SOFTWARE_VERSION` | String | Version of the fbsl software that generated the output | `0.4.1` |
| `INPUT_ASSETS` | String | Comma-separated list of input data sources used | `NDSWIR_STATS,NDSWIR_RASTER,KA_V_DESC_STATS` |
| `LAST_NDSWIR_DATE` | String (ISO date) | Date of the last NDSWIR (Sentinel-2) observation with full coverage | `2024-01-19` |
| `LAST_NDSWIR_COV` | String (fraction) | Coverage fraction of the last NDSWIR observation used | `0.85` (= 85% coverage) |
| `QUALITY` | String | Overall quality assessment: `HIGH` if valid coverage > 80%, otherwise `LOW` | `HIGH` or `LOW` |
| `FUSION` | String | Whether L-band fusion was applied | `YES` or `NO` |
| `DIVERGENCE_COV` | String (fraction) | Fraction of pixels where LPRM algorithm did not converge | `0.05` (= 5% divergence) |
| `QA_MDPI_LT_0_0001` | String (fraction) | Fraction of pixels with Modified Dual Polarization Index < 0.0001 | `0.12` (= 12% of pixels) |
| `QA_NO_COVERAGE` | String (fraction) | Fraction of pixels with no microwave coverage | `0.0` (= 0% missing) |
| `QA_FREEZING` | String (fraction) | Fraction of pixels flagged as freezing conditions | `0.0` (= 0% frozen) |
#### SWC 100 m and SWC 1000 m
Quality flag assets (`*swc-qf.tif`) provide metadata for each pixel using bitwise flags. Critical flags indicate unreliable data, with corresponding pixels in band 1 of the SWC asset (`*swc.tif`) set to the no data value. The replaced SWC value can be found in band 2 of the SWC asset. Non-critical flags indicate that the data can be used with caution, taking into account the flag description.
Critical and non-critical flags are described in the tables below. For more information on how to access the quality flag asset, check out [subscribing to planetary variables](https://docs.planet.com/develop/apis/subscriptions/sources.md).
*Table 7: Non-critical flags*
| Bit | Flag layer | Description |
| --- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Dense vegetation | The retrieved soil water content is less reliable over dense vegetation cover. |
| 2 | Low soil water content | The retrieved soil water content is lower than the estimated wilting point. |
| 3 | High soil water content | The retrieved soil water content is higher than the estimated porosity. |
| 4 | Possible severe precipitation | Part of the footprints touch an area flagged as severe precipitation. |
| 5 | Possible RFI | Footprints are contaminated for less than 25% with Radio Frequency Interference (RFI). RFI occurs when human-made transmitters emit in the same frequencies and thus disrupt the radiometer measurements of the natural microwave emission. |
| 7 | Possible frozen soil | The soil may be frozen. These are pixels with a soil temperature between -10°C and 0°C. |
*Table 8: Critical flags*
| Bit | Flag layer | Description |
| --- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 6 | Statistical outlier | The underlying footprint is considered a statistical outlier. |
| 8 | Frozen soil | The soil is frozen. Pixels with a soil temperature below -10°C. A conservative value of -10°C was chosen to avoid masking valid data. |
| 9 | Severe precipitation | Severe precipitation is detected. |
| 10 | Vegetation too dense | The vegetation cover is too dense for the algorithm to reliably retrieve soil water content. |
| 11 | No overpass | The satellite did not pass over. |
| 12 | RFI | Footprints are contaminated for more than 25% with Radio Frequency Interference (RFI). RFI occurs when human-made transmitters emit in the same frequencies and thus disrupt the radiometer measurements of the natural microwave emission. |
| 13 | Instrumental flaws | Unrealistic values due to instrumental flaws. If the brightness temperature at 36.5 GHz V produces values either over 400K or under 0.9 \* the water temperature, the data is considered as unrealistic and is removed. |
| 14 | Out of valid range | Soil water content values are outside the valid range, meaning under 0 m3/m3 or above 1 m3/m3. |
| 15 | Open water | Soil water content is not defined over water. |
| 16 | Brightness temperature residuals too high | The LPRM model could not find a soil water content value that is consistent with all provided input data. |
*Figure 3: An example of two quality flags for a region around Nantes, France. The image shows critical flags 'open water' and 'no overpass' overlaid on SWC 100 m.*
The following Python script converts a quality flag pixel value into a list of corresponding quality flags. Note that one pixel may have multiple flags applied to it.
```
# swc_quality_flags.py
import argparse
SWC_QUALITY_FLAGS = {
1: "Dense vegetation",
2: "Low soil water content",
3: "High soil water content",
4: "Possible severe precipitation",
5: "Possible RFI",
6: "Statistical outlier (critical flag)",
7: "Possible frozen soil",
8: "Frozen Soil (critical flag)",
9: "Severe precipitation (critical flag)",
10: "Vegetation too dense (critical flag)",
11: "No overpass (critical flag)",
12: "RFI (critical flag)",
13: "Instrumental flaws (critical flag)",
14: "Out of valid range (critical flag)",
15: "Open water (critical flag)",
16: "Brightness temperature residuals too high (critical flag)",
}
def convert_to_quality_flags(decimal_value: int) -> list[str]:
binary_string = format(decimal_value, "016b")
reversed_binary_string = binary_string[::-1]
return [
f"{i}. {SWC_QUALITY_FLAGS.get(i, 'Unused flag')}"
for i, bit in enumerate(reversed_binary_string, start=1) if bit == "1"
]
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Convert a decimal value to quality flags.")
parser.add_argument("decimal_value", type=int, help="The decimal value to convert.")
args = parser.parse_args()
flags = convert_to_quality_flags(args.decimal_value)
print(*flags, sep="\n")
```
that you can call as follows, using value `32770` as example:
```
> python swc_quality_flags.py 32770
2. Low soil water content
16. Brightness temperature residuals too high (critical flag)
```
## Other Limitations
The following are some key limitations that we have not flagged:
* SWC data should be considered unreliable over sloped terrain that is over 20 degrees. The microwave signal can be distorted by the angle of the slope, causing changes in the observed brightness temperature. This distortion leads to inaccuracies in the soil water content estimates because the algorithms assume a flat surface. Data usually shows up unrealistically dry.
* SWC data should be considered unreliable over urban areas. Human-made surfaces like concrete and asphalt have different microwave emissivity properties than natural soil. These surfaces can cause reflections and scattering of the microwave signal, leading to incorrect soil water content retrieval. Moreover, because urban areas have such a wide range of land cover types (asphalt, concrete, roofs, parks, gardens, etc) the average SWC value is not representative of any specific land cover type.
* Dynamic water bodies may cause unrealistic soil water content estimates. Water bodies influence the microwave observations and without proper mitigation they could result in unrealistic retrievals. Data around dynamic waterbodies can show up drier or wetter.
* Cloud cover hinders the optical observations by Sentinel-2 that are used for the SWC 100 m products. The downscaling can therefore only be updated when we obtain a cloud-free observation and the SWC data may suddenly increase or decrease after a long spell of no observations.
* False cloud/shadow detections may occur if surface conditions change very rapidly, during prolonged cloudiness, or over AOIs with significant terrain and shadowing. Significant effort has gone into developing automated techniques to differentiate between actual change and atmospheric contamination, but there may still be false detections.
* The SWC product integrates passive microwave data streams from multiple satellite missions. In rare instances where source data is completely unavailable, Planet cannot calculate SWC for that specific date. Once the 30-day reanalysis window closes, any such missing date in the subscription will be designated with a READY\_NO\_DATA status.
## Frequently Asked Questions
### There are three different bands for soil water content. What is a 'band' and which one should I use?
We use passive microwave observations to measure soil water content. A microwave signal is a light signal with a frequency that is much lower than the frequency of visible light. The lower the frequency of the passive microwaves, the more they tell us about what happens below the ground. A “band” refers to the frequency band we use to measure SWC. The lowest frequency band we deliver is the L-band (1.4 GHz), which is measured by the SMAP satellite. This measurement shows the water content in the top 5 cm of the soil. Other frequencies we deliver are the C-band (6.9 GHz), which shows the water content in the top 2 cm, and X-band (10.7 GHz), showing the top cm of the soil. The X-band and C-band measurements come from the AMSR-2 satellite.
For most use cases, L-band measurements are the best choice:
* They are representative of a deeper layer than the other bands.
* Vegetation on top of the soil has a much lower impact on the signal than for other bands.
* L-band observations are more sensitive to soil water content changes than the other bands: per unit change in soil water content, the microwave soil emission changes are stronger for L-band than for higher frequencies like C-band. This higher sensitivity leads to more accurate and precise SWC observations.
There are however some situations where the other bands are a better choice:
* Sometimes, radio signals emitted from the Earth interfere with the soil water content signals. We call this effect “radio frequency interference” (RFI). We filter for RFI, but sometimes the filter does not filter out everything, leading to strange SWC values. When this happens in the L-band for a specific location, use X-band or C-band.
* AMSR-2 provides the observations for X-band and C-band SWC. AMSR-2 data is available from 2012 onwards, and can be combined with data from its predecessor (AMSR-E) to compute long SWC time series, all the way back to 2002. When a customer wants to have a long time series, C-band and X-band data can go back to 2002. Our L-band product can provide SWC data from 2015 to present.
### What is the difference between the SWC 20 m, 100 m, and 1000 m products?
Our SWC 1000 m product is based on our patented disaggregation method where we make optimum use of the overlapping satellite footprints to refine the resolution from 36 km to 1 km. The SWC 100 m product also uses the NIR and SWIR band from Sentinel-2 to add more spatial constraints to our disaggregation method.
### Why does the SWC 1000 m product show a higher correlation with in-situ measurements than the SWC 100 m product?
Sometimes, customers compare our SWC products with in-situ measurements and find that the SWC 1000 m products perform better than the SWC 100 m products. This can be explained by the method used to enhance the spatial resolution. The SWC 1000 m product uses passive microwave observations, and has a temporal resolution of about 2 days, depending on the microwave band used and the latitude.
As a result, the SWC 1000 m product sees a lot of the temporal variations in SWC which are also caught by the in-situ sensor. For the enhanced-resolution products, we combine the passive microwave observations with infrared observations from the Sentinel-2 satellite. The infrared observations have a repeat cycle of about 5 days, depending on the latitude, but they cannot be made on cloudy days. The infrared data tell us how the soil water content is spatially divided within the coarser SWC 1000 m product and thus can accurately tell us which fields are relatively wet or dry, compared to the environment. However, the lower temporal resolution of the infrared data can cause the correlation coefficient to drop compared to the SWC 1000 m product. The enhanced-resolution product does get updated every time a new passive microwave observation comes in, but the temporal changes that result from the infrequent infrared observations can cause a degradation in the correlation.
Therefore, when a customer is interested mostly in the temporal changes, often the 1km products are the best choice. When they are interested in the spatial variations, the enhanced-resolution product can tell which areas are relatively dry or wet, compared to the environment.
### Is SWC a modeled product or an observation?
The brightness temperatures are direct observations by the satellite. These observations are used in a physical-based radiative transfer model to retrieve soil water content. However, considering the strong physical description of the radiative transfer model, scientists often refer to passive microwave soil water content as satellite-observed.
## Release notes
### June 1, 2025 - SWC 20 m v1.0
New Features:
* Increased spatial resolution for L-band product (25x)
* Field-based processing
* Metadata as raster-level tags in each geotiff (1-band raster delivered per observation)
### November 14, 2023 - SWC 1000 m V5.0 and SWC 100 m V2.0
New Features:
* Increased temporal resolution for L-band products
* Enhanced outlier detection capabilities
* Improved parameterization of the SWC retrieval model
* Refined water-body mask, enabling pixel size reduction from 1000m to 100m while maintaining consistent spatial support
* Updated quality flags for more accurate data assessment
warning
These new versions are not compatible with previous versions. Combining datasets from different versions may introduce offsets and scale discrepancies. We strongly advise against merging data from old and new versions.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/)
# Public Data
Planet provides access to a curated set of public Earth observation datasets from Copernicus, USGS, and NASA through the [Planet Insights Platform](https://insights.planet.com/).
## Public Data Catalog
[](https://docs.planet.com/data/public-data/copernicus.md)
### [Copernicus Imagery](https://docs.planet.com/data/public-data/copernicus.md)
[](https://docs.planet.com/data/public-data/other-datasets.md)
### [Other Datasets](https://docs.planet.com/data/public-data/other-datasets.md)
[](https://docs.planet.com/data/public-data/usgs-nasa.md)
### [USGS & NASA Imagery](https://docs.planet.com/data/public-data/usgs-nasa.md)
## Main Deployments
### EU-Central-1 (Frankfurt) Region
**API endpoint:** `services.sentinel-hub.com/`
| Collection | Description | Coverage |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| [Sentinel-1 GRD](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md) | C-band SAR imagery from the Sentinel-1 mission | Global since January 2017 |
| [Sentinel-2 L1C](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md) | Multispectral imagery from the Sentinel-2 mission | Global since November 2015 |
| [Sentinel-2 L2A](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md) | Atmospherically corrected multispectral imagery from Sentinel-2 | Europe since November 2016
Global since January 2017 |
| [Digital Elevation Model](https://docs.planet.com/data/public-data/other-datasets/dem.md) | Global digital elevation models from Copernicus and Mapzen | Global |
| [BYOC](https://docs.planet.com/develop/apis/byoc.md#accessing-byoc-data) | User-provided raster data imported for processing and analysis | Depends on data |
### US-West-2 (Oregon) Regions
**API endpoint:** `services-uswest2.sentinel-hub.com/`
| Collection | Description | Coverage |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------- |
| [Landsat 8 L1](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9.md) | Multispectral imagery from the Landsat 8 and 9 missions | Global since February 2013 |
| [Landsat 8 L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9.md) | Atmospherically corrected multispectral imagery from Landsat 8 and 9 | Global since February 2013 |
| [Landsat 7 L1](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm.md) | Multispectral imagery from the Landsat 7 mission | Global since April 1999 |
| [Landsat 7 L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm.md) | Atmospherically corrected multispectral imagery from Landsat 7 | Global since April 1999 |
| [Landsat 4-5 TM L1](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm.md) | Multispectral imagery from the Landsat 4 and 5 missions (TM) | Global from July 1982 to May 2012 |
| [Landsat 4-5 TM L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm.md) | Atmospherically corrected multispectral imagery from Landsat 4 and 5 (TM) | Global from July 1982 to May 2012 |
| [Harmonized Landsat Sentinel HLS](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel.md) | Harmonized surface reflectance from Landsat 8–9 OLI and Sentinel-2 MSI sensors | Global since April 2013 |
| [Digital Elevation Model](https://docs.planet.com/data/public-data/other-datasets/dem.md) | Digital elevation model data by [Mapzen](https://github.com/tilezen/joerd/tree/master/docs) | Global |
| [BYOC](https://docs.planet.com/develop/apis/byoc.md#accessing-byoc-data) | User-provided raster data imported for processing and analysis | Depends on data |
note
For consistency of the documentation all further examples will be based on `services.sentinel-hub.com/` end-point. To access Landsat or DEM data, you can simply replace “**services**” with “**services-uswest2**” to get the applicable results.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/copernicus/)
# Copernicus Imagery
[](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md)
### [Sentinel 1 GRD](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md)
[Use Processing API to access Sentinel-1 (C-band synthetic aperture radar imaging) data.](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd.md)
[](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md)
### [Sentinel 2 L1C & L2A](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md)
[Use Processing API to access Sentinel-2 data.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/)
# Sentinel 1 GRD
Sentinel-1 imagery is provided by a constellation of polar-orbiting satellites, operating day and night performing C-band synthetic aperture radar (SAR), enabling acquisitions regardless of weather conditions. Main applications include monitoring sea ice, oil spills, marine winds, waves and currents, land-use change, land deformation, and supporting rapid response to emergencies such as floods and earthquakes.
note
On December 23, 2021, one of the two satellites Sentinel-1B encountered an anomaly of the power unit, causing SAR functionality to be lost, and the satellite will be intentionally deorbited in the future. Thus, between December 23, 2021 and March 26, 2025 (beginning of data availability after successful launch of Sentinel-1C [1](https://dataspace.copernicus.eu/news/2025-3-25-sentinel-1c-user-data-opening-26th-march#:~:text=Initial%20access%20to%20Sentinel%2D1C%20data%20is%20available,*%20Data%20calibration%20and%20validation%20remain%20preliminary)) only data from Sentinel-1A is available, which means some areas lost coverage completely, and many others had longer revisit times.
Planet provides access to Sentinel-1 Level-1 GRD (Ground Range Detected) products only. You can explore these datasets in the [Browser](https://insights.planet.com/analyze/browser/). Sentinel-1 products are released under the [Sentinel Data Legal Notice](https://sentinels.copernicus.eu/documents/247904/690755/Sentinel_Data_Legal_Notice).
## Acquisition Modes and Polarizations
Sentinel-1 operates in four acquisition modes (IW, EW, SM, WV), which determine resolution, swath width, and polarization options. ESA uses predefined [Observation Scenarios](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-ObservationandProductionScenariosS1-Mission-Observation-and-Production-Scenarios) to schedule these acquisitions globally, ensuring systematic coverage of land, oceans, and polar regions.
Source: European Space Agency (ESA).
The figure shows the global Sentinel-1 observation scenario, with acquisition modes, polarization schemes, and orbit directions planned across different regions. This scenario ensures systematic coverage of land, ocean, and polar areas.
For more information, see the [Sentinel-1 Mission Overview](https://sentiwiki.copernicus.eu/web/s1-mission) and the [Sentinel-1 Applications and User Guide](https://sentiwiki.copernicus.eu/web/s1-applications).
## Processing
Sentinel-1 GRD data is processed on demand through the Processing API. By configuring processing parameters such as calibration, terrain correction, and speckle filtering, you can generate outputs ranging from minimally processed radar backscatter to fully analysis-ready products.
The following steps describe the available processing operations:
* **Source selection**: original or multilooked imagery is chosen depending on resolution.
* **Calibration and noise removal**: radiometric calibration is applied to the selected backscatter coefficient, and thermal noise is removed.
* [**Speckle filtering**](#speckle-filtering): optional speckle filtering methods are available and can be enabled through processing options.
* **Radiometric terrain correction (optional)**: applies radiometric terrain correction using [area integration](https://ieeexplore.ieee.org/document/5752845) when the backscatter coefficient is set to `GAMMA0_TERRAIN`, using a [digital elevation model (DEM)](https://docs.planet.com/data/public-data/other-datasets/dem.md).
* **Orthorectification (optional)**: Range-Doppler geometric terrain correction using a DEM.
Processing details
* Orbit files included in the products are used and sufficient for GRD applications.
* Areas of border noise are masked.
* Radiometric terrain correction requires orthorectification to be enabled.
* DEM oversampling defaults to 2 but can be adjusted for better results at coarse resolution.
## Accessing Sentinel-1 GRD Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the data collection you are querying. This chapter will help you understand the parameters for S1GRD data. To see examples of such requests go [here](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/examples.md), and for an overview of all API parameters see the S1GRD [API Reference](https://docs.planet.com/develop/apis/processing/reference.md).
### Endpoint Locations
| Service | Notes |
| -------------------------- | ------------------------- |
| services.sentinel-hub.com/ | Global since October 2014 |
#### Processing Behavior
* **Features:** Zooming out will use multi-looked sources at an appropriate resolution to your viewing level. You can therefore expect high quality results at all zoom levels.
* **Backscatter coefficients:** We support all backscatter coefficients.
### Data type identifier: `sentinel-1-grd`
Use `sentinel-1-grd` (previously `S1GRD`) as the value of the `input.data.type` parameter in your API requests. This is mandatory and will ensure you get Sentinel-1 GRD data.
### Filtering Options
This chapter will explain the `input.data.dataFilter` object of the `S1GRD` `process` API.
#### `mosaickingOrder`
Sets the order of overlapping tiles from which the output result is mosaicked.
| Value | Description |
| --------------- | -------------------------------------------------------------------------- |
| **mostRecent** | (default) The pixel will be selected from the most recently acquired tile. |
| **leastRecent** | Similar to **mostRecent** but in reverse order. |
#### `resolution` (pixel spacing)
| Value | Description |
| ---------- | ---------------------------------- |
| **HIGH** | 10m/px for IW/SM and 25m/px for EW |
| **MEDIUM** | 40m/px for IW/SM and EW |
#### `acquisitionMode`
Sentinel-1 operates in four different acquisition modes ([more](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-AcquisitionModesS1-Mission-Acquisition-Modes)).
| Value | Description | Polarization options |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **SM** | Stripmap mode ([more](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-StripmapS1-Mission-Stripmap)). | HH+HV, VV+VH, HH, VV |
| **IW** | Interferometric Wide (IW) swath mode ([more](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-InterferometricWideSwathS1-Mission-Interferometric-Wide-Swath)). | HH+HV, VV+VH, HH, VV |
| **EW** | Extra Wide (EW) swath mode ([more](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-ExtraWideSwathS1-Mission-Extra-Wide-Swath)). | HH+HV, VV+VH, HH, VV |
| **WV** | Wave mode ([more](https://sentiwiki.copernicus.eu/web/s1-mission#S1Mission-WaveS1-Mission-Wave)). | HH, VV |
#### `polarization`
This table contains information about the polarization two letter code used by ESA and the product's contained polarizations.
| Value | Description | Notes |
| ------ | --------------------- | -------------------------------------------------------- |
| **SH** | HH | |
| **SV** | VV | |
| **DH** | HH+HV | Typical for EW acquisitions |
| **DV** | VV+VH | Typical for IW acquisitions |
| **HH** | Partial Dual, HH only | HH+HV was acquired, only HH is available in this product |
| **HV** | Partial Dual, HV only | HH+HV was acquired, only HV is available in this product |
| **VV** | Partial Dual, VV only | VV+VH was acquired, only VV is available in this product |
| **VH** | Partial Dual, VH only | VV+VH was acquired, only VH is available in this product |
#### `orbitDirection`
| Value | Description |
| -------------- | -------------------------------------------------------------------------------------- |
| **ASCENDING** | Data acquired when the satellite was traveling approx. towards the Earth's North pole. |
| **DESCENDING** | Data acquired when the satellite was traveling approx. towards the Earth's South pole. |
#### `timeliness`
| Value |
| ------------ |
| NRT10m |
| NRT1h |
| NRT3h |
| Fast24h |
| Offline |
| Reprocessing |
| ArchNormal |
### Processing Options
This chapter will explain the `input.data.processing` object of the `S1GRD` `process` API.
| Parameter | Description | Values | Default |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| upsampling | Interpolation method used for resampling Sentinel-1 GRD data when the requested resolution differs from the source resolution. The same method is applied for both upsampling and downsampling. | **NEAREST** - [nearest neighbour interpolation](https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
**BILINEAR** - [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
**BICUBIC** - [bicubic interpolation](https://en.wikipedia.org/wiki/Bicubic_interpolation) | **NEAREST** |
| backCoeff \[1] | Backscatter coefficient | **BETA0**
**SIGMA0\_ELLIPSOID**
**GAMMA0\_ELLIPSOID**
**GAMMA0\_TERRAIN** | **GAMMA0\_ELLIPSOID** |
| orthorectify \[2] | Enables/disables orthorectification | **TRUE** - Orthorectified
**FALSE** - non-Orthorectified
| **FALSE** |
| demInstance | The DEM used for orthorectification | **MAPZEN** - Mapzen DEM
**COPERNICUS** - Copernicus DEM 10m and 30m \[3]\[4]
**COPERNICUS\_30** - Copernicus DEM 30m \[4]
**COPERNICUS\_90** - Copernicus DEM 90m | Deployment-dependent |
| radiometricTerrainOversampling | Sets the DEM oversampling parameter for radiometric terrain correction. Integer values recommended. | 1 to 4 | 2 |
| speckleFilter | Defines the speckle filtering method and parameters to use. | See [Speckle Filtering](#speckle-filtering) | NONE |
note
* For Sentinel-1 GRD, the `downsampling` interpolation is not configurable and always uses the same method as specified for `upsampling`.
* The default DEM depends on the deployment:
* **EU-Central-1 (Frankfurt):** `COPERNICUS_30`
* **US-West-2 (Oregon):** `MAPZEN`
\[1]: `gamma0_ellipsoid` and `sigma0_ellipsoid` use an ellipsoid earth model. Radiometric terrain correction can be enabled by setting the backscatter coefficient to `gamma0_terrain`; orthorectification must be enabled in this case.
\[2]: For orthorectification, we use the DEM instance specified in the demInstance field or the default DEM instance if this is not set. The Copernicus DEM is generally of higher quality and recommended in most cases. The non-orthorectified products use a simple earth model as provided in the products themselves. This may be sufficient for very flat target areas and is faster to process.
\[3]: It has 10m resolution inside [39 European states including islands](https://dataspace.copernicus.eu/explore-data/data-collections/copernicus-contributing-missions/collections-description/COP-DEM) and 30m elsewhere. The 30m DEM is used exclusively if the request resolution is lower (more zoomed out) than 120m/px.
\[4]: The Copernicus 30m DEM has global coverage if used for the processing of Sentinel-1 data.
#### Speckle Filtering
Speckle filtering is applied right after calibration and noise removal and done on source data. To enable speckle filtering, add the speckle filter object with the correct type and parameters to your processing options, as shown in [this example](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/examples.md#s1grd-non-orthorectified-lee-speckle-filtered-decibel-gamma0-hh-between--20-db-and-10-db-png).
Available filters:
1. The `NONE` filter, which as the name implies, does nothing, and is equivalent to not having the filter defined at all.
```
"speckleFilter": {
"type": "NONE"
}
```
2. The LEE speckle filter. Window sizes from 1 to 7 are supported in each dimension. Odd valued window sizes are recommended. Processing time rapidly increases as window size increases. Note also that the effect of the filter depends on the resolution/zoom level; it is most pronounced at native resolution and gets reduced as you zoom out. We therefore suggest you use it at or near native resolution and switch it off at low resolution to save processing time. The effect of the filter is negligible if greatly zoomed out. An example with a 5x5 window:
```
"speckleFilter": {
"type": "LEE",
"windowSizeX": 5,
"windowSizeY": 5
}
```
**Note:** As an alternative or in addition to this, you can also perform [multitemporal averaging](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/examples.md#s1grd-orthorectified-gamma0-two-month-temporal-averaged-decibel-vv-between--20-db-and-0-db-png) to reduce speckle.
### Available Bands and Data
Information in this chapter is useful when defining [`input` object](https://docs.planet.com/develop/evalscripts/functions.md#input-object-properties) in evalscript. Any string listed in the column **Name** can be an element of the `input.bands` array in your evalscript.
| Name | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| VV | Present when the product polarization type is one of SV, DV or VV. |
| VH | Present when the product polarization type is VH or DV. |
| HV | Present when the product polarization type is HV or DH. |
| HH | Present when the product polarization type is one of SH, DH or HH. |
| localIncidenceAngle | The local incidence angle for each output pixel. Only available if orthorectification is enabled. |
| scatteringArea | The normalized scattering area for each output pixel. Used for conversion of beta0 to terrain corrected gamma0. Only available if radiometric terrain correction is performed. |
| shadowMask | Flags output pixels which are in or near radar shadow. Is `true` if the nearest GRD source pixel is at most one GRD pixel away from a GRD pixel with a scatteringArea of less than 0.05. Only available if radiometric terrain correction is performed. |
| dataMask | The mask of data/nodata pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)). |
### Units
The data values for each band in your custom script are presented in the units as specified here. In case more than one unit is available for a given band, you may optionally set the value of `input.units` in your evalscript `setup` function to one of the values in the `Units Value` column. Doing so will present data in that unit. The `units` parameter combines the physical quantity and corresponding units of measurement values. As such, some names more closely resemble physical quantities, others resemble units of measurement.
The `Source Format` specifies how and with what precision the digital numbers (`DN`) from which the unit is derived are encoded. Bands requested in `DN` units contain exactly the pixel values of the source data. Note that resampling may produce interpolated values. `DN` is also used whenever a band is derived computationally (like dataMask); such bands can be identified by having `DN` units and `N/A` source format. `DN` values are typically not offered if they do not simply represent any physical quantity, in particular, when `DN` values require source-specific (i.e. non-global) conversion to physical quantities.
Values in non-`DN` units are computed from the source (`DN`) values with at least float32 precision. Note that the conversion might be nonlinear, therefore the full value range and quantization step size of such a band can be hard to predict. Band values in evalscripts always behave as floating point numbers, regardless of the actual precision.
The `Typical Range` indicates what values are common for a given band and unit, however outliers can be expected.
For Sentinel-1, data values are linear power in the chosen backscatter coefficient. To specify the backscatter coefficient, set `BETA0`, `SIGMA0_ELLIPSOID`, `GAMMA0_ELLIPSOID` (default) or `GAMMA0_TERRAIN` as the value of `input.data.processing.backCoeff` in your request. The default is `GAMMA0_ELLIPSOID`.
| Band | Physical Quantity (units) | Units Value | Source Format | Typical Range | Notes |
| -------------------------------- | ------------------------------------------------------------- | ------------- | ------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Polarization
VV, HH, VH, HV | Linear power in the chosen backscatter coefficient (unitless) | LINEAR\_POWER | UINT16 | 0 - 0.5 | Can reach very high values (such as 1000); for visualizing a large dynamic range consider converting to decibels: `decibel = 10 * log10 (linear)`. |
| localIncidenceAngle | Angle (degrees) | DN | N/A | 0 - 180 | Computed for each output pixel. Requires orthorectification. |
| scatteringArea | Normalized area (unitless) | DN | N/A | 0 - 2 | Can reach high values on foreslopes. Requires radiometric terrain correction. |
| shadowMask | N/A | DN | N/A | 0 - likely not radar shadow
1 - likely in/near radar shadow | Requires radiometric terrain correction. |
| dataMask | N/A | DN | N/A | 0 - no data
1 - data | |
### Scenes Object
[`scenes` object](https://docs.planet.com/develop/evalscripts/functions.md#scenes) stores metadata. An example of metadata available in `scenes` object for Sentinel-1 GRD when mosaicking is `ORBIT`:
| Property name | Value |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| dateFrom | `'2019-04-02T00:00:00Z'` |
| dateTo | `'2019-04-02T23:59:59Z'` |
| tiles\[i].sentinel1ProductId | `'S1A_IW_GRDH_1SDV_20190402T170539_20190402T170604_026614_02FC31_7D8E'` |
| tiles\[i].date | `'2019-04-02T17:05:39Z'` |
| tiles\[i].shId | `881338` |
| tiles\[i].dataPath | `'s3://sentinel-s1-l1c/GRD/2019/4/2/IW/DV/S1A_IW_GRDH_1SDV_20190402T170539_20190402T170604_026614_02FC31_7D8E'` |
Properties of a `scenes` object can differ depending on the selected mosaicking and in which evalscript function the object is accessed. [Working with metadata in evalscript](https://docs.planet.com/develop/evalscripts.md#working-with-metadata-in-evalscripts) user guide explains all details and provide examples.
### Mosaicking
`SIMPLE` and `ORBIT` [mosaicking](https://docs.planet.com/develop/evalscripts/functions.md#mosaicking) types are supported. `TILE` mosaicking is not supported for this collection.
## Collection specific constraints
* **Noise**: Thermal noise reduction is applied to all Sentinel-1 GRD products.
* **Decibel units**: For decibel outputs, a conversion is necessary within your evalscript, see an example [here](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/examples.md#s1grd-orthorectified-decibel-gamma0-vh-between--20-db-and-0-db-png). We offer pre-defined evalscripts, which return S1GRD values in decibel units, as products in the Configuration Utility for your convenience.
* **Orbit state vectors**: We currently use the orbit state vectors provided in the products themselves as we find these sufficient for GRD use.
## CARD4L Data
CARD4L or [CEOS Analysis Ready Data](https://ceos.org/ard/) for Land refers to Sentinel-1 satellite data that has been processed to a predefined set of requirements (specifically [Normalised Radar Backscatter](https://ceos.org/ard/files/PFS/NRB/v5.5/CARD4L-PFS_NRB_v5.5.pdf) requirements), making Sentinel-1 data analysis ready and thus reducing its complexity. It is especially useful for non-expert users, as it does most of the data preparation work in advance, including geometric and radiometric correction. CARD4L also takes care of obligatory and extensive metadata generation, detailing data provenance, processing parameters, etc.
We have created a [CARD4L request generation tool](https://apps.sentinel-hub.com/s1-card4l/), which makes it easy to process CARD4L [compliant](https://ceos.org/ard/files/Self%20Assessments/NRB/v5.5/WGCV_CARD4L_Assessment_for_Sinergise_Sentinel-1_NRB_v5.5.pdf) Sentinel-1 data. To use it, you will need an [enterprise account](https://www.planet.com/pricing/?tab=platform), which activates access to batch processing. Note that you can get the equivalent raster data with the correct settings in an API request yourself, however metadata can only be obtained using the tool.
**Articles and use cases**
* We are processing Sentinel-1 CARD4L data for the [Digital Earth Africa project](https://docs.digitalearthafrica.org/en/latest/index.html). Technical information about the data and how to access it may be found [here](https://docs.digitalearthafrica.org/en/latest/data_specs/Sentinel-1_specs.html).
* [An Operational Analysis Ready Radar Backscatter Dataset for the African Continent](https://www.mdpi.com/2072-4292/14/2/351), January 2022
* [Intercomparison of Sentinel-1 Datasets from Google Earth Engine and the Card4L Tool](https://www.researchgate.net/publication/355208945_Intercomparison_of_Sentinel-1_Datasets_from_Google_Earth_Engine_and_the_Sinergise_Sentinel_Hub_Card4L_Tool), July 2021
## Catalog API Capabilities
To access Sentinel-1 GRD product metadata you need to send search request to our [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md). The requested metadata will be returned as JSON formatted response to your request. This chapter will help with understanding Sentinel 1 GRD specific parameters for search request.
### Collection identifier: `sentinel-1-grd`
### Filter extension
* `sar:instrument_mode` ([possible values](#acquisitionmode))
* `sat:orbit_state` ([possible values](#orbitdirection))
* `s1:polarization` ([possible values](#polarization))
* `s1:resolution` ([possible values](#resolution-pixel-spacing))
* `s1:timeliness` ([possible values](#timeliness))
### Distinct extension
* `date`
* `sar:instrument_mode`
* `sat:orbit_state`
* `s1:polarization`
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/copernicus/sentinel-1-grd/examples/)
# Sentinel 1 GRD Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## S1GRD orthorectified linear gamma0 VV between 0 and 0.5 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD orthorectified linear gamma0 VV between 0 and 0.5 in approximate real-world 10 m resolution (IW) (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
268574.43,
4624494.84,
276045.41,
4631696.16
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
}
},
"data": [{
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
},
"resolution": "HIGH",
"acquisitionMode": "IW"
},
"processing": {
"orthorectify": "true",
"demInstance": "COPERNICUS_30"
},
"type": "sentinel-1-grd"
}]
},
"output": {
"resx": 10,
"resy": 10,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD orthorectified with Copernicus DEM 30 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true",
"demInstance": "COPERNICUS_30"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD orthorectified linear gamma0 VV, ascending orbit direction, GeoTIFF in EPSG:32648 (UTM zone 48N)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Accept: image/tiff' \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
699800, 1190220, 709800, 1200220
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32648"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2017-11-15T00:00:00Z",
"to": "2017-11-15T23:00:00Z"
},
"acquisitionMode": "IW",
"polarization": "DV",
"orbitDirection ": "ASCENDING"
},
"processing": {
"backCoeff": "GAMMA0_ELLIPSOID",
"orthorectify": "true"
}
}
]
},
"output": {
"width": 1000,
"height": 1000,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1,sampleType: SampleType.FLOAT32}
}
}
function evaluatePixel(samples) {
return [samples.VV]
}'
```
## S1GRD orthorectified decibel gamma0 VH between -20 dB and 0 dB (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VH"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [toDb(samples.VH)]
}
// visualizes decibels from -20 to 0
function toDb(linear) {
// the following commented out lines are simplified below
// var log = 10 * Math.log(linear) / Math.LN10
// var val = Math.max(0, (log + 20) / 20)
return Math.max(0, Math.log(linear) * 0.21714724095 + 1)
}'
```
## S1GRD orthorectified decibel gamma0 RGB composite of VV, VH, VV/VH/10 between -20 dB and 0 dB (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV", "VH"],
output: { id:"default", bands: 3}
}
}
function evaluatePixel(samples) {
var vvdB = toDb(samples.VV)
var vhdB = toDb(samples.VH)
return [vvdB, vhdB, vvdB / vhdB / 10]
}
// displays VV in decibels from -20 to 0
function toDb(linear) {
// the following commented out lines are simplified below
// var log = 10 * Math.log(linear) / Math.LN10
// var val = Math.max(0, (log + 20) / 20)
return Math.max(0, Math.log(linear) * 0.21714724095 + 1)
}'
```
## S1GRD non-orthorectified linear sigma0 VH between 0 and 0.5 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "false",
"backCoeff": "SIGMA0_ELLIPSOID"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VH"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VH]
}'
```
## S1GRD non-orthorectified Lee speckle filtered decibel gamma0 HH between -20 dB and +10 dB (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
18400000,-11330000,18500000,-11430000
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"acquisitionMode": "EW",
"timeRange": {
"from": "2020-09-29T00:00:00Z",
"to": "2020-09-29T23:59:59Z"
}
},
"processing": {
"orthorectify": "false",
"backCoeff": "GAMMA0_ELLIPSOID",
"speckleFilter": {
"type": "LEE",
"windowSizeX": 5,
"windowSizeY": 5
}
}
}
]
},
"output": {
"width": 1000,
"height": 1000,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["HH"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [toDb(samples.HH)]
}
// visualizes decibels from -20 to +10
function toDb(linear) {
var log = 10 * Math.log(linear) / Math.LN10
return Math.max(0, (log + 20) / 30)
}'
```
## S1GRD orthorectified gamma0 two month temporal averaged decibel VV between -20 dB and 0 dB (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1360000,5121900,1370000,5131900
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-01T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
},
"orbitDirection": "ASCENDING"
},
"processing": {
"orthorectify": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV", "dataMask"],
output: { id:"default", bands: 1},
mosaicking: Mosaicking.ORBIT
}
}
function evaluatePixel(samples) {
return [calculateAverage(samples)]
}
function calculateAverage(samples) {
var sum = 0
var nValid = 0
for (let sample of samples) {
if (sample.dataMask != 0) {
nValid++
sum += toDb(sample.VV)
}
}
return sum / nValid
}
// visualizes decibels from -20 to 0
function toDb(linear) {
// the following commented out lines are simplified below
// var log = 10 * Math.log(linear) / Math.LN10
// var val = Math.max(0, (log + 20) / 20)
return Math.max(0, Math.log(linear) * 0.21714724095 + 1)
}'
```
## S1GRD radiometrically terrain corrected linear gamma0 VV between 0 and 0.5 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1095431, 5714610, 1146158, 5754129
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true",
"backCoeff": "GAMMA0_TERRAIN"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD radiometrically terrain corrected using Copernicus DEM 30 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1095431, 5714610, 1146158, 5754129
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true",
"backCoeff": "GAMMA0_TERRAIN",
"demInstance": "COPERNICUS_30"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD radiometrically terrain corrected with custom DEM oversampling of 3 (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
1095431, 5714610, 1146158, 5754129
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true",
"backCoeff": "GAMMA0_TERRAIN",
"radiometricTerrainOversampling": 3
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV"],
output: { id:"default", bands: 1}
}
}
function evaluatePixel(samples) {
return [2 * samples.VV]
}'
```
## S1GRD radiometrically terrain corrected gamma0 VV and auxiliary data: local incidence angle, scattering area, and shadow mask
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
565556.94, 5048644.47, 600656.56, 5076658.33
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32632"
}
},
"data": [
{
"type": "sentinel-1-grd",
"dataFilter": {
"timeRange": {
"from": "2019-02-02T00:00:00Z",
"to": "2019-04-02T23:59:59Z"
}
},
"processing": {
"orthorectify": "true",
"backCoeff": "GAMMA0_TERRAIN"
}
}
]
},
"output": {
"width": 1024,
"height": 796,
"responses": [
{
"identifier": "s1_rtc_VV_area",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "s1_rtc_angle_mask",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["VV", "localIncidenceAngle", "scatteringArea", "shadowMask"],
output: [{ id:"s1_rtc_VV_area", bands: 2, sampleType: "FLOAT32"},
{ id:"s1_rtc_angle_mask", bands: 2, sampleType: "UINT8"}]
}
}
function evaluatePixel(samples) {
return {
s1_rtc_VV_area: [samples.VV, samples.scatteringArea],
s1_rtc_angle_mask: [samples.localIncidenceAngle, samples.shadowMask]
}
}'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/copernicus/sentinel-2/)
# Sentinel 2 L1C & L2A
Sentinel-2 is a European wide-swath, high-resolution (as defined by ESA) multispectral imaging mission. Its optical imagery supports applications such as land monitoring, emergency response, and security-related use cases. The multispectral instrument provides 13 spectral bands spanning the visible, near-infrared, and shortwave infrared regions.
Dedicated to supplying data for Copernicus services, Sentinel-2 carries a range of technologies such as multispectral imaging instruments for land, ocean, and atmospheric monitoring. It delivers high-resolution optical images for land monitoring, emergency response, and security services. For more information, see the [S2 Mission](https://sentiwiki.copernicus.eu/web/s2-mission) and the [Collection User Guide](https://sentiwiki.copernicus.eu/web/s2-applications).
## Basic Facts
| Property | Value |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sensor** | MultiSpectral Instrument (MSI), 13 bands: four visible bands, six near-infrared bands, and three short-wave infrared bands |
| **Spatial resolution** | 10 m, 20 m, and 60 m (band-dependent) |
| **Revisit time** | five days at the equator (two to three days at mid latitudes) |
| **Spatial coverage** | [Land and coastal areas between latitudes 56°S and 83°N](https://sentiwiki.copernicus.eu/web/s2-mission#S2Mission-GeographicalCoverageS2-Mission-Geographical-Coveragetrue) |
| **Common use cases** | Land-cover mapping, land-change detection, vegetation monitoring, burned-area analysis |
### Product Differences
| Property | Sentinel-2 L1C | Sentinel-2 L2A |
| --------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| **Measurement** | Top-of-atmosphere (TOA) reflectance | Bottom-of-atmosphere (BOA) reflectance, processed from L1C using Sen2Cor |
| **Data availability** | Available since November 2015 | Available since October 2016 (global availability since January 2017) |
**Note:** Sentinel-2A was maneuvered into a new orbit (located 36° away from Sentinel-2B) and resumed observations in 13 March 2025. With this campaign, the Sentinel-2 constellation consists of 3 satellites for 1 year (till 13 March 2026).[\[1\]](https://sentinels.copernicus.eu/web/sentinel/-/sentinel-2a-extended-campaign-starting-march-13-2025)
## Attribution and Use
EU law grants free access to Copernicus Sentinel Data and Service Information for the purpose of the following lawful uses: a) reproduction; b) distribution; c) communication to the public; d) adaptation, modification, and combination with other data and information; e) any combination of points a to d.
See more details on the [use of Copernicus Sentinel data and service information.](https://sentinels.copernicus.eu/documents/247904/690755/Sentinel_Data_Legal_Notice)
Tracing based on Sentinel imagery is allowed for commercial purposes as well.
**Acknowledgment**: Contains modified Copernicus Sentinel data \[Year] processed by Planet.
## Accessing Sentinel-2 Data
To access data, you need to send a POST request to the Processing API. The requested data will be returned as the response to your request. Each POST request can be tailored to get exactly the data you require by setting various parameters depending on the data source.
### Endpoint Locations
| Data | Service | Notes |
| -------------- | -------------------------- | --------------------------------------------------------- |
| Sentinel-2 L1C | services.sentinel-hub.com/ | Global since November 2015 |
| Sentinel-2 L2A | services.sentinel-hub.com/ | Europe since November 2016
Global since January 2017 |
**Data type identifiers:**
* `sentinel-2-l1c`
* `sentinel-2-l2a`
Use these as the value of the `input.data.type` parameter in your API requests. This ensures you get the correct Sentinel-2 data level.
### Filtering Options
This chapter explains the `input.data.dataFilter` object for Sentinel-2 data.
#### `mosaickingOrder`
Sets the order of overlapping tiles from which the output result is mosaicked. Tiles typically come from the same orbit/acquisition.
| Value | Description | Notes |
| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **mostRecent** | (default) Pixel selected from the most recently acquired tile | In case multiple tiles share the same timestamp, the one downloaded or created latest will be used. |
| **leastRecent** | Same as above, but in reverse order | |
| **leastCC** | Pixel selected from tile with least cloud coverage | Tile-level metadata (each covering about 12,000 sq. km), approximate values |
#### `maxCloudCoverage`
Sets the upper limit for cloud coverage (%) based on precomputed estimates in the tile metadata. For example, setting `20` retrieves only tiles with at most 20% cloud coverage.
note
The filter is per-tile and might not perfectly reflect the area of interest.
### Rendering Limits
#### Sentinel-2 L1C
Rendering is available up to 200 m/px.
#### Sentinel-2 L2A
Rendering is available up to 1500 m/px.
### Antimeridian handling
[Browser](https://insights.planet.com/analyze/browser/) does not magically handle all aspects of data which crosses the antimeridian. Longitudes beyond +180 degrees are NOT treated as longitudes beyond -180 degrees. Sentinel-2 tiles do cross the antimeridian and L1C and L2A tiles are distributed in the UTM projection. Requesting data in the native UTM coordinates will work exactly as expected. However, for mosaicking, UTM zone 1 and UTM zone 60 are not seen as intersecting even though they do intersect in reality. UTM tiles reprojected to some other coordinate system may fall outside the bounds of this coordinate system. This happens with WGS84, for example, where you may get data at -181 longitude. It is also possible to not get data at +179 longitude due to the slight asymmetry of the Sentinel-2 tile grid. In these situations some additional care must be taken when creating requests.
### Processing Options
This chapter explains the `input.data.processing` object for Sentinel-2 data.
| Parameter | Description | Values | Default |
| ------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| upsampling | Interpolation when requested resolution `>` source resolution | **NEAREST** - [nearest neighbour interpolation](https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
**BILINEAR** - [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
**BICUBIC** - [bicubic interpolation](https://en.wikipedia.org/wiki/Bicubic_interpolation) | **NEAREST** |
| downsampling | Interpolation when requested resolution `<` source resolution | **NEAREST** - [nearest neighbour interpolation](https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
**BILINEAR** - [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
**BICUBIC** - [bicubic interpolation](https://en.wikipedia.org/wiki/Bicubic_interpolation) | **NEAREST** |
For visualization, see [upsampling comparison examples.](https://en.wikipedia.org/wiki/Comparison_gallery_of_image_scaling_algorithms)
### Available Bands and Data
This chapter will explain the bands and data which can be set in the [evalscript input object](https://docs.planet.com/develop/evalscripts/functions.md#input-object-properties). Any string listed in the column **Name** can be an element of the `input.bands` array in your evalscript.
| Name | Description | Resolution | Notes |
| ---------------- | ---------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------- |
| B01 | Coastal aerosol | 60 m | |
| B02 | Blue | 10 m | |
| B03 | Green | 10 m | |
| B04 | Red | 10 m | |
| B05 | Vegetation red edge | 20 m | |
| B06 | Vegetation red edge | 20 m | |
| B07 | Vegetation red edge | 20 m | |
| B08 | NIR | 10 m | |
| B8A | Narrow NIR | 20 m | |
| B09 | Water vapour | 60 m | |
| B10 | SWIR – Cirrus | 60 m | (excluded for L2A BOA data) |
| B11 | SWIR | 20 m | |
| B12 | SWIR | 20 m | |
| CLP | Cloud probability (S2Cloudless) ([more](#cloud-masks)) | 160 m | S2Cloudless band is 160 m; can be requested for products at any output resolution |
| CLM | Cloud mask (S2Cloudless) ([more](#cloud-masks)) | 160 m | |
| AOT (L2A) | Aerosol Optical Thickness map (Sen2Cor) | 10 m | Only L2A |
| SCL (L2A) | Scene classification (Sen2Cor) | 20 m | Only L2A |
| SNW (L2A) | Snow probability (Sen2Cor) | 20 m | Only L2A |
| CLD (L2A) | Cloud probability (Sen2Cor) | 20 m | Only L2A |
| sunAzimuthAngles | Sun azimuth angle | 5000 m | |
| sunZenithAngles | Sun zenith angle | 5000 m | |
| viewAzimuthMean | Viewing azimuth angle | 5000 m | |
| viewZenithMean | Viewing zenith angle | 5000 m | |
| dataMask | Mask of data/no data pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)) | N/A | Calculated per pixel |
### Cloud Masks
Cloud masks and probabilities are computed using the 10-band version of [s2cloudless](https://github.com/sentinel-hub/sentinel2-cloud-detector), an in-house developed cloud detection algorithm. These bands are available at a fixed resolution of 160 m per pixel and are provided as convenience bands to improve analysis capabilities. See [Additional Resources](#additional-resources) for more information on cloud masks.
The bands are named `CLP` (cloud probabilities) and `CLM` (cloud masks) with the following return values:
* `CLM`: 0 (no clouds), 1 (clouds), 255 (no data)
* `CLP`: 0–255 (divide by 255 to get the \[0–1] range)
The `CLM` no data value of 255 is also returned if a tile has missing `CLM` and `CLP` bands (for example, due to errors). This ensures that values of 0 and 1 can be used with confidence for each pixel. In such cases, `CLP` returns 0. Consider using `CLM` alongside `CLP` in your evalscript if this is a concern.
#### Alignment with `s2cloudless`
`CLP` is generated per tile using the `s2cloudless` product at 160 m resolution. Due to the 60 m Sentinel-2 bands, a perfect match between `CLP` and `s2cloudless` is not possible for all requests.
### Units
The data values for each band in your evalscript are provided in the units specified below. You can set the desired unit via `input.units` in your evalscript setup function.
The available units and their meanings depend on the selected dataset and band. Refer to the dataset-specific sections below for details on value scaling and interpretation.
| Band | Physical Quantity | Units Value | Source Format | Typical Range |
| ---------------- | ---------------------------------- | --------------------- | ------------- | ---------------------------------------- |
| Optical bands | Reflectance (unitless) | REFLECTANCE (default) | UINT15 | 0 – 0.4 \* |
| Optical bands | Digital numbers | DN | UINT15 | 0 – 4000 \* |
| CLP | Cloud probability (unitless) × 255 | DN | UINT8 | 0 – 255 |
| CLM | Cloud mask | DN | UINT8 | 0 (no clouds), 1 (clouds), 255 (no data) |
| L2A only: AOT | Aerosol optical thickness | OPTICAL\_DEPTH | UINT16 | 0 – 0.6 (AOT = DN / 1000) |
| L2A only: SCL | Scene classification mask | DN | UINT8 | 0 – No data; 1–11 classification codes |
| L2A only: SNW | Snow probability | PERCENT | UINT8 | 0 – 100 |
| L2A only: CLD | Cloud probability | PERCENT | UINT8 | 0 – 100 |
| sunAzimuthAngles | Angle (degrees) | DEGREES | FLOAT32 | 30 – 200 |
| sunZenithAngles | Angle (degrees) | DEGREES | FLOAT32 | 15 – 80 |
| viewAzimuthMean | Angle (degrees) | DEGREES | FLOAT32 | 90 – 300 |
| viewZenithMean | Angle (degrees) | DEGREES | FLOAT32 | 0 – 12 |
| dataMask | N/A | DN | N/A | 0 (no data), 1 (data) |
\**Higher values expected in IR bands; reflectance may exceed 1.*
#### Harmonize Values
ESA updated the Sentinel-2 processing baseline starting with [version 04.00](https://sentiwiki.copernicus.eu/web/s2-processing) in January 2022, introducing changes to digital number (DN) interpretation that apply to this and all subsequent baselines.
For harmonized Sentinel-2 optical data, digital numbers (DN) are related to reflectance as:
* `DN = 10000 × reflectance`
`harmonizeValues` can be `true` (default) or `false`, and it's behavior depends on the [units](#units) chosen:
* `REFLECTANCE`:
* `harmonizeValues = true`: negative reflectance values are clamped to zero. In other words, pixels with negative reflectance return zero reflectance instead.
* `harmonizeValues = false`: negative reflectance values can be returned.
* `DN`:
* `harmonizeValues = true`: DN values are harmonized so they are comparable with data from previous baselines. Therefore it still holds that `DN = 10000 * REFLECTANCE`. In addition, negative values are clamped to zero.
* `harmonizeValues = false`: DN values are exactly as provided in the source files themselves. The "true" DN value, you could say. Don't forget that values have different definitions with different processing baselines, careful with mosaicking!
### Mosaicking
All [mosaicking](https://docs.planet.com/develop/evalscripts/functions.md#mosaicking) types are supported.
### Scenes Object
The [`scenes`](https://docs.planet.com/develop/evalscripts/functions.md#scenes) object stores metadata.
**Example (L1C ORBIT mosaicking):**
| Property name | Value |
| ---------------------------- | ---------------------------------------------------------------- |
| dateFrom | `'2020-09-15T00:00:00Z'` |
| dateTo | `'2020-09-15T00:00:00Z'` |
| tiles\[i].sentinel2ProductId | `'S2A_MSIL1C_20200915T101031_N0209_R022_T33TVM_20200915T122749'` |
| tiles\[i].date | `'2020-09-15T10:17:52Z'` |
| tiles\[i].shId | `11583048` |
| tiles\[i].cloudCoverage | `2.09` |
| tiles\[i].dataPath | `'s3://sentinel-s2-l1c/tiles/33/T/VM/2020/9/15/0'` |
### Collection Specific Constraints (Sentinel-2 L2A)
Atmospheric correction for Sentinel-2 L2A products is performed using ESA’s official [Sen2Cor](https://step.esa.int/main/third-party-plugins-2/sen2cor/) processor. This processing is carried out by ESA as part of the standard data production workflow.
## Catalog API Capabilities
To access Sentinel-2 product metadata, send a **search request** to the [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md). The requested metadata is returned as a JSON response.
| Dataset | Collection Identifier | Filter Extension | Distinct Extension |
| -------------- | --------------------- | ---------------- | ------------------ |
| Sentinel-2 L1C | sentinel-2-l1c | eo:cloud\_cover | date |
| Sentinel-2 L2A | sentinel-2-l2a | eo:cloud\_cover | date |
## Additional Resources
[Cloud Mask Intercomparison eXercise (CMIX)](https://www.sciencedirect.com/science/article/pii/S0034425722001043?via%3Dihub)
[An evaluation of cloud masking algorithms for Landsat 8 and Sentinel-2](https://www.sciencedirect.com/science/article/pii/S0034425722001043?via%3Dihub)
[Cloud Masks at Your Service](https://medium.com/sentinel-hub/cloud-masks-at-your-service-6e5b2cb2ce8a)
[Introduction to cloud masks and their applications](https://medium.com/sentinel-hub/cloud-masks-at-your-service-6e5b2cb2ce8a)
[On cloud detection with multi-temporal data](https://medium.com/sentinel-hub/on-cloud-detection-with-multi-temporal-data-f64f9b8d59e5)
[Advanced techniques for cloud detection using time series](https://medium.com/sentinel-hub/on-cloud-detection-with-multi-temporal-data-f64f9b8d59e5)
[Cloud Detector - s2cloudless](https://medium.com/sentinel-hub/sentinel-hub-cloud-detector-s2cloudless-a67d263d3025)
[Technical details of the s2cloudless algorithm](https://medium.com/sentinel-hub/sentinel-hub-cloud-detector-s2cloudless-a67d263d3025)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/copernicus/sentinel-2/examples/)
# Sentinel 2 L1C & L2A Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## True Color
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
## True Color (EPSG 32633)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
## True Color, resolution (EPSG 32633)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"resx": 100,
"resy": 100
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"resx": 100,
"resy": 100
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
## True Color, multi-band GeoTIff
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: image/tiff' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: image/tiff' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}'
```
## True Color, cloudy pixels masked out
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: ["B02", "B03", "B04", "SCL"],
output: {bands: 3}
}
}
function evaluatePixel(sample) {
if ([8, 9, 10].includes(sample.SCL) ){
return [1, 0, 0]
} else{
return [ 2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02 ]
}
}'
```
## True Color, mosaicking with leastRecent
* L1C
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2018-10-11T00:00:00Z",
"to": "2018-11-18T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: ["B02", "B03", "B04"],
output: {bands: 3}
}
}
function evaluatePixel(sample) {
return [ 2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02 ]
}'
```
## True color and metadata (multi-part response GeoTIFF and json)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2018-12-27T00:00:00Z",
"to": "2018-12-27T23:59:59Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
mosaicking: Mosaicking.ORBIT,
output: { id:"default", bands: 3}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = { "scenes": scenes.orbits }
}
function evaluatePixel(samples) {
return [ 2.5 * samples[0].B04, 2.5 * samples[0].B03, 2.5 * samples[0].B02 ]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 200,
"height": 100,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/png"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
mosaicking: Mosaicking.ORBIT,
output: { id:"default", bands: 3}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = { "scenes": scenes.orbits }
}
function evaluatePixel(samples) {
return [ 2.5 * samples[1].B04, 2.5 * samples[1].B03, 2.5 * samples[1].B02 ]
}'
```
## True color multi-part-reponse (different formats and SampleType)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.206251,
41.627351,
12.594042,
41.856879
]
},
"data": [{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2018-06-01T00:00:00Z",
"to": "2018-08-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg"
}
}, {
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
}, {
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
}, {
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B03", "B02"],
units: "REFLECTANCE" // default units
}
],
output: [{
id: "default",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
}, {
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8" //floating point values are automatically rounded to the nearest integer by the service.
}, {
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
}, {
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
default: [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02],
// Multiply input reflectance values by 2.5 to increase brighness and by 255 to return the band values clamped to [0, 255] unsigned 8 bit range.
true_color_8bit: [2.5 * sample.B04 * 255, 2.5 * sample.B03 * 255, 2.5 * sample.B02 * 255],
// Multiply input reflectance values by 2.5 to increase brightness and by 65535 to return the band values clamped to [0, 65535] unsigned 16 bit range.
true_color_16bit: [2.5 * sample.B04 * 65535, 2.5 * sample.B03 * 65535, 2.5 * sample.B02 * 65535],
// Returns band reflectance.
true_color_32float: [sample.B04, sample.B03, sample.B02]
}
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.206251,
41.627351,
12.594042,
41.856879
]
},
"data": [{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg"
}
}, {
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
}, {
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
}, {
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B03", "B02"],
units: "REFLECTANCE" // default units
}
],
output: [{
id: "default",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
}, {
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8" //floating point values are automatically rounded to the nearest integer by the service.
}, {
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
}, {
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
default: [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02],
// Multiply input reflectance values by 2.5 to increase brighness and by 255 to return the band values clamped to [0, 255] unsigned 8 bit range.
true_color_8bit: [2.5 * sample.B04 * 255, 2.5 * sample.B03 * 255, 2.5 * sample.B02 * 255],
// Multiply input reflectance values by 2.5 to increase brightness and by 65535 to return the band values clamped to [0, 65535] unsigned 16 bit range.
true_color_16bit: [2.5 * sample.B04 * 65535, 2.5 * sample.B03 * 65535, 2.5 * sample.B02 * 65535],
// Returns band reflectance.
true_color_32float: [sample.B04, sample.B03, sample.B02]
}
}'
```
## NDVI as jpeg image with bounds given as polygon
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B04", "B08"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B04", "B08"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
## Exact NDVI values using a floating point GeoTIFF
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B08"],
units: "REFLECTANCE"
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
return [ ndvi ]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B08"],
units: "REFLECTANCE"
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
return [ ndvi ]
}'
```
## NDVI values as INT16 raster
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B08"],
units: "REFLECTANCE"
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.INT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
// Return NDVI multiplied by 10000 as integers to save processing units. To obtain NDVI values, simply divide the resulting pixel values by 10000.
return [ndvi * 10000]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "true"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B08"],
units: "REFLECTANCE"
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.INT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
// Return NDVI multiplied by 10000 as integers to save processing units. To obtain NDVI values, simply divide the resulting pixel values by 10000.
return [ndvi * 10000]
}'
```
## NDVI image and value (multi-part response png and GeoTIFF)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry":{
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962866
],
[
-94.06738758087158,
41.805901566741305
],
[
-94.06734466552734,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347966
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup( ){
return{
input: [{
bands:["B04", "B08"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
if (ndvi<-0.5) image = [0.05,0.05,0.05]
else if (ndvi<-0.2) image = [0.75,0.75,0.75]
else if (ndvi<-0.1) image = [0.86,0.86,0.86]
else if (ndvi<0) image = [0.92,0.92,0.92]
else if (ndvi<0.025) image = [1,0.98,0.8]
else if (ndvi<0.05) image = [0.93,0.91,0.71]
else if (ndvi<0.075) image = [0.87,0.85,0.61]
else if (ndvi<0.1) image = [0.8,0.78,0.51]
else if (ndvi<0.125) image = [0.74,0.72,0.42]
else if (ndvi<0.15) image = [0.69,0.76,0.38]
else if (ndvi<0.175) image = [0.64,0.8,0.35]
else if (ndvi<0.2) image = [0.57,0.75,0.32]
else if (ndvi<0.25) image = [0.5,0.7,0.28]
else if (ndvi<0.3) image = [0.44,0.64,0.25]
else if (ndvi<0.35) image = [0.38,0.59,0.21]
else if (ndvi<0.4) image = [0.31,0.54,0.18]
else if (ndvi<0.45) image = [0.25,0.49,0.14]
else if (ndvi<0.5) image = [0.19,0.43,0.11]
else if (ndvi<0.55) image = [0.13,0.38,0.07]
else if (ndvi<0.6) image = [0.06,0.33,0.04]
else image = [0,0.27,0]
return {
default: [ ndvi ],
ndvi_image: image
}
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry":{
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962866
],
[
-94.06738758087158,
41.805901566741305
],
[
-94.06734466552734,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347966
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup( ){
return{
input: [{
bands:["B04", "B08"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B08 - sample.B04) / (sample.B08 + sample.B04)
if (ndvi<-0.5) image = [0.05,0.05,0.05]
else if (ndvi<-0.2) image = [0.75,0.75,0.75]
else if (ndvi<-0.1) image = [0.86,0.86,0.86]
else if (ndvi<0) image = [0.92,0.92,0.92]
else if (ndvi<0.025) image = [1,0.98,0.8]
else if (ndvi<0.05) image = [0.93,0.91,0.71]
else if (ndvi<0.075) image = [0.87,0.85,0.61]
else if (ndvi<0.1) image = [0.8,0.78,0.51]
else if (ndvi<0.125) image = [0.74,0.72,0.42]
else if (ndvi<0.15) image = [0.69,0.76,0.38]
else if (ndvi<0.175) image = [0.64,0.8,0.35]
else if (ndvi<0.2) image = [0.57,0.75,0.32]
else if (ndvi<0.25) image = [0.5,0.7,0.28]
else if (ndvi<0.3) image = [0.44,0.64,0.25]
else if (ndvi<0.35) image = [0.38,0.59,0.21]
else if (ndvi<0.4) image = [0.31,0.54,0.18]
else if (ndvi<0.45) image = [0.25,0.49,0.14]
else if (ndvi<0.5) image = [0.19,0.43,0.11]
else if (ndvi<0.55) image = [0.13,0.38,0.07]
else if (ndvi<0.6) image = [0.06,0.33,0.04]
else image = [0,0.27,0]
return {
default: [ ndvi ],
ndvi_image: image
}
}'
```
## All Sentinel 2 L1C & L2A raw bands, original data (no harmonization)
Learn about harmonization [here](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#harmonize-values).
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l1c",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "false"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08", "B8A", "B09", "B10", "B11", "B12"],
units: "DN"
}],
output: {
id: "default",
bands: 13,
sampleType: SampleType.UINT16
}
}
}
function evaluatePixel(sample) {
return [ sample.B01, sample.B02, sample.B03, sample.B04, sample.B05, sample.B06, sample.B07, sample.B08, sample.B8A, sample.B09, sample.B10, sample.B11, sample.B12]
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-94.04798984527588,
41.7930725281021
],
[
-94.04803276062012,
41.805773608962869
],
[
-94.06738758087158,
41.805901566741308
],
[
-94.06734466552735,
41.7967199475024
],
[
-94.06223773956299,
41.79144072064381
],
[
-94.0504789352417,
41.791376727347969
],
[
-94.05039310455322,
41.7930725281021
],
[
-94.04798984527588,
41.7930725281021
]
]
]
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
},
"processing": {
"harmonizeValues": "false"
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08", "B8A", "B09", "B11", "B12"],
units: "DN"
}],
output: {
id: "default",
bands: 12,
sampleType: SampleType.UINT16
}
}
}
function evaluatePixel(sample) {
return [ sample.B01, sample.B02, sample.B03, sample.B04, sample.B05, sample.B06, sample.B07, sample.B08, sample.B8A, sample.B09, sample.B11, sample.B12]
}'
```
## Other Sentinel 2 L2A specific data (Aerosol Optical Thickness, Scene Classification, Snow and Cloud probabilities, Sun and View angles)
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"timeRange": {
"from": "2022-10-01T00:00:00Z",
"to": "2022-10-31T00:00:00Z"
}
}
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "TrueColor",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "AOT",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "SCL",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "SNW",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "CLD",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "SAA",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "SZA",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "VAM",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "VZM",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{bands:["B02", "B03", "B04", "AOT", "SCL", "SNW", "CLD", "sunAzimuthAngles", "sunZenithAngles", "viewAzimuthMean", "viewZenithMean"]}],
output: [
{id: "TrueColor", bands: 3, sampleType: SampleType.FLOAT32},
{id: "AOT", bands: 1, sampleType: SampleType.UINT16},
{id: "SCL", bands: 1, sampleType: SampleType.UINT8},
{id: "SNW", bands: 1, sampleType: SampleType.UINT8},
{id: "CLD", bands: 1, sampleType: SampleType.UINT8},
{id: "SAA", bands: 1, sampleType: SampleType.FLOAT32},
{id: "SZA", bands: 1, sampleType: SampleType.FLOAT32},
{id: "VAM", bands: 1, sampleType: SampleType.FLOAT32},
{id: "VZM", bands: 1, sampleType: SampleType.FLOAT32}
]
}
}
function evaluatePixel(sample) {
var truecolor = [sample.B04, sample.B03, sample.B02]
var aot = [sample.AOT]
var scl = [sample.SCL]
var snw = [sample.SNW]
var cld = [sample.CLD]
var saa = [sample.sunAzimuthAngles]
var sza = [sample.sunZenithAngles]
var vam = [sample.viewAzimuthMean]
var vzm = [sample.viewZenithMean]
return {
TrueColor: truecolor,
AOT: aot,
SCL: scl,
SNW: snw,
CLD: cld,
SAA: saa,
SZA: sza,
VAM: vam,
VZM: vzm
}
}'
```
## All acquisitions in specified time range for subset of bands returned as multiband GeoTIFFs (multi-part response GeoTIFF and json)
* L1C
* L2A
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Content-Type: multipart/form-data' \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.44693,
41.870072,
12.541001,
41.917096
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2022-07-01T00:00:00Z",
"to": "2022-07-19T23:59:59Z"
}
},
"type": "sentinel-2-l1c"
}
]
},
"output": {
"width": 512,
"height": 344,
"responses": [
{
"identifier": "blue",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "green",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "red",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B02", "B03", "B04"]
}],
output: [
{id: "blue", bands: 1 },
{id: "green", bands: 1 },
{id: "red", bands: 1 },
],
mosaicking: Mosaicking.ORBIT
}
}
function updateOutput(outputs, collection) {
Object.values(outputs).forEach((output) => {
output.bands = collection.scenes.length;
});
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
var dates_array = [];
for (let elem of scenes){
dates_array.push(elem.date.toISOString())
}
outputMetadata.userData = { "acquisition_dates": dates_array }
}
function evaluatePixel(samples) {
var n_observations = samples.length;
let band_02_array = new Array(n_observations).fill(NaN);
let band_03_array = new Array(n_observations).fill(NaN);
let band_04_array = new Array(n_observations).fill(NaN);
samples.forEach((sample, index) => {
band_02_array[index] = sample.B02;
band_03_array[index] = sample.B03;
band_04_array[index] = sample.B04;
});
return {
blue: band_02_array,
green: band_03_array,
red: band_04_array
};
}'
```
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Content-Type: multipart/form-data' \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.44693,
41.870072,
12.541001,
41.917096
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2022-07-01T00:00:00Z",
"to": "2022-07-19T23:59:59Z"
}
},
"type": "sentinel-2-l2a"
}
]
},
"output": {
"width": 512,
"height": 344,
"responses": [
{
"identifier": "blue",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "green",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "red",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B02", "B03", "B04"]
}],
output: [
{id: "blue", bands: 1 },
{id: "green", bands: 1 },
{id: "red", bands: 1 },
],
mosaicking: Mosaicking.ORBIT
}
}
function updateOutput(outputs, collection) {
Object.values(outputs).forEach((output) => {
output.bands = collection.scenes.length;
});
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
var dates_array = [];
for (let elem of scenes){
dates_array.push(elem.date.toISOString())
}
outputMetadata.userData = { "acquisition_dates": dates_array }
}
function evaluatePixel(samples) {
var n_observations = samples.length;
let band_02_array = new Array(n_observations).fill(NaN);
let band_03_array = new Array(n_observations).fill(NaN);
let band_04_array = new Array(n_observations).fill(NaN);
samples.forEach((sample, index) => {
band_02_array[index] = sample.B02;
band_03_array[index] = sample.B03;
band_04_array[index] = sample.B04;
});
return {
blue: band_02_array,
green: band_03_array,
red: band_04_array
};
}'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/)
# Other Datasets
[](https://docs.planet.com/data/public-data/other-datasets/dem.md)
### [Digital Elevation Model (DEM)](https://docs.planet.com/data/public-data/other-datasets/dem.md)
[](https://docs.planet.com/data/public-data/other-datasets/sentinel-s2-l2a-mosaic-120.md)
### [Sentinel-2 L2A 120m Mosaic](https://docs.planet.com/data/public-data/other-datasets/sentinel-s2-l2a-mosaic-120.md)
[](https://docs.planet.com/data/public-data/other-datasets/impact-observatory-lulc-map.md)
### [10m Annual Land Use Land Cover (9-class)](https://docs.planet.com/data/public-data/other-datasets/impact-observatory-lulc-map.md)
[](https://docs.planet.com/data/public-data/other-datasets/cnes-land-cover-map.md)
### [CNES Land Cover Map](https://docs.planet.com/data/public-data/other-datasets/cnes-land-cover-map.md)
[](https://docs.planet.com/data/public-data/other-datasets/esa-worldcover.md)
### [ESA WorldCover](https://docs.planet.com/data/public-data/other-datasets/esa-worldcover.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/cnes-land-cover-map/)
# CNES Land Cover Map
The CNES Land Cover Map (Occupation des Sols, OSO) produces land classification for Metropolitan France at a 10m spatial resolution. It is based on Sentinel-2 L2A data processed within the Theia Land Cover CES framework. The map is generated automatically using the iota² processing chain, which employs a Random Forest classifier calibrated with extensive national vector data (such as BD TOPO and Corine Land Cover).
## Data Availability & Collections
The OSO maps are available as annual composites. Since 2018, the product has used a 23-category nomenclature, which is backward-compatible with the 17-category version used in 2016 and 2017.
* **Collection ID**: `9baa2732-6597-49d2-ae3b-68ba0a5386b2`
* **Update Frequency**: Annually.
## Basic Facts
| Property | Value |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Sensor** | MultiSpectral Instrument (MSI) from Sentinel-2 |
| **Spatial Resolution** | 10 m |
| **Geographic Coverage** | Metropolitan France |
| **Coordinate System** | Lambert-93 (EPSG:2154) or UTM |
| **Data Format** | Cloud Optimized GeoTIFF (COG) |
| **Temporal Coverage** | 2016 – 2022 (Updated annually) |
| **License** | [ETALAB V2.0 Open License](https://theia.cnes.fr/atdistrib/documents/Licence-Theia-CNES-Sentinel-ETALAB-v2.0-en.pdf) |
| **Provider** | **Planet** |
## Band Information
The CNES Land Cover product contains three specific bands:
| Name | Description |
| ------------------- | --------------------------------------------------------------------------- |
| **OCS** | Main discrete classification according to the 23-category nomenclature. |
| **OCS\_Confidence** | Classifier confidence level (values 1 to 100). |
| **OCS\_Validity** | Indicates the number of cloudless images used for the pixel classification. |
## Class Definitions (23-Category Nomenclature)
The following table describes the classification values found in the OCS band for maps from 2018 onwards.
| Value | Label | Color |
| ------ | ---------------------------------------- | --------- |
| **1** | Dense built-up area | `#ff00ff` |
| **2** | Diffuse built-up area | `#ff55ff` |
| **3** | Industrial and commercial areas | `#ffaaff` |
| **4** | Roads | `#00ffff` |
| **5** | Oilseeds (Rapeseed) | `#ffff00` |
| **6** | Straw cereals (Wheat, Triticale, Barley) | `#d0ff00` |
| **7** | Protein crops (Beans / Peas) | `#a1d600` |
| **8** | Soy | `#ffab44` |
| **9** | Sunflower | `#d6d600` |
| **10** | Corn | `#ff5500` |
| **11** | Rice | `#c5ffff` |
| **12** | Tubers/roots | `#aaaa61` |
| **13** | Grasslands | `#aaaa00` |
| **14** | Orchards and fruit growing | `#aaaaff` |
| **15** | Vineyards | `#550000` |
| **16** | Hardwood forest | `#009c00` |
| **17** | Softwood forest | `#003200` |
| **18** | Natural grasslands and pastures | `#aaff00` |
| **19** | Woody moorlands | `#55aa7f` |
| **20** | Natural mineral surfaces | `#ff0000` |
| **21** | Beaches and dunes | `#ffb802` |
| **22** | Glaciers and eternal snows | `#bebebe` |
| **23** | Water | `#0000ff` |
## Accessing the Data
### Planet Insights Platform API
To access this collection programmatically, use the following details in your API requests:
* **Endpoint**: `services.sentinel-hub.com`
* **Collection Type**: `byoc-9baa2732-6597-49d2-ae3b-68ba0a5386b2`
### Visualization Script (Evalscript)
Use this script to visualize the land cover classification with the official CNES color scheme:
```
// VERSION=3
// CNES Land Cover (OSO) Visualizer
const colormap = [
[1, 0xff00ff], [2, 0xff55ff], [3, 0ffaaff], [4, 0x00ffff],
[5, 0xffff00], [6, 0xd0ff00], [7, 0xa1d600], [8, 0xffab44],
[9, 0xd6d600], [10, 0xff5500], [11, 0xc5ffff], [12, 0 aaaa61],
[13, 0 aaaa00], [14, 0 aaaaff], [15, 0x550000], [16, 0x009c00],
[17, 0x003200], [18, 0 aaff00], [19, 0x55aa7f], [20, 0xff0000],
[21, 0xffb802], [22, 0xbebebe], [23, 0x0000ff]
];
const visualizer = new ColorMapVisualizer(colormap);
function setup() {
return {
input: ["OCS", "dataMask"],
output: { bands: 3 }
};
}
function evaluatePixel(samples) {
return visualizer.process(samples.OCS);
}
```
## Attribution
Value-added data processed by CNES for the [Theia](https://www.theia-land.fr/en/homepage-en/#) data center from Copernicus data. Processing uses algorithms developed by Theia's Centers of Scientific Expertise.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/dem/)
# Digital Elevation Model (DEM)
A **DEM** is a digital model or 3D\* representation of a terrain's surface. With a DEM you are able to obtain and analyze heights within your area of interest, and integrate the data in 3D applications. The data can also be used for the **orthorectification** of satellite imagery (for example, Sentinel 1). Browser supports **Mapzen's DEM**, available through [Amazon Web Services (AWS)](https://registry.opendata.aws/terrain-tiles/) through EU-Central-1 and US-West-2 regions, and **Copernicus DEM**, available through AWS EU-Central-1 region.
**Mapzen DEM** is based on SRTM30 (Shuttle Radar Topography Mission) and [other sources](https://github.com/tilezen/joerd/blob/master/docs/data-sources.md). Bathymetry data is taken from [ETOPO1](https://www.ngdc.noaa.gov/mgg/global/global.html). It is a static collection and does not depend on the date. More information: [Mapzen's documentation](https://github.com/tilezen/joerd/tree/master/docs).
**Copernicus DEM** is based on WorldDEM that is infilled on a local basis with the following DEMs: ASTER, SRTM90, SRTM30, SRTM30plus, GMTED2010, TerraSAR-X Radargrammetric DEM, ALOS World 3D-30m. We provide two instances named COPERNICUS\_30 and COPERNICUS\_90, with worldwide coverage. COPERNICUS\_90 uses COP-DEM GLO-90, which has 90 meters resolution. COPERNICUS\_30 uses COP-DEM GLO-30 Public, which has 30 meters resolution, where it's available, and for the rest is uses GLO-90. Tiles that are missing from GLO-30 Public are not yet released to the public by Copernicus Programme. Both instances are static and do not depend on the date. We return a homogeneous DEM with zeros in regions where there are no source tiles (for example, in ocean areas). More information [here](https://dataspace.copernicus.eu/explore-data/data-collections/copernicus-contributing-missions/collections-description/COP-DEM).
info
Actually, we should say "2.5D" to be more precise. The terrain surface embedded in 3D space is modeled in a way that precisely one height is assigned to each pixel. This brings limitations as not all 3D shapes (for example, overhangs, vertical walls, caves) can be fully modeled.
## Attribution and use
For Mapzen DEM, see terms [here](https://www.mapzen.com/terms/).
For Copernicus DEM GLO-90, check the [licensing terms](https://dataspace.copernicus.eu/explore-data/data-collections/copernicus-contributing-missions/collections-description/COP-DEM). The applicable licence is "COP-DEM-GLO-90-F Global 90m Full, Free & Open. Licence for the use of the Copernicus WorldDEM™-90".
For Copernicus DEM GLO-30 Public, check the license and terms [here](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/Data/DEM.html).
## Accessing DEM Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the collection you are querying. This chapter will help you understand the parameters for DEM data. To see examples of such requests go [here](https://docs.planet.com/data/public-data/other-datasets/dem/examples.md), and for an overview of all API parameters see the [API Reference](https://docs.planet.com/develop/apis/processing/reference.md).
### Endpoint Locations
Default DEMs (the data you receive should no [demInstance](#deminstance) parameter be set) may differ across deployments as not all data is available everywhere. Note that defaults may change (with prior notice) should a higher quality DEM become available. Consider setting the DEM instance explicitly if this could be an issue.
| Service | DEM instances available | Default DEM | Notes |
| ------------------------------------- | -------------------------------------- | -------------- | ------------------------------------------------------------------------ |
| services.sentinel-hub.com/api | MAPZEN, COPERNICUS\_30, COPERNICUS\_90 | COPERNICUS\_30 | Mapzen DEM is available up to resolution level 13 (level 14 is missing). |
| services-uswest2.sentinel-hub.com/api | MAPZEN | MAPZEN | Mapzen DEM is available at full resolution (level 14 included) |
### Data type identifier: dem
Use `dem` (previously `DEM`) as the value of the `input.data.type` parameter in your API requests. This is mandatory and will ensure you get DEM data.
### Filtering Options
This chapter will explain the `input.data.dataFilter` object of the `DEM` `process` API.
#### demInstance
Sets the DEM to use. Will return the default DEM if no parameter is set. For information about the default DEM for each deployment, see [Endpoint Locations](#endpoint-locations).
| Identifier | DEM | Notes |
| -------------- | --------------------------------------- | --------------------------------------------------------- |
| MAPZEN | Mapzen's DEM | Contains bathymetry information |
| COPERNICUS\_30 | Copernicus DEM GLO-30 Public and GLO-90 | 30m is infilled with 90m where 30m tiles are not released |
| COPERNICUS\_90 | Copernicus DEM GLO-90 | Global |
### Processing Options
This chapter will explain the `input.data.processing` object of the `DEM` `process` API.
| Parameter | Description | Values | Default |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| upsampling | Defines the interpolation used for processing when the pixel resolution is greater than the source resolution (for example, 5m/px with a 10m/px source). | **NEAREST** - [nearest neighbour interpolation](https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
**BILINEAR** - [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
**BICUBIC** - [bicubic interpolation](https://en.wikipedia.org/wiki/Bicubic_interpolation) | **NEAREST** |
| downsampling | As above except when the resolution is lower. | **NEAREST** - [nearest neighbour interpolation](https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
**BILINEAR** - [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
**BICUBIC** - [bicubic interpolation](https://en.wikipedia.org/wiki/Bicubic_interpolation) | **NEAREST** |
| egm | An option to add geoid heights from an earth gravitational model to the orthometric heights in which case the returned values represent ellipsoidal heights relative to the WGS84 ellipsoid.
For Mapzen's DEM, we use [EGM96](https://en.wikipedia.org/wiki/Earth_Gravitational_Model#EGM96), and for Copernicus DEMs, we use [EGM2008](https://en.wikipedia.org/wiki/Earth_Gravitational_Model#EGM2008). | **TRUE** - returned values are ellipsoid heights
**FALSE** - returned values are orthometric heights | **FALSE** |
| clampNegative | **Mapzen DEM** specific option. It replaces negative orthometric heights with 0. Useful for removing ocean bathymetry, for example.
*Note: If `clampNegative:true` and `egm: true` it is still possible to have negative output values. This is because the egm offset can be negative and it is applied after clampNegative.* | **TRUE** - negative orthometric heights are replaced with 0.
**FALSE** - no changes. | **FALSE** |
### Available Bands and Data
Information in this chapter is useful when defining [`input` object](https://docs.planet.com/develop/evalscripts/functions.md#input-object-properties) in evalscript. A string listed in the column **Name** can be an element of the `input.bands` array in your evalscript.
| Property name | Description | Resolution |
| ------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DEM | Heights in meters | Various, depending on the datasource used for the generation of the DEM, [see](https://github.com/tilezen/joerd/blob/master/docs/images/footprints-preview.png). |
| dataMask | The mask of data/no data pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)). | N/A\* |
\*dataMask has no source resolution as it is calculated for each output pixel.
### Units
The data values for each band in your custom script are presented in the units as specified here. In case more than one unit is available for a given band, you may optionally set the value of `input.units` in your evalscript `setup` function to one of the values in the `Units Value` column. Doing so will present data in that unit. The `units` parameter combines the physical quantity and corresponding units of measurement values. As such, some names more closely resemble physical quantities, others resemble units of measurement.
The `Source Format` specifies how and with what precision the digital numbers (`DN`) from which the unit is derived are encoded. Bands requested in `DN` units contain exactly the pixel values of the source data. Note that resampling may produce interpolated values. `DN` is also used whenever a band is derived computationally (like dataMask); such bands can be identified by having `DN` units and `N/A` source format. `DN` values are typically not offered if they do not simply represent any physical quantity, in particular, when `DN` values require source-specific (i.e. non-global) conversion to physical quantities.
Values in non-`DN` units are computed from the source (`DN`) values with at least float32 precision. Note that the conversion might be nonlinear, therefore the full value range and quantization step size of such a band can be hard to predict. Band values in evalscripts always behave as floating point numbers, regardless of the actual precision.
The `Typical Range` indicates what values are common for a given band and unit, however outliers can be expected.
For DEM, `DN` (digital numbers) are the default and only unit. `DN` values equal elevation.
| Band | Physical Quantity (units) | Units Value | Source Format | Typical Range |
| -------- | ------------------------- | ----------- | --------------------- | ------------------------- |
| DEM | Height (meters) | METERS | INT16 or FLOAT32 \[1] | \[2] |
| dataMask | N/A | DN | N/A | 0 - no data
1 - data |
\[1]: Copernicus DEM is always FLOAT32. MAPZEN is typically INT16 but occasionally FLOAT32.
\[2]: MAPZEN includes bathymetry data while Copernicus DEM does not. As such, MAPZEN values can extend to -11000 (Mariana Trench), while Copernicus DEM values are typically positive. The highest point is of course Mount Everest at slightly less than +9000 meters.
### Scene Object
The [evalscript evaluatePixel scene object](https://docs.planet.com/develop/evalscripts/functions.md#evaluatepixel) is not returned/is null when requesting DEM.
### Collection specific constraints
DEM values are in meters and can be negative for areas which lie below sea level (for example, ocean areas or much of the Netherlands). When requesting a DEM a simple way to mitigate this is to set the output format in your evalscript to **`sampleType: SampleType.FLOAT32`** or **`sampleType: SampleType.INT16`** if this provides sufficient precision for your use. More about output formats can be found [here](https://docs.planet.com/develop/evalscripts/functions.md#sampletype).
For output formats `sampleType: SampleType.UINT8` and `sampleType: SampleType.UINT16` be careful as negative values can be misinterpreted due to signedness issues as well as potential problems due to [integer overflow](https://en.wikipedia.org/wiki/Integer_overflow). For example:
* `sampleType: SampleType.UINT8` - a height of 256 meters will be encoded as 0 in such a file due to overflow. A height of -1 meter will be encoded as 255.
* `sampleType: SampleType.UINT16`- a height of -15 meters for instance will be encoded as 65520.
One way to handle this adjustment is to ensure there are no negative values in the output by adding a constant to DEM values, for example, 12000 (the minimum value in DEM is not smaller than -11000 m). If you need actual DEM values (i.e. heights), the constant 12000 must be subtracted from the output values outside.
```
//VERSION=3
function setup() {
return {
input: ['DEM'],
output: {
id: 'default',
bands: 1,
sampleType: SampleType.UINT16,
},
};
}
function evaluatePixel(sample) {
return [sample.DEM + 12000];
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/dem/examples/)
# Digital Elevation Model (DEM) Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## Copernicus DEM 30 image (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "COPERNICUS_30"
},
"processing": {
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: { bands: 1 }
}
}
function evaluatePixel(sample) {
return [sample.DEM/1000]
}'
```
## Mapzen DEM image (png)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "MAPZEN"
},
"processing": {
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: { bands: 1 }
}
}
function evaluatePixel(sample) {
return [sample.DEM/1000]
}'
```
## Copernicus DEM 30, 0.0003° (\~33m) resolution (tiff)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "COPERNICUS_30"
},
"processing": {
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"resx": 0.0003,
"resy": 0.0003,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: { bands: 1 }
}
}
function evaluatePixel(sample) {
return [sample.DEM/1000]
}'
```
## Copernicus DEM 90 values, orthometric heights (tif)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "COPERNICUS_90"
},
"processing": {
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
return [sample.DEM]
}'
```
## Copernicus DEM 90 values, ellipsoidal heights (tif)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "COPERNICUS_90"
},
"processing": {
"egm": true,
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
return [sample.DEM]
}'
```
## Copernicus DEM 90 image at sea level (png)
```
curl -X POST \
https://services.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
10.082016,
42.625876,
10.496063,
42.927268
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "COPERNICUS_90"
},
"processing": {
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: { bands: 3 }
}
}
function evaluatePixel(sample) {
if (sample.DEM > 0) {
return [0, sample.DEM / 1000, 0]
} else {
return [0, 0, -sample.DEM / 100]
}
}'
```
## Mapzen DEM image at sea level, clampNegatives (png)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
10.082016,
42.625876,
10.496063,
42.927268
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "MAPZEN"
},
"processing": {
"clampNegative": true,
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: { bands: 1 }
}
}
function evaluatePixel(sample) {
return [sample.DEM / 1000]
}'
```
## Mapzen DEM values at sea level, orthometric heights, clampNegatives (tif)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
10.082016,
42.625876,
10.496063,
42.927268
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "MAPZEN"
},
"processing": {
"egm": false,
"clampNegative": true,
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
return [sample.DEM]
}'
```
## Mapzen DEM values at sea level, orthometric heights including negative values (tif)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'content-type: multipart/form-data' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
10.082016,
42.625876,
10.496063,
42.927268
]
},
"data": [{
"type": "dem",
"dataFilter": {
"demInstance": "MAPZEN"
},
"processing": {
"clampNegative": false,
"upsampling": "BILINEAR",
"downsampling": "BILINEAR"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["DEM"],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
return [sample.DEM]
}'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/esa-worldcover/)
# ESA WorldCover
The ESA WorldCover product provides global land cover maps for 2020 and 2021. By combining the strengths of both Sentinel-1 (SAR) and Sentinel-2 (optical), it achieves a more consistent global result than optical-only products. The 2020 version (v100) and 2021 version (v200) use slightly different algorithms, so users should exercise caution when performing direct change detection between the two years.
## Data Availability & Collections
The WorldCover map is accessible via the [Planet Insights Platform](https://insights.planet.com/) as a Bring Your Own COG (BYOC) collection.
* **Collection ID**: `0b940c63-45dd-4e6b-8019-c3660b81b884`
* **Update Frequency**: Annual (2020 and 2021 currently available).
## Basic Facts
| Property | Value |
| ----------------------- | --------------------------------------------------------- |
| **Sensor** | Sentinel-1 (C-SAR) and Sentinel-2 (MSI) |
| **Spatial Resolution** | 10 m |
| **Geographic Coverage** | Global |
| **Coordinate System** | WGS 84 (EPSG:4326) |
| **Data Format** | Cloud Optimized GeoTIFF (COG) |
| **Temporal Coverage** | 2020, 2021 |
| **License** | [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
| **Provider** | **Planet** |
## Band Information
The collection contains the main classification map and a multi-band quality layer.
| Name | Description |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Map** | Main discrete classification according to FAO LCCS scheme (11 classes). |
| **InputQuality** | 3-band layer indicating the number and quality of S1 and S2 inputs used per pixel. |
## Class Definitions
The `Map` band contains the following 11 land cover classes:
| Value | Label | Color |
| ------- | ------------------------ | --------- |
| **10** | Tree cover | `#006400` |
| **20** | Shrubland | `#ffbb22` |
| **30** | Grassland | `#ffff4c` |
| **40** | Cropland | `#f096ff` |
| **50** | Built-up | `#fa0000` |
| **60** | Bare / sparse vegetation | `#b4b4b4` |
| **70** | Snow and ice | `#f0f0f0` |
| **80** | Permanent water bodies | `#0064c8` |
| **90** | Herbaceous wetland | `#0096a0` |
| **95** | Mangroves | `#00cf75` |
| **100** | Moss and lichen | `#fae6a0` |
## Accessing the Data
### Planet Insights Platform API
To access the data programmatically:
* **Endpoint**: `services.sentinel-hub.com`
* **Collection Type**: `byoc-0b940c63-45dd-4e6b-8019-c3660b81b884`
### Visualization Script (Evalscript)
Use the following script to visualize the WorldCover map with its standard color palette:
```
// VERSION=3
// ESA WorldCover Visualization Script
const colormap = [
[10, 0x006400], // Tree cover
[20, 0xffbb22], // Shrubland
[30, 0xffff4c], // Grassland
[40, 0xf096ff], // Cropland
[50, 0xfa0000], // Built-up
[60, 0xb4b4b4], // Bare / sparse vegetation
[70, 0xf0f0f0], // Snow and ice
[80, 0x0064c8], // Permanent water bodies
[90, 0x0096a0], // Herbaceous wetland
[95, 0x00cf75], // Mangroves
[100, 0xfae6a0], // Moss and lichen
];
const visualizer = new ColorMapVisualizer(colormap);
function setup() {
return {
input: ['Map', 'dataMask'],
output: { bands: 3 },
};
}
function evaluatePixel(samples) {
return visualizer.process(samples.Map);
}
```
## Attribution
© ESA WorldCover project / Contains modified Copernicus Sentinel data (2020/2021) processed by ESA WorldCover consortium.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/impact-observatory-lulc-map/)
# 10m Annual Land Use Land Cover (9-class)
The **10m Annual Land Use Land Cover (9-class)** dataset is a global map produced by **Impact Observatory**, **Microsoft**, and **Esri**. It provides a year-by-year snapshot of global land cover at a 10-meter resolution, derived from ESA Sentinel-2 imagery using a deep learning AI model.
This dataset is particularly valuable for monitoring urbanization, deforestation, and agricultural expansion over time.
## Data Availability & Collections
The dataset is organized as a "Bring Your Own COG" (BYOC) collection within the [Planet Insights Platform](https://insights.planet.com/). Each pixel represents the most likely land cover class for the given year.
* **Collection ID**: `0ed26381-7344-4281-b180-66f3da521f75`
* **Update Frequency**: The map is updated annually following the completion of the calendar year.
## Basic Facts
| Property | Value |
| ---------------------- | --------------------------------------------------------- |
| **Sensor** | MultiSpectral Instrument (MSI) from Sentinel-2 |
| **Spatial Resolution** | 10 m |
| **Coordinate System** | UTM (aligned to Sentinel-2 tiling grid) |
| **Data Format** | Cloud Optimized GeoTIFF (COG) |
| **Temporal Coverage** | 2017 – 2023 (Updated annually) |
| **License** | [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
| **Provider** | **Planet** |
## Class Definitions
The product consists of a single band named `lulc`. Each pixel contains an integer value from 1 to 11. Note that values 3 and 6 are not used in this 9-class schema.
| Value | Label | Color |
| ------ | ---------------------- | --------- |
| **1** | **Water** | `#419bdf` |
| **2** | **Trees** | `#397d49` |
| **4** | **Flooded Vegetation** | `#7a87c6` |
| **5** | **Crops** | `#e49635` |
| **7** | **Built Area** | `#c4281b` |
| **8** | **Bare Ground** | `#a59b8f` |
| **9** | **Snow/Ice** | `#a8ebff` |
| **10** | **Clouds** | `#616161` |
| **11** | **Rangeland** | `#e3e2c3` |
## Accessing the Data
### AWS S3 Access
The data is hosted in the AWS `us-west-2` region. You can browse the directory structure using the AWS CLI:
```
aws s3 ls --no-sign-request s3://io-10m-annual-lulc/
```
### Planet Insights Platform API
To access the data programmatically via the [Planet Insights Platform](https://insights.planet.com/):
* Endpoint: `services.sentinel-hub.com`
* Collection Type: `byoc-0ed26381-7344-4281-b180-66f3da521f75`
## Visualization Script (Evalscript)
To view the land cover map with the standard classification colors, use the following [Evalscript](https://docs.planet.com/develop/evalscripts.md) in your request:
```
// VERSION=3
// Impact Observatory 10m LULC Visualizer
const colormap = [
[1, 0x419bdf], // Water
[2, 0x397d49], // Trees
[4, 0x7a87c6], // Flooded Vegetation
[5, 0xe49635], // Crops
[7, 0xc4281b], // Built Area
[8, 0xa59b8f], // Bare Ground
[9, 0xa8ebff], // Snow/Ice
[10, 0x616161], // Clouds
[11, 0xe3e2c3], // Rangeland
];
const visualizer = new ColorMapVisualizer(colormap);
function setup() {
return {
input: ['lulc', 'dataMask'],
output: { bands: 3 },
};
}
function evaluatePixel(samples) {
return visualizer.process(samples.lulc);
}
```
## Attribution
This dataset is collaboratively produced by [Impact Observatory](https://www.impactobservatory.com/maps-for-good/), Microsoft, and Esri. It contains modified Copernicus Sentinel data processed by these partners.
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/other-datasets/sentinel-s2-l2a-mosaic-120/)
# Sentinel-2 L2A 120m Mosaic
The Sentinel-2 L2A 120m mosaic is a derived product that provides the "best pixel" values for 10-daily periods. It is modeled by removing cloudy pixels and performing linear interpolation among the remaining valid observations. While designed to be cloud-free, some clouds may remain in regions with persistent, lengthy cloudy periods.
## Data Availability & Collections
The mosaic is split into annual collections with different band configurations.
* 2020 Collection: Contains 12 spectral bands and 1 quality mask.
* **Collection ID**: `484d8dbb-9e3e-41f2-b96b-35189d3ae37f`
* 2019 Collection: Contains 6 spectral bands.
* **Collection ID**: `0074520d-bcf5-4811-8f6f-afd946e77695`
## Basic Facts
| Property | Value |
| ---------------------- | --------------------------------------------------------- |
| **Sensor** | MultiSpectral Instrument (MSI) from Sentinel-2 |
| **Spatial Resolution** | 120 m |
| **Coordinate System** | UTM |
| **Data Format** | Cloud Optimized GeoTIFF (COG) |
| **Temporal Coverage** | 2019, 2020 (Annual updates) |
| **License** | [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
| **Provider** | **Planet** |
## Band Information (2019 Product)
The 2019 mosaic includes the following 6 bands, typically provided in Digital Numbers (DN) ranging from 0 to 10,000.
| Name | Description | Resolution |
| ---- | ----------- | ---------- |
| B02 | Blue | 120 m |
| B03 | Green | 120 m |
| B04 | Red | 120 m |
| B08 | NIR | 120 m |
| B11 | SWIR 1 | 120 m |
| B12 | SWIR 2 | 120 m |
## Quality Mask (QM)
The `QM` band is essential for identifying the reliability of the interpolated data. It is recommended to filter data where `QM != 0`.
| Value | Meaning | Description |
| ----- | -------------------- | -------------------------------------------------------------- |
| 0 | No Data | Areas where no valid observations were found. |
| 1 | Interpolation Passed | Areas where the interpolation successfully finished. |
| 2 | Artificially Raised | DN values raised from 0 to 1 to avoid confusion with NO\_DATA. |
| 3 | Interpolation Failed | Detected persistent clouds; values set to maximum (10,000). |
## Accessing the Data
### AWS S3 Access
The data is hosted on AWS in the `eu-central-1` region. You can list objects using the AWS CLI without an account:
```
aws s3 ls --no-sign-request s3://sentinel-s2-l2a-mosaic-120/2019/
```
Path Structure: `[year]/[month]/[day]/[UTM_code][latitude_band]/`
### Planet Insights Platform API
To access the data programmatically via the [Planet Insights Platform](https://insights.planet.com/):
* Endpoint: `services.sentinel-hub.com`
* Collection Type: `byoc-[Collection_ID]`
## Band Information (2020 Product)
The 2020 mosaic contains the full spectral range of Sentinel-2.
| Name | Description | Resolution |
| ----------- | ---------------- | ---------- |
| **B01** | Coastal aerosol | 120 m |
| **B02** | Blue | 120 m |
| **B03** | Green | 120 m |
| **B04** | Red | 120 m |
| **B05-B07** | Red Edge | 120 m |
| **B08/B8A** | NIR / Narrow NIR | 120 m |
| **B09** | Water Vapour | 120 m |
| **B11/B12** | SWIR 1 / SWIR 2 | 120 m |
| **QM** | Quality Mask | 120 m |
### Custom Scripts: Interpolated Time-Series
For users wanting to recreate or customize this mosaic, an **Interpolated Time-series** script is available. This script:
1. Defines a start and end date (for example, a full year).
2. Splits the timeframe into equal 10-daily intervals.
3. Applies cloud masking using `CLM` and `CLP` bands.
4. Performs linear interpolation to fill gaps caused by cloud cover.
**Example Evalscript Snippet:**
```
// VERSION=3
// Basic linear interpolation logic used for the 120m mosaic
function linearInterpolation(x, x0, y0, x1, y1) {
var a = (y1 - y0) / (x1 - x0);
var b = -a * x0 + y0;
return a * x + b;
}
```
## Attribution
Contains modified Copernicus Sentinel data \[Year] processed by Sentinel Hub. For citations, use: Sentinel-2 L2A 120m Mosaic was accessed on \[DATE] from .
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/)
# USGS & NASA Imagery
[](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel.md)
### [Harmonized Landsat Sentinel](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel.md)
[Use Processing API to access Harmonized Landsat Sentinel data with 13 optical and 2 thermal bands.](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel.md)
[](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm.md)
### [Landsat 4-5 TM L1 & L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm.md)
[Use Processing API to access Landsat 4–5 Thematic Mapper (TM) Level 1 and Level 2 data, including optical, thermal, and surface reflectance products.](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm.md)
[](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm.md)
### [Landsat 7 ETM+ L1 & L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm.md)
[Use Processing API to access Landsat 7 Enhanced Thematic Mapper Plus (ETM+) Level 1 and Level 2 data, including optical, thermal, and surface reflectance products.](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm.md)
[](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9.md)
### [Landsat 8-9 L1 & L2](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9.md)
[Use Processing API to access Landsat 8–9 Level 1 and Level 2 data, including optical, thermal, and surface reflectance products.](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel/)
# Harmonized Landsat Sentinel
Harmonized Landsat Sentinel is a NASA initiative to produce a Virtual Constellation of surface reflectance (SR) data from the Operational Land Imager (OLI) and Multi-Spectral Instrument (MSI) aboard the Landsat 8-9 and Sentinel-2 remote sensing satellites, respectively. The combined measurement enables global observations of the land every 2–3 days.
Input products are Landsat 8-9 Collection 2 Level 1 top-of-atmosphere reflectance and Sentinel-2 L1C top-of-atmosphere reflectance, which NASA radiometrically harmonizes to the maximum extent, resamples to common 30-meter resolution, and grids using the Sentinel-2 Military Grid Reference System (MGRS) UTM grid. Because of this, the products are different from Landsat 8-9 Collection 2 Level 2 surface reflectance and Sentinel-2 L2A surface reflectance. Learn more about the data [here](https://lpdaac.usgs.gov/data/get-started-data/collection-overview/missions/harmonized-landsat-sentinel-2-hls-overview/).
### Basic Facts
| Property | Info |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| **Spatial resolution** | 30 m |
| **Sensor** | Operational Land Imager for Landsat 8-9, and MultiSpectral Instrument for Sentinel-2 satellites. |
| **Revisit time** | 2-3 days |
| **Spatial coverage** | Whole globe |
| **Data availability** | Landsat 8-9 since April 2013, Sentinel-2 since November 2015. |
| **Common usage/purpose** | Vegetation monitoring, land use, land cover maps and monitoring of changes. |
## Accessing Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the collection you are querying. This chapter will help you understand the parameters for HLS data. For an overview of all API parameters see the [API Reference](https://docs.planet.com/develop/apis.md).
### Endpoint Locations
| Service | Notes |
| ------------------------------------- | ------------------------------------------------------------- |
| services-uswest2.sentinel-hub.com/api | Landsat 8-9 since April 2013, Sentinel-2 since November 2015. |
### Data type identifier: `hls`
Use `hls` as the value of the `input.data.type parameter` in your API requests. This is mandatory and will ensure you get HLS data.
### Filtering Options
This chapter will explain the `input.data.dataFilter` object of the `process` API.
#### `mosaickingOrder`
Sets the order of overlapping tiles from which the output result is mosaicked. Note that tiles will in most cases come from the same orbit/acquisition. The tiling is done by NASA for easier distribution.
| Value | Description | Notes |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **mostRecent** | (default) The pixel will be selected from the most recently acquired tile | |
| **leastRecent** | similar to **mostRecent** but in reverse order | |
| **leastCC** | The pixel is selected from the tile with the lowest cloud coverage | This information is estimated per tile (each covering about 31,100 sq. km) so local cloud coverage may differ |
#### `maxCloudCoverage`
Sets the upper limit for cloud coverage in percent based on the precomputed cloud coverage estimate for each tile as present in the tile metadata. Satellite data will therefore not be retrieved for tiles with a higher cloud coverage estimate. For example, by setting the value to `20`, only tiles with at most 20% cloud coverage will be used. Note that this parameter is set per tile and might not be directly applicable to the chosen area of interest.
#### `constellation`
Selects constellation. By default, both constellations are selected. Note that for any type of data mosaicking, for requests containing bands which are present in only one constellation (e.g. `RedEdge1`), it is highly recommended (but not strictly necessary) to set the corresponding `constellation` parameter. Otherwise, your request may fail as the band is not guaranteed to be present for all data being mosaicked.
| Value | Description |
| ------------ | ------------------------------ |
| **SENTINEL** | selects only Sentinel products |
| **LANDSAT** | selects only Landsat products |
### Processing Options
This chapter will explain the `input.data.processing` object of the `process` API.
| Parameter | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| upsampling | [The same as for S2L1C.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
| downsampling | [The same as for S2L1C.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
### Available Bands and Data
Information in this chapter is useful when defining [`input` object](https://docs.planet.com/develop/evalscripts/functions.md#input-object-properties) in evalscript. Any string listed in the column **Name** can be an element of the `input.bands` array in your evalscript.
| Name | Description | Resolution | Constellation |
| ---------------- | --------------------------------------------------------------------------------------------------- | ---------- | ------------- |
| CoastalAerosol | Coastal Aerosol - band 1 from Landsat and Sentinel | 30 m | Both |
| Blue | Blue - band 2 from both | 30 m | Both |
| Green | Green - band 3 from both | 30 m | Both |
| Red | Red - band 4 from both | 30 m | Both |
| RedEdge1 | Red-Edge 1 - band 5 from Sentinel | 30 m | Sentinel |
| RedEdge2 | Red-Edge 2 - band 6 from Sentinel | 30 m | Sentinel |
| RedEdge3 | Red-Edge 3 - band 7 from Sentinel | 30 m | Sentinel |
| NIR\_Broad | NIR Broad - band 8 from Sentinel | 30 m | Sentinel |
| NIR\_Narrow | NIR Narrow - band 5 from Landsat and 8A from Sentinel | 30 m | Both |
| SWIR1 | SWIR 1 - band 6 from Landsat and 11 from Sentinel | 30 m | Both |
| SWIR2 | SWIR 2 - band 7 from Landsat and 12 from Sentinel | 30 m | Both |
| WaterVapor | Water Vapor - band 9 from Sentinel | 30 m | Sentinel |
| Cirrus | Cirrus - band 9 from Landsat and 10 from Sentinel | 30 m | Both |
| ThermalInfrared1 | Thermal Infrared 1 - band 10 from Landsat | 30 m | Landsat |
| ThermalInfrared2 | Thermal Infrared 2 - band 11 from Landsat | 30 m | Landsat |
| QA | Quality Assessment band (QA) | 30 m | Both |
| VAA | View (sensor) Azimuth Angle | 30 m | Both |
| VZA | View (sensor) Zenith Angle | 30 m | Both |
| SAA | Sun Azimuth Angle | 30 m | Both |
| SZA | Sun Zenith Angle | 30 m | Both |
| dataMask | The mask of data/no data pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)). | N/A \[1] | Both |
\[1]: dataMask has no source resolution as it is calculated for each output pixel.
For more info about the bands, check [HLS user guide](https://lpdaac.usgs.gov/documents/1698/HLS_User_Guide_V2.pdf).
### Units
The data values for each band in your custom script are presented in the units as specified here. In case more than one unit is available for a given band, you may optionally set the value of `input.units` in your evalscript `setup` function to one of the values in the `Units Value` column. Doing so will present data in that unit. The `units` parameter combines the physical quantity and corresponding units of measurement values. As such, some names more closely resemble physical quantities, others resemble units of measurement.
The `Source Format` specifies how and with what precision the digital numbers (`DN`) from which the unit is derived are encoded. Bands requested in `DN` units contain exactly the pixel values of the source data. Note that resampling may produce interpolated values. `DN` is also used whenever a band is derived computationally (like dataMask); such bands can be identified by having `DN` units and `N/A` source format. `DN` values are typically not offered if they do not simply represent any physical quantity, in particular, when `DN` values require source-specific (i.e. non-global) conversion to physical quantities.
Values in non-`DN` units are computed from the source (`DN`) values with at least float32 precision. Note that the conversion might be nonlinear, therefore the full value range and quantization step size of such a band can be hard to predict. Band values in evalscripts always behave as floating point numbers, regardless of the actual precision.
The `Typical Range` indicates what values are common for a given band and unit, however outliers can be expected.
For optical data, the relation between `DN` and `REFLECTANCE` (default unit) is: `DN = 10000 * REFLECTANCE`.
For thermal data, the relation between `DN` and `BRIGHTNESS_TEMPERATURE` (default unit) is: `DN = 100 * BRIGHTNESS_TEMPERATURE`.
For angle view data, the relation between `DN` and `DEGREES` (default unit) is: `DN = 100 * DEGREES`.
| Band | Physical Quantity (units) | Units Value | Source Format | Typical Range | Notes |
| ---------------------- | ----------------------------------- | ---------------------------- | ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Optical bands | Surface reflectance (unitless) | REFLECTANCE | INT16 | 0 - 0.4 | Higher values in infrared bands. Reflectance values can easily be above 1. |
| Optical bands | Digital numbers (unitless) | DN | INT16 | 0 - 4000 | |
| Thermal infrared bands | Brightness temperature (kelvin) | BRIGHTNESS\_TEMPERATURE \[1] | INT16 | 250 - 320 | Brightness temperature of roughly -20 to +50 C. Can reach outside this range in extreme environments. |
| Thermal infrared bands | Digital numbers (unitless) | DN | INT16 | 25000-32000 | Brightness temperature of roughly -20 to +50 C. Can reach outside this range in extreme environments. |
| QA | Pixel quality assessment (unitless) | DN | UINT8 | bit-packed combination | For the interpretation, check chapter 6.4 of the [user guide](https://lpdaac.usgs.gov/documents/1698/HLS_User_Guide_V2.pdf). |
| View angles | Angle (degrees) | DEGREES | UINT16 | | |
| View angles | Digital numbers (unitless) | DN | UINT16 | | |
| dataMask | N/A | DN | N/A | 0 - no data
1 - data | |
\[1]: Top of the Atmosphere Brightness Temperature.
### Scenes Object
[`scenes` object](https://docs.planet.com/develop/evalscripts/functions.md#scenes) stores metadata. An example of metadata available in `scenes` object for HLS when mosaicking is `ORBIT`:
| Property name | Value |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| dateFrom | `'2018-12-25T00:00:00Z'` |
| dateTo | `'2018-12-25T23:59:59Z'` |
| tiles\[i].hlsProductId | `'HLSS30.020/HLS.S30.T58WEV.2020273T003609.v2.0`' |
| tiles\[i].date | `'2018-12-25T09:45:29.121783Z'` |
| tiles\[i].shId | `3097841` |
| tiles\[i].cloudCoverage | `98.35` |
| tiles\[i].dataPath | `'https://lp-prod-protected.s3.amazonaws.com/HLSS30.020/HLS.S30.T58WEV.2020273T003609.v2.0'` |
Properties of a `scenes` object can differ depending on the selected mosaicking and in which evalscript function the object is accessed. [Working with metadata in evalscript](https://docs.planet.com/develop/evalscripts.md#working-with-metadata-in-evalscripts) user guide explains all details and provide examples.
## Catalog API Capabilities
To access HLS product metadata you need to send search request to our [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md). The requested metadata will be returned as JSON formatted response to your request.
### Collection identifier: `hls`
### Filter extension
* `eo:cloud_cover` cloud cover percentage
* `constellation` ([possible values](#constellation))
### Distinct extension
* `date`
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/harmonized-landsat-sentinel/examples/)
# Harmonized Landsat Sentinel Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## True Color
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["Blue", "Green", "Red"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.Red, 2.5 * sample.Green, 2.5 * sample.Blue]
}
'
```
## True Color, full 30 meter resolution (EPSG 32633)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
284281.024812,
4637026.521832,
301547.842435,
4652124.141629
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"resx": 30,
"resy": 30
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["Red", "Green", "Blue", "dataMask"],
output: {
bands: 4
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.Red, 2.5 * sample.Green, 2.5 * sample.Blue, sample.dataMask]
}
'
```
## NDVI as jpeg image with bounds given as polygon
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg" }
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["NIR_Narrow", "Red", "dataMask"],
output: { bands: 4 }
}
}
function evaluatePixel(sample) {
var ndvi = (sample.NIR_Narrow - sample.Red) / (sample.NIR_Narrow + sample.Red)
if (ndvi<-0.5) return [0.05,0.05,0.05,sample.dataMask]
else if (ndvi<-0.2) return [0.75,0.75,0.75,sample.dataMask]
else if (ndvi<-0.1) return [0.86,0.86,0.86,sample.dataMask]
else if (ndvi<0) return [0.92,0.92,0.92,sample.dataMask]
else if (ndvi<0.025) return [1,0.98,0.8,sample.dataMask]
else if (ndvi<0.05) return [0.93,0.91,0.71,sample.dataMask]
else if (ndvi<0.075) return [0.87,0.85,0.61,sample.dataMask]
else if (ndvi<0.1) return [0.8,0.78,0.51,sample.dataMask]
else if (ndvi<0.125) return [0.74,0.72,0.42,sample.dataMask]
else if (ndvi<0.15) return [0.69,0.76,0.38,sample.dataMask]
else if (ndvi<0.175) return [0.64,0.8,0.35,sample.dataMask]
else if (ndvi<0.2) return [0.57,0.75,0.32,sample.dataMask]
else if (ndvi<0.25) return [0.5,0.7,0.28,sample.dataMask]
else if (ndvi<0.3) return [0.44,0.64,0.25,sample.dataMask]
else if (ndvi<0.35) return [0.38,0.59,0.21,sample.dataMask]
else if (ndvi<0.4) return [0.31,0.54,0.18,sample.dataMask]
else if (ndvi<0.45) return [0.25,0.49,0.14,sample.dataMask]
else if (ndvi<0.5) return [0.19,0.43,0.11,sample.dataMask]
else if (ndvi<0.55) return [0.13,0.38,0.07,sample.dataMask]
else if (ndvi<0.6) return [0.06,0.33,0.04,sample.dataMask]
else return [0,0.27,0,sample.dataMask]
}'
```
## Exact NDVI values using a floating point GeoTIFF
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["Red", "NIR_Narrow", "dataMask"]
}],
output: {
id: "default",
bands: 2,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.NIR_Narrow - sample.Red) / (sample.NIR_Narrow + sample.Red)
return [ ndvi, sample.dataMask ]
}'
```
## Landsat Thermal Band as jpeg image with bounds given as bounding box
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"constellation": "LANDSAT"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = -50
let maxVal = 50
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"ThermalInfrared1",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.ThermalInfrared1
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
## Landsat Thermal band Kelvin values using a FLOAT32 GeoTIFF
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"constellation": "LANDSAT"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"ThermalInfrared1", "dataMask"
]
}],
output: {
bands: 2,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.ThermalInfrared1, samples.dataMask]
}
'
```
## Sentinel Red Edge Composite
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2022-07-01T00:00:00Z",
"to": "2022-07-31T00:00:00Z"
},
"constellation": "SENTINEL"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=
//VERSION=3
function setup() {
return {
input: [{
bands: [
"RedEdge3", "RedEdge2", "RedEdge1", "dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
return [3*samples.RedEdge3, 3*samples.RedEdge2, 3*samples.RedEdge1, samples.dataMask]
}
'
```
## Sentinel True color and metadata (multi-part response GeoTIFF and json)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2022-07-01T00:00:00Z",
"to": "2022-07-31T00:00:00Z"
},
"constellation": "SENTINEL"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["Blue", "Green", "Red", "dataMask"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 4
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].Red, 2.5 * samples[0].Green, 2.5 * samples[0].Blue, samples.dataMask]
}
'
```
## True color multi-part response (different formats and SampleType)
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "hls",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["Red", "Green", "Blue"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.Red, 2.5 * sample.Green, 2.5 * sample.Blue],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.Red * 255, sample.Green * 255, sample.Blue * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.Red * 65535, sample.Green * 65535, sample.Blue * 65535],
// Reflectance values
true_color_32float: [sample.Red, sample.Green, sample.Blue],
}
}
'
```
## HLS bands from both constellations as GeoTIFF
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T23:59:59Z"
}
},
"type": "hls"
}
]
},
"output": {
"width": 512,
"height": 464.292,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["CoastalAerosol", "Blue", "Green", "Red", "NIR_Narrow", "SWIR1", "SWIR2", "Cirrus", "QA"]
}],
output: {
id: "default",
bands: 9,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.CoastalAerosol, 10000 * sample.Blue, 10000 * sample.Green, 10000 * sample.Red, 10000 * sample.NIR_Narrow, 10000 * sample.SWIR1, 10000 * sample.SWIR2, 1000* sample.Cirrus, sample.QA]
}'
```
## Only HLS Sentinel-2 bands as GeoTIFF
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T23:59:59Z"
},
"constellation": "SENTINEL"
},
"type": "hls"
}
]
},
"output": {
"width": 512,
"height": 464.292,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["CoastalAerosol", "Blue", "Green", "Red", "RedEdge1", "RedEdge2", "RedEdge3", "NIR_Broad", "NIR_Narrow", "SWIR1", "SWIR2", "Cirrus", "QA"]
}],
output: {
id: "default",
bands: 13,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.CoastalAerosol, 10000 * sample.Blue, 10000 * sample.Green, 10000 * sample.Red, 10000 * sample.RedEdge1, 10000 * sample.RedEdge2, 10000 * sample.RedEdge3, 1000* sample.NIR_Broad, 10000 * sample.NIR_Narrow, 10000 * sample.SWIR1, 10000 * sample.SWIR2, 1000* sample.Cirrus, sample.QA]
}'
```
## Only HLS Landsat8/9 bands as GeoTIFF
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T23:59:59Z"
},
"constellation": "LANDSAT"
},
"type": "hls"
}
]
},
"output": {
"width": 512,
"height": 464.292,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["CoastalAerosol", "Blue", "Green", "Red", "NIR_Narrow", "SWIR1", "SWIR2", "Cirrus", "ThermalInfrared1", "ThermalInfrared2", "QA"]
}],
output: {
id: "default",
bands: 11,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.CoastalAerosol, 10000 * sample.Blue, 10000 * sample.Green, 10000 * sample.Red, 10000 * sample.NIR_Narrow, 10000 * sample.SWIR1, 10000 * sample.SWIR2, 1000* sample.Cirrus, sample.ThermalInfrared1, sample.ThermalInfrared2, sample.QA]
}'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm/)
# Landsat 4-5 TM L1 & L2
The Landsat Thematic Mapper (TM) sensor was carried onboard Landsats 4 and 5. It provides 6 spectral bands and 1 thermal infrared band. Landsat 4–5 TM Collection 2 includes both Level 1 and Level 2 products, supporting long-term global Earth observation from the early 1980s through 2012.
Landsat 4–5 TM Level 1 products provide radiometrically calibrated and orthorectified Top-of-Atmosphere (TOA) reflectance and brightness temperature data. Landsat 4–5 TM Level 2 products provide atmospherically corrected surface reflectance and surface temperature science products derived from Collection 2 Level 1 inputs.
## Basic Facts
| Property | Landsat 4–5 TM Level 1 | Landsat 4–5 TM Level 2 |
| ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Data type** | TOA Reflectance and Brightness Temperature | Surface Reflectance and Surface Temperature |
| **Spatial resolution** | 30 m (thermal band resampled from 120 m) | 30 m (thermal band resampled from 120 m) |
| **Sensor** | Thematic Mapper (TM) with 6 spectral bands and 1 thermal infrared band | Thematic Mapper (TM) with 6 spectral bands and 1 thermal infrared band |
| **Revisit time** | 16 days | 16 days |
| **Spatial coverage** | Whole globe | Whole globe |
| **Data availability** | Landsat 4: Aug 1982 – Dec 1993
Landsat 5: Mar 1984 – May 2012 | Landsat 4: Aug 1982 – Dec 1993
Landsat 5: Mar 1984 – May 2012 |
| **Common usage/purpose** | Vegetation monitoring, land use, land cover maps and monitoring of changes | Vegetation monitoring, land use, land cover maps and monitoring of changes |
## Accessing Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the collection you are querying.
For an overview of all API parameters see the [API Reference](https://docs.planet.com/develop/apis/processing/reference.md).
### Endpoint Locations
| Service | Notes |
| ------------------------------------- | ------------------------------------------ |
| services-uswest2.sentinel-hub.com/api | Global coverage from July 1982 to May 2012 |
### Data type identifiers
Use the following values for `input.data.type`:
| Dataset | Identifier |
| ---------------------- | --------------- |
| Landsat 4–5 TM Level 1 | `landsat-tm-l1` |
| Landsat 4–5 TM Level 2 | `landsat-tm-l2` |
## Filtering Options
This chapter explains the `input.data.dataFilter` object of the `process` API.
### `mosaickingOrder`
Sets the order of overlapping tiles from which the output result is mosaicked. Note that tiles will in most cases come from the same orbit/acquisition. The tiling is done by USGS for easier distribution.
| Value | Description | Notes |
| --------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **mostRecent** | (default) The pixel will be selected from the most recently acquired tile | |
| **leastRecent** | similar to **mostRecent** but in reverse order | |
| **leastCC** | The pixel is selected from the tile with the lowest cloud coverage | Estimated per tile (\~31,000 sq. km); local cloud coverage may differ |
### `maxCloudCoverage`
Sets the upper limit for cloud coverage in percent based on the precomputed cloud coverage estimate for each tile as present in the tile metadata.
### `tiers`
| Value | Description |
| -------------- | ------------------------------------------------------- |
| **TIER\_1** | selects Tier 1 products |
| **ALL\_TIERS** | selected by default. selects Tier 1 and Tier 2 products |
## Processing Options
This chapter explains the `input.data.processing` object of the `process` API.
| Parameter | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| upsampling | [Same as Sentinel-2.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
| downsampling | [Same as Sentinel-2.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
## Available Bands and Data
### Landsat 4–5 TM Level 1 Bands
| Name | Description | Resolution |
| ---------- | ---------------------------------------------------- | ---------- |
| B01 | Blue (450–520 nm) | 30 m |
| B02 | Green (520–600 nm) | 30 m |
| B03 | Red (630–690 nm) | 30 m |
| B04 | Near Infrared (760–900 nm) | 30 m |
| B05 | SWIR 1 (1550–1750 nm) | 30 m |
| B06 | Thermal Infrared (10400–12500 nm) | 30 m \[1] |
| B07 | SWIR 2 (2080–2350 nm) | 30 m |
| BQA | Quality Assessment band | 30 m |
| QA\_RADSAT | Radiometric Saturation and Terrain Occlusion QA Band | 30 m |
| VAA | View Azimuth Angle | 30 m |
| VZA | View Zenith Angle | 30 m |
| SAA | Sun Azimuth Angle | 30 m |
| SZA | Sun Zenith Angle | 30 m |
| dataMask | Data / no-data mask | N/A |
\[1]: Thermal band is acquired at 120 m and resampled to 30 m.
### Landsat 4–5 TM Level 2 Bands
Includes all Level 1 bands plus surface reflectance and surface temperature–related products:
| Name | Description | Resolution |
| ------------------ | ------------------------------- | ---------- |
| B01–B05, B07 | Surface reflectance bands | 30 m |
| B06 | Surface temperature | 30 m |
| ST\_QA | Surface Temperature Uncertainty | 30 m |
| ST\_TRAD | Thermal surface radiance | 30 m |
| ST\_URAD | Upwelled radiance | 30 m |
| ST\_DRAD | Downwelled radiance | 30 m |
| ST\_ATRAN | Atmospheric transmittance | 30 m |
| ST\_EMIS | Emissivity | 30 m |
| ST\_EMSD | Emissivity standard deviation | 30 m |
| ST\_CDIST | Pixel distance to cloud | 30 m |
| SR\_ATMOS\_OPACITY | Atmospheric opacity | 30 m |
| SR\_CLOUD\_QA | Cloud Quality Assessment | 30 m |
| dataMask | Data / no-data mask | N/A |
## Units
Both Level 1 and Level 2 units are preserved exactly as defined in the original pages.
* **Level 1**: TOA Reflectance and Brightness Temperature
* **Level 2**: Surface Reflectance and Surface Temperature
(See original unit tables for full band-level details.)
## Scenes Object
The [`scenes` object](https://docs.planet.com/develop/evalscripts/functions.md#scenes) stores metadata returned with Processing API responses. Properties may differ depending on mosaicking and product level.
## Catalog API Capabilities
To access Landsat 4–5 TM metadata, send a search request to our [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md).
### Collection identifiers
* `landsat-tm-l1`
* `landsat-tm-l2`
### Filter extension
* `eo:cloud_cover`
* `landsat:scene_id`
* `landsat:collection_category`
### Distinct extension
* `date`
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-4-5-tm/examples/)
# Landsat 4-5 TM L1 & L2 Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## True Color
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, resolution (EPSG 32633)
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"resx": 100,
"resy": 100
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, multi-band GeoTIFF
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, mosaicking with leastRecent
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B01, 2.5 * sample.B02, 2.5 * sample.B03]
}
'
```
## True Color and metadata (multi-part response GeoTIFF and json)
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 3
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].B03, 2.5 * samples[0].B02, 2.5 * samples[0].B01]
}
'
```
## True Color multi-part response (different formats and SampleType)
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.B03 * 255, sample.B02 * 255, sample.B01 * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.B03 * 65535, sample.B02 * 65535, sample.B01 * 65535],
// Reflectance values
true_color_32float: [sample.B03, sample.B02, sample.B01],
}
}
'
```
## NDVI as jpeg image with bounds given as polygon
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B03", "B04"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
## Exact NDVI values using a floating point GeoTIFF
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B03", "B04"]
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
return [ ndvi ]
}'
```
## NDVI image and value (multi-part response png and GeoTIFF)
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B03", "B04"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO
}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
if (ndvi < -0.5) image = [0.05, 0.05, 0.05]
else if (ndvi < -0.2) image = [0.75, 0.75, 0.75]
else if (ndvi < -0.1) image = [0.86, 0.86, 0.86]
else if (ndvi < 0) image = [0.92, 0.92, 0.92]
else if (ndvi < 0.025) image = [1, 0.98, 0.8]
else if (ndvi < 0.05) image = [0.93, 0.91, 0.71]
else if (ndvi < 0.075) image = [0.87, 0.85, 0.61]
else if (ndvi < 0.1) image = [0.8, 0.78, 0.51]
else if (ndvi < 0.125) image = [0.74, 0.72, 0.42]
else if (ndvi < 0.15) image = [0.69, 0.76, 0.38]
else if (ndvi < 0.175) image = [0.64, 0.8, 0.35]
else if (ndvi < 0.2) image = [0.57, 0.75, 0.32]
else if (ndvi < 0.25) image = [0.5, 0.7, 0.28]
else if (ndvi < 0.3) image = [0.44, 0.64, 0.25]
else if (ndvi < 0.35) image = [0.38, 0.59, 0.21]
else if (ndvi < 0.4) image = [0.31, 0.54, 0.18]
else if (ndvi < 0.45) image = [0.25, 0.49, 0.14]
else if (ndvi < 0.5) image = [0.19, 0.43, 0.11]
else if (ndvi < 0.55) image = [0.13, 0.38, 0.07]
else if (ndvi < 0.6) image = [0.06, 0.33, 0.04]
else image = [0, 0.27, 0]
return {
default: [ndvi],
ndvi_image: image
}
}
'
```
## All bands as GeoTIFF
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "BQA"]
}],
output: {
id: "default",
bands: 9,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands B01-B09, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.B01, 10000 * sample.B02, 10000 * sample.B03, 10000 * sample.B04, 10000 * sample.B05, sample.B06, 10000 * sample.B07, sample.BQA]
}
'
```
## Thermal Band as jpeg image with bounds given as bounding box
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = 200
let maxVal = 375
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"B06",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.B06
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
## Extract Thermal band Kelvin values using a FLOAT32 GeoTIFF
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-tm-l2",
"dataFilter": {
"timeRange": {
"from": "2010-07-01T00:00:00Z",
"to": "2010-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B06"
]
}],
output: {
bands: 1,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.B06]
}
'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm/)
# Landsat 7 ETM+ L1 & L2
The Landsat 7 Enhanced Thematic Mapper (ETM+) sensor is carried onboard Landsat 7. It provides seven spectral bands and one thermal band. Learn more about [Landsat 7 ETM+](https://www.usgs.gov/search?keywords=USGS+EROS+Archive+-+Landsat+Archives+-+Landsat+7+Enhanced+Thematic+Mapper+Plus+%28ETM%2B%29).
## Basic Facts
| Property | Landsat 7 ETM+ L1 | Landsat 7 ETM+ L2 |
| ---------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Spatial resolution** | 15 m for the panchromatic band and 30 m for the rest (the thermal band is resampled from 60 m) | 30 m (the thermal band is resampled from 60 m) |
| **Sensor** | Enhanced Thematic Mapper (ETM+) with 8 spectral bands and 1 thermal band | Enhanced Thematic Mapper (ETM+) with 7 spectral bands and 1 thermal band |
| **Revisit time** | 16 days | 16 days |
| **Spatial coverage** | Whole globe | Whole globe |
| **Data availability** | From May 1999 to January 2024 | From May 1999 to January 2024 |
## Accessing Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the collection you are querying. This chapter will help you understand the parameters for Landsat 7 ETM+ Level 1 and Level 2 data. For an overview of all API parameters see the [API Reference](https://docs.planet.com/develop/apis/processing/reference.md).
### Endpoint Locations
| Service | Notes |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| services-uswest2.sentinel-hub.com/api | Global coverage since April 1999. All scenes collected since May 30, 2003 have data gaps due to the Scan Line Corrector (SLC) failure. |
### Data type identifiers
Use the following values for `input.data.type`:
| Dataset | Identifier |
| ---------------------- | ------------------------------------ |
| Landsat 7 ETM+ Level 1 | `landsat-etm-l1` (previously LETML1) |
| Landsat 7 ETM+ Level 2 | `landsat-etm-l2` (previously LETML2) |
## Filtering Options
This chapter explains the `input.data.dataFilter` object.
### `mosaickingOrder`
| Value | Description | Notes |
| --------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **mostRecent** | (default) The pixel is selected from the most recently acquired tile | |
| **leastRecent** | Same as **mostRecent**, but in reverse order | |
| **leastCC** | Pixel selected from tile with lowest cloud coverage | Estimated per tile (each covering \~31,100 sq. km); local cloud coverage may differ |
### `maxCloudCoverage`
Sets the upper limit for cloud coverage in percent based on the precomputed cloud coverage estimate for each tile as present in the tile metadata. Satellite data will therefore not be retrieved for tiles with a higher cloud coverage estimate. For example, by setting the value to `20`, only tiles with at most 20% cloud coverage will be used. Note that this parameter is set per tile and might not be directly applicable to the chosen area of interest.
### `tiers`
#### Level 1 tiers
| Value | Description |
| -------------------- | ----------------------------------------------- |
| **TIER\_1** | Tier 1 products |
| **TIER\_1\_AND\_RT** | Tier 1 and Real-Time products |
| **ALL\_TIERS** | Default. Tier 1, Tier 2, and Real-Time products |
#### Level 2 tiers
| Value | Description |
| -------------- | ----------------------------------- |
| **TIER\_1** | Tier 1 products |
| **ALL\_TIERS** | Default. Tier 1 and Tier 2 products |
## Processing Options
| Parameter | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| upsampling | [Same as Sentinel-2.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
| downsampling | [Same as Sentinel-2.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
## Available Bands and Data
### Landsat 7 ETM+ Level 1 Bands
| Name | Description | Resolution |
| -------------------------- | --------------------------------- | ---------- |
| B01 | Blue (450–520 nm) | 30 m |
| B02 | Green (520–600 nm) | 30 m |
| B03 | Red (630–690 nm) | 30 m |
| B04 | Near Infrared (770–900 nm) | 30 m |
| B05 | SWIR 1 (1550–1750 nm) | 30 m |
| B06\_VCID\_1, B06\_VCID\_2 | Thermal Infrared (10400–12500 nm) | 30 m \[1] |
| B07 | SWIR 2 (2090–2350 nm) | 30 m |
| B08 | Panchromatic (520–900 nm) | 15 m |
| BQA | Quality Assessment band | 30 m |
| QA\_RADSAT | Radiometric Saturation QA Band | 30 m |
| VAA | View Azimuth Angle | 30 m |
| VZA | View Zenith Angle | 30 m |
| SAA | Sun Azimuth Angle | 30 m |
| SZA | Sun Zenith Angle | 30 m |
| dataMask | Data/no-data mask | N/A \[2] |
### Landsat 7 ETM+ Level 2 Bands
| Name | Description | Resolution |
| ------------ | ------------------------------- | ---------- |
| B01–B05, B07 | Surface reflectance bands | 30 m |
| B06 | Surface temperature | 30 m \[1] |
| BQA | Quality Assessment band | 30 m |
| QA\_RADSAT | Radiometric Saturation QA Band | 30 m |
| ST\_QA | Surface temperature uncertainty | 30 m |
| ST\_TRAD | Thermal radiance | 30 m |
| ST\_URAD | Upwelled radiance | 30 m |
| ST\_DRAD | Downwelled radiance | 30 m |
| ST\_ATRAN | Atmospheric transmittance | 30 m |
| ST\_EMIS | Emissivity | 30 m |
| ST\_EMSD | Emissivity standard deviation | 30 m |
| ST\_CDIST | Pixel distance to cloud | 30 m |
| dataMask | Data/no-data mask | N/A \[2] |
\[1]: Thermal band is acquired at 60 m and resampled to 30 m.
\[2]: Calculated per output pixel.
## Units
### Landsat 7 ETM+ Level 1 Units
| Band type | Physical Quantity | Units Value | Source Format |
| ------------- | -------------------------- | ----------------------- | ------------- |
| Optical bands | Reflectance | REFLECTANCE | UINT8 |
| Thermal bands | Brightness temperature (K) | BRIGHTNESS\_TEMPERATURE | UINT8 |
| QA bands | Quality flags | DN | UINT16 |
| Angles | Degrees | DEGREES | INT16 |
| dataMask | Data mask | DN | N/A |
### Landsat 7 ETM+ Level 2 Units
| Band type | Physical Quantity | Units Value | Source Format |
| ---------------------- | ----------------------- | ------------------------ | ------------- |
| Optical bands | Surface reflectance | REFLECTANCE | UINT16 |
| Thermal band | Surface temperature (K) | SURFACE\_TEMPERATURE | UINT16 |
| QA and auxiliary bands | Various | DN / FRACTION / RADIANCE | INT16 |
## Scenes Object
[`scenes` object](https://docs.planet.com/develop/evalscripts/functions.md#scenes) stores metadata. An example of metadata available in `scenes` object for Landsat ETM L1 and L2 when mosaicking is `ORBIT`:
| Property name | Value |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| dateFrom | `'2020-07-30T00:00:00Z'` |
| dateTo | `'2020-07-30T23:59:59Z'` |
| tiles\[i].landsatEtmProductId | `'LE07_L1TP_119019_20200730_20200909_02_T1'` |
| tiles\[i].date | `'2020-07-30T01:52:34.528Z'` |
| tiles\[i].shId | `3097841` |
| tiles\[i].cloudCoverage | `98.35` |
| tiles\[i].dataPath | `'https://usgs-landsat.s3.amazonaws.com/collection02/level-1/standard/etm/2020/119/019/LE07_L1TP_119019_20200730_20200909_02_T1'` |
Properties of a `scenes` object can differ depending on the selected mosaicking and in which evalscript function the object is accessed. [Working with metadata in evalscript](https://docs.planet.com/develop/evalscripts.md#working-with-metadata-in-evalscripts) user guide explains all details and provide examples.
## Catalog API Capabilities
To access Landsat 7 ETM+ metadata, send a search request to the [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md).
### Collection identifiers
* `landsat-etm-l1`
* `landsat-etm-l2`
### Filter extension
* `eo:cloud_cover`
* `landsat:scene_id`
* `landsat:collection_category`
### Distinct extension
* `date`
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-7-etm/examples/)
# Landsat 7 ETM+ L1 & L2 Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## True Color
* L1
* L2
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
},
"type": "landsat-etm-l1"
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/jpeg"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
},
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, resolution (EPSG 32633)
* L1
* L2
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
284281.024812,
4637026.521832,
301547.842435,
4652124.141629
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
}
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
},
"type": "landsat-etm-l1"
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/jpeg"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
},
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"resx": 100,
"resy": 100
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, multi-band GeoTIFF
* L1
* L2
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
284281.024812,
4637026.521832,
301547.842435,
4652124.141629
],
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
}
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
},
"type": "landsat-etm-l1"
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
},
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}
'
```
## True Color, mosaicking with leastRecent
* L1
* L2
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
},
"type": "landsat-etm-l1"
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "default",
"format": {
"type": "image/jpeg"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3,
},
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B01, 2.5 * sample.B02, 2.5 * sample.B03]
}
'
```
## True Color and metadata (multi-part response GeoTIFF and json)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 3
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].B03, 2.5 * samples[0].B02, 2.5 * samples[0].B01]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B01", "B02", "B03"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 3
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].B03, 2.5 * samples[0].B02, 2.5 * samples[0].B01]
}
'
```
## True Color multi-part response (different formats and SampleType)
* L1
* L2
```
curl -X POST https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
},
"type": "landsat-etm-l1"
}
]
},
"output": {
"width": 512,
"height": 512,
"responses": [
{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.B03 * 255, sample.B02 * 255, sample.B01 * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.B03 * 65535, sample.B02 * 65535, sample.B01 * 65535],
// Reflectance values
true_color_32float: [sample.B03, sample.B02, sample.B01],
}
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.B03, 2.5 * sample.B02, 2.5 * sample.B01],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.B03 * 255, sample.B02 * 255, sample.B01 * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.B03 * 65535, sample.B02 * 65535, sample.B01 * 65535],
// Reflectance values
true_color_32float: [sample.B03, sample.B02, sample.B01],
}
}
'
```
## NDVI as jpeg image with bounds given as polygon
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B03", "B04"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B03", "B04"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
## Exact NDVI values using a floating point GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B03", "B04"]
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
return [ ndvi ]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B03", "B04"]
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
return [ ndvi ]
}'
```
## NDVI image and value (multi-part response png and GeoTIFF)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B05"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO
}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
if (ndvi < -0.5) image = [0.05, 0.05, 0.05]
else if (ndvi < -0.2) image = [0.75, 0.75, 0.75]
else if (ndvi < -0.1) image = [0.86, 0.86, 0.86]
else if (ndvi < 0) image = [0.92, 0.92, 0.92]
else if (ndvi < 0.025) image = [1, 0.98, 0.8]
else if (ndvi < 0.05) image = [0.93, 0.91, 0.71]
else if (ndvi < 0.075) image = [0.87, 0.85, 0.61]
else if (ndvi < 0.1) image = [0.8, 0.78, 0.51]
else if (ndvi < 0.125) image = [0.74, 0.72, 0.42]
else if (ndvi < 0.15) image = [0.69, 0.76, 0.38]
else if (ndvi < 0.175) image = [0.64, 0.8, 0.35]
else if (ndvi < 0.2) image = [0.57, 0.75, 0.32]
else if (ndvi < 0.25) image = [0.5, 0.7, 0.28]
else if (ndvi < 0.3) image = [0.44, 0.64, 0.25]
else if (ndvi < 0.35) image = [0.38, 0.59, 0.21]
else if (ndvi < 0.4) image = [0.31, 0.54, 0.18]
else if (ndvi < 0.45) image = [0.25, 0.49, 0.14]
else if (ndvi < 0.5) image = [0.19, 0.43, 0.11]
else if (ndvi < 0.55) image = [0.13, 0.38, 0.07]
else if (ndvi < 0.6) image = [0.06, 0.33, 0.04]
else image = [0, 0.27, 0]
return {
default: [ndvi],
ndvi_image: image
}
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B03", "B04"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO
}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B04 - sample.B03) / (sample.B04 + sample.B03)
if (ndvi < -0.5) image = [0.05, 0.05, 0.05]
else if (ndvi < -0.2) image = [0.75, 0.75, 0.75]
else if (ndvi < -0.1) image = [0.86, 0.86, 0.86]
else if (ndvi < 0) image = [0.92, 0.92, 0.92]
else if (ndvi < 0.025) image = [1, 0.98, 0.8]
else if (ndvi < 0.05) image = [0.93, 0.91, 0.71]
else if (ndvi < 0.075) image = [0.87, 0.85, 0.61]
else if (ndvi < 0.1) image = [0.8, 0.78, 0.51]
else if (ndvi < 0.125) image = [0.74, 0.72, 0.42]
else if (ndvi < 0.15) image = [0.69, 0.76, 0.38]
else if (ndvi < 0.175) image = [0.64, 0.8, 0.35]
else if (ndvi < 0.2) image = [0.57, 0.75, 0.32]
else if (ndvi < 0.25) image = [0.5, 0.7, 0.28]
else if (ndvi < 0.3) image = [0.44, 0.64, 0.25]
else if (ndvi < 0.35) image = [0.38, 0.59, 0.21]
else if (ndvi < 0.4) image = [0.31, 0.54, 0.18]
else if (ndvi < 0.45) image = [0.25, 0.49, 0.14]
else if (ndvi < 0.5) image = [0.19, 0.43, 0.11]
else if (ndvi < 0.55) image = [0.13, 0.38, 0.07]
else if (ndvi < 0.6) image = [0.06, 0.33, 0.04]
else image = [0, 0.27, 0]
return {
default: [ndvi],
ndvi_image: image
}
}
'
```
## All bands as GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06_VCID_1", "B06_VCID_2", "B07", "B08", "BQA"]
}],
output: {
id: "default",
bands: 12,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands B01-B09, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.B01, 10000 * sample.B02, 10000 * sample.B03, 10000 * sample.B04, 10000 * sample.B05, sample.B06_VCID_1, sample.B06_VCID_2, 10000 * sample.B07, 10000 * sample.B08, sample.BQA]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "BQA"]
}],
output: {
id: "default",
bands: 9,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands B01-B09, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.B01, 10000 * sample.B02, 10000 * sample.B03, 10000 * sample.B04, 10000 * sample.B05, sample.B06, 10000 * sample.B07, sample.BQA]
}
'
```
## Thermal Band as jpeg image with bounds given as bounding box
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = 200
let maxVal = 375
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"B06_VCID_1",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.B06_VCID_1
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = 200
let maxVal = 375
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"B06",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.B06
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
## Extract Thermal band Kelvin values using a FLOAT32 GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B06_VCID_1"
]
}],
output: {
bands: 1,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.B06_VCID_1]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-etm-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B06"
]
}],
output: {
bands: 1,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.B06]
}
'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9/)
# Landsat 8-9 L1 & L2
Landsat 8–9 collections include both Landsat 8 and the most recently launched Landsat 9 satellites (provided by NASA/USGS), both carrying the Operational Land Imager (OLI/OLI-2) and the Thermal Infrared Sensor (TIRS/TIRS-2) instruments, providing seasonal coverage of the global landmass.
Landsat 8–9 Level 1 includes radiometrically calibrated and orthorectified data with 9 optical and 2 thermal bands. Landsat 8–9 Level 2 provides global surface reflectance and surface temperature science products. Level 2 science products are generated from Collection 2 Level-1 inputs that meet the `<76` degrees Solar Zenith Angle constraint and include the required auxiliary data inputs to generate a scientifically viable product.
## Basic Facts
| Property | Landsat 8–9 Level 1 | Landsat 8–9 Level 2 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data type** | Top of Atmosphere (TOA) Reflectance and Brightness Temperature | Surface Reflectance and Surface Temperature |
| **Spatial resolution** | 15 m for the panchromatic band and 30 m for the rest (the thermal bands is resampled from 100 m) | 30 m (the thermal bands is resampled from 100 m) |
| **Sensor** | Operational Land Imager (OLI for Landsat 8 and OLI-2 for Landsat 9) with 9 spectral bands and Thermal Infrared Sensor (TIRS for Landsat 8 and TIRS-2 for Landsat 9) with 2 thermal bands | Operational Land Imager (OLI for Landsat 8 and OLI-2 for Landsat 9) with 9 spectral bands and Thermal Infrared Sensor (TIRS for Landsat 8 and TIRS-2 for Landsat 9) with 2 thermal bands |
| **Revisit time** | 8 days (16 days for each of the two sensors) | 8 days (16 days for each of the two sensors) |
| **Spatial coverage** | Whole globe | Whole globe |
| **Data availability** | Landsat 8 since March 2013, Landsat 9 since November 2021. | Landsat 8 since February 2013, Landsat 9 since January 2022. |
| **Common usage/purpose** | Vegetation monitoring, land use, land cover maps and monitoring of changes. | Vegetation monitoring, land use, land cover maps and monitoring of changes. |
## Accessing Data
To access data you need to send a POST request to our `process` API. The requested data will be returned as the response to your request. Each POST request can be tailored to get you exactly the data you require. To do this requires setting various parameters which depend on the collection you are querying.
For an overview of all API parameters see the [API Reference](https://docs.planet.com/develop/apis.md).
### Endpoint Locations
| Service | Notes |
| ------------------------------------- | ----------------------------------- |
| services-uswest2.sentinel-hub.com/api | Global coverage since February 2013 |
### Data type identifiers
Use the following values for `input.data.type`:
| Dataset | Identifier |
| ------------------- | ---------------------------------- |
| Landsat 8–9 Level 1 | `landsat-ot-l1` (previously LOTL1) |
| Landsat 8–9 Level 2 | `landsat-ot-l2` (previously LOTL2) |
## Filtering Options
This chapter explains the `input.data.dataFilter` object.
### `mosaickingOrder`
| Value | Description | Notes |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **mostRecent** | (default) The pixel will be selected from the most recently acquired tile | |
| **leastRecent** | similar to **mostRecent** but in reverse order | |
| **leastCC** | The pixel is selected from the tile with the lowest cloud coverage | This information is estimated per tile (each covering about 31,100 sq. km) so local cloud coverage may differ |
### `maxCloudCoverage`
Sets the upper limit for cloud coverage in percent based on the precomputed cloud coverage estimate for each tile as present in the tile metadata. Satellite data will therefore not be retrieved for tiles with a higher cloud coverage estimate. For example, by setting the value to `20`, only tiles with at most 20% cloud coverage will be used. Note that this parameter is set per tile and might not be directly applicable to the chosen area of interest.
### `tiers`
#### Level 1 tiers
| Value | Description |
| -------------------- | ------------------------------------------------------------------ |
| **TIER\_1** | selects Tier 1 products |
| **TIER\_1\_AND\_RT** | selects Tier 1 and Real-Time products (only for Landsat 8) |
| **ALL\_TIERS** | selected by default. selects Real-Time, Tier 1 and Tier 2 products |
#### Level 2 tiers
| Value | Description |
| -------------- | ------------------------------------------------------- |
| **TIER\_1** | selects Tier 1 products |
| **ALL\_TIERS** | selected by default. selects Tier 1 and Tier 2 products |
## Processing Options
| Parameter | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| upsampling | [The same as for S2L1C.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
| downsampling | [The same as for S2L1C.](https://docs.planet.com/data/public-data/copernicus/sentinel-2.md#processing-options) |
## Available Bands and Data
Below are the bands for each data level.
### Landsat 8–9 Level 1 Bands
| Name | Description | Resolution |
| ---------- | --------------------------------------------------------------------------------------------------- | ---------- |
| B01 | Ultra Blue (443 nm) | 30 m |
| B02 | Blue (482 nm) | 30 m |
| B03 | Green (561.5 nm) | 30 m |
| B04 | Red (654.5 nm) | 30 m |
| B05 | Near Infrared (NIR) (865 nm) | 30 m |
| B06 | Shortwave Infrared (SWIR) 1 (1608.5 nm) | 30 m |
| B07 | Shortwave Infrared (SWIR) 2 (2200.5 nm) | 30 m |
| B08 | Panchromatic (589.5 nm) | 15 m |
| B09 | Cirrus (1373.5 nm) | 30 m |
| B10 | Thermal Infrared (TIRS) 1(10895 nm) | 30 m\[1] |
| B11 | Thermal Infrared (TIRS) 2 (12005 nm) | 30 m\[1] |
| BQA | Quality Assessment band (QA) | 30 m |
| QA\_RADSAT | Radiometric Saturation and Terrain Occlusion QA Band | 30 m |
| VAA | View (sensor) Azimuth Angle | 30 m |
| VZA | View (sensor) Zenith Angle | 30 m |
| SAA | Sun Azimuth Angle | 30 m |
| SZA | Sun Zenith Angle | 30 m |
| dataMask | The mask of data/no data pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)). | N/A \[2] |
\[1]: Thermal bands are acquired at 100 meter resolution, but are resampled to 30 meter in delivered data product.
\[2]: dataMask has no source resolution as it is calculated for each output pixel.
## Landsat 8–9 Level 2 Bands
| Name | Description | Resolution |
| --------------- | --------------------------------------------------------------------------------------------------- | ---------- |
| B01 | Ultra Blue (443 nm) | 30 m |
| B02 | Blue (482 nm) | 30 m |
| B03 | Green (561.5 nm) | 30 m |
| B04 | Red (654.5 nm) | 30 m |
| B05 | Near Infrared (NIR) (865 nm) | 30 m |
| B06 | Shortwave Infrared (SWIR) 1 (1608.5 nm) | 30 m |
| B07 | Shortwave Infrared (SWIR) 2 (2200.5 nm) | 30 m |
| B10 | Thermal Infrared (TIRS) 1(10895 nm) | 30 m\[1] |
| BQA | Quality Assessment band (QA) | 30 m |
| QA\_RADSAT | Radiometric Saturation and Terrain Occlusion QA Band | 30 m |
| SR\_QA\_AEROSOL | SR Aerosol QA | 30 m |
| ST\_QA | Surface Temperature Uncertainty | 30 m |
| ST\_TRAD | Level-1 thermal band converted to thermal surface radiance | 30 m |
| ST\_URAD | Upwelled Radiance | 30 m |
| ST\_DRAD | Downwelled Radiance | 30 m |
| ST\_ATRAN | Atmospheric Transmittance | 30 m |
| ST\_EMIS | Emissivity of Band 10 estimated from ASTER GED | 30 m |
| ST\_EMSD | Emissivity standard deviation | 30 m |
| ST\_CDIST | Pixel distance to cloud | 30 m |
| dataMask | The mask of data/no data pixels ([more](https://docs.planet.com/develop/evalscripts.md#data-mask)). | N/A \[2] |
## Units
Both unit tables preserved exactly.
### Landsat 8–9 Level 1 Units
| Band | Physical Quantity (units) | Units Value | Source Format | Typical Range | Notes |
| ------------------------------------- | ---------------------------------------------------- | ---------------------------- | ------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
| Optical bands
B01 - B09 | Reflectance (unitless) | REFLECTANCE \[1] | UINT16 | 0 - 0.4 | Higher values in infrared bands. Reflectance values can easily be above 1. |
| Thermal infrared bands
B10 - B11 | Brightness temperature (kelvin) | BRIGHTNESS\_TEMPERATURE \[2] | UINT16 | 250 - 320 | Brightness temperature of roughly -20 to +50 C. Can reach outside this range in extreme environments. |
| BQA | Pixel quality assessment (unitless) | DN | UINT16 | bit-packed combination | The values can be obtained using the utility function *decodeL8C2Qa*. |
| QA\_RADSAT | Radiometric saturation quality assessment (unitless) | DN | UINT16 | bit-packed combination | |
| VAA | Angle (degrees) | DEGREES | INT16 | | |
| VZA | Angle (degrees) | DEGREES | INT16 | | |
| SAA | Angle (degrees) | DEGREES | INT16 | | |
| SZA | Angle (degrees) | DEGREES | INT16 | | |
| dataMask | N/A | DN | N/A | 0 - no data
1 - data | |
### Landsat 8–9 Level 2 Units
| Band | Physical Quantity (units) | Units Value | Source Format | Typical Range | Notes |
| ------------------------------ | ---------------------------------------------------- | -------------------- | ------------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
| Optical bands
B01 - B07 | Surface reflectance (unitless) | REFLECTANCE | UINT16 | 0 - 0.4 | Higher values in infrared bands. Reflectance values can easily be above 1. |
| Thermal infrared band
B10 | Surface temperature (kelvin) | SURFACE\_TEMPERATURE | UINT16 | 250 - 320 | Surface temperature of roughly -20 to +50 C. Can reach outside this range in extreme environments. |
| BQA | Pixel quality assessment (unitless) | DN | UINT16 | bit-packed combination | |
| QA\_RADSAT | Radiometric saturation quality assessment (unitless) | DN | UINT16 | bit-packed combination | |
| SR\_QA\_AEROSOL | Surface reflectance quality assessment (unitless) | DN | UINT8 | bit-packed combination | |
| ST\_QA | Surface temperature uncertainty (Kelvin) | KELVIN | INT16 | | |
| ST\_TRAD | Radiance (W / m^2 / sr / μm) | RADIANCE | INT16 | | |
| ST\_URAD | Radiance (W / m^2 / sr / μm) | RADIANCE | INT16 | | |
| ST\_DRAD | Radiance (W / m^2 / sr / μm) | RADIANCE | INT16 | | |
| ST\_ATRAN | Atmospheric transmittance (unitless) | FRACTION | INT16 | 0 - 1 | |
| ST\_EMIS | Emissivity (unitless) | FRACTION | INT16 | 0 - 1 | |
| ST\_EMSD | Emissivity standard deviation (unitless) | FRACTION | INT16 | 0 - 1 | |
| ST\_CDIST | Pixel distance (kilometers) | KILOMETERS | INT16 | | |
| dataMask | N/A | DN | N/A | 0 - no data
1 - data | |
## Scenes Object
`scenes` object stores metadata. An example of metadata available in scenes object for Landsat 8-9 L1 when mosaicking is `ORBIT`:
| Property name | Value |
| --------------------------------- | --------------------------------------------- |
| dateFrom | `'2018-12-25T00:00:00Z'` |
| dateTo | `'2018-12-25T23:59:59Z'` |
| tiles\[i].landsatOliTirsProductId | `'LC08_L1TP_190027_20181225_20200829_02_T1'` |
| tiles\[i].date | `'2018-12-25T09:45:29.121783Z'` |
| tiles\[i].shId | `3097841` |
| tiles\[i].cloudCoverage | `98.35` |
| tiles\[i].dataPath | `'https://usgs-landsat.s3.amazonaws.com/...'` |
## Catalog API Capabilities
To access Landsat 8-9 product metadata you need to send search request to our [Catalog API](https://docs.planet.com/develop/apis/catalog/reference.md). The requested metadata will be returned as JSON formatted response to your request.
### Collection identifiers
* `landsat-ot-l1`
* `landsat-ot-l2`
### Filter extension
* `eo:cloud_cover`
* `landsat:scene_id`
* `landsat:collection_category`
### Distinct extension
* `date`
---
Copy for LLM[View as Markdown](https://docs.planet.com/data/public-data/usgs-nasa/landsat-8-9/examples/)
# Landsat 8-9 L1 & L2 Examples
The following examples are CURL requests and can be run from the command line or terminal. In addition, you can copy and paste these examples into [Request Builder](https://insights.planet.com/analyze/requests-builder/). You can translate the requests into other programming languages in the Request Builder app.
To request data using any of the request below, you will need to replace the string `` with your access token. Your access token will look something like this:
```
ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg
```
and can be obtained as described in the [Authentication chapter](https://docs.planet.com/develop/authentication.md).
## True Color
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
## True Color Pansharpened
* L1
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B02",
"B03",
"B04",
"B08",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
let minVal = 0.0
let maxVal = 0.4
let viz = new HighlightCompressVisualizer(minVal, maxVal)
function evaluatePixel(samples) {
let sudoPanW = (samples.B04 + samples.B03 + samples.B02 * 0.4) / 2.4
let ratioW = samples.B08 / sudoPanW
let val = [samples.B04 * ratioW, samples.B03 * ratioW, samples.B02 * ratioW]
val = viz.processList(val)
val.push(samples.dataMask)
return val
}
'
```
## True Color, resolution (EPSG 32633)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"resx": 100,
"resy": 100
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
},
"bbox": [
408553.58,
5078145.48,
466081.02,
5126576.61
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"resx": 100,
"resy": 100
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
## True Color, multi-band GeoTIff
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
## True Color, mosaicking with leastRecent
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"mosaickingOrder": "leastRecent"
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
'
```
## True color and metadata (multi-part response GeoTIFF and json)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 3
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].B04, 2.5 * samples[0].B03, 2.5 * samples[0].B02]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "userdata",
"format": {
"type": "application/json"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
mosaicking: Mosaicking.ORBIT,
output: {
id: "default",
bands: 3
}
}
}
function updateOutputMetadata(scenes, inputMetadata, outputMetadata) {
outputMetadata.userData = {
"scenes": scenes.orbits
}
}
function evaluatePixel(samples) {
return [2.5 * samples[0].B04, 2.5 * samples[0].B03, 2.5 * samples[0].B02]
}
'
```
## True color multi-part response (different formats and SampleType)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B03", "B02"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.B04 * 255, sample.B03 * 255, sample.B02 * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.B04 * 65535, sample.B03 * 65535, sample.B02 * 65535],
// Reflectance values
true_color_32float: [sample.B04, sample.B03, sample.B02],
}
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "true_color",
"format": {
"type": "image/jpeg"
}
},
{
"identifier": "true_color_8bit",
"format": {
"type": "image/png"
}
},
{
"identifier": "true_color_16bit",
"format": {
"type": "image/tiff"
}
},
{
"identifier": "true_color_32float",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B03", "B02"],
units: "REFLECTANCE" // default units
}],
output: [{
id: "true_color",
bands: 3,
sampleType: "AUTO" // default - scales the output values from input values [0,1] to [0,255].
},
{
id: "true_color_8bit",
bands: 3,
sampleType: "UINT8"
},
{
id: "true_color_16bit",
bands: 3,
sampleType: "UINT16" //floating point values are automatically rounded to the nearest integer by the service.
},
{
id: "true_color_32float",
bands: 3,
sampleType: "FLOAT32"
}
]
}
}
function evaluatePixel(sample) {
return {
// output band values are scaled from [0,1] to [0,255]. Multiply by 2.5 to increase brightness
true_color: [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02],
// Multiply input reflectance values by 255 to stretch them to [0, 255] unsigned 8 bit range.
true_color_8bit: [sample.B04 * 255, sample.B03 * 255, sample.B02 * 255],
// Multiply input reflectance values by 65535 to stretch them to [0, 65535] unsigned 16 bit range.
true_color_16bit: [sample.B04 * 65535, sample.B03 * 65535, sample.B02 * 65535],
// Reflectance values
true_color_32float: [sample.B04, sample.B03, sample.B02],
}
}
'
```
## NDVI as jpeg image with bounds given as polygon
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B04", "B05"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/jpeg",
"quality": 80
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands:["B04", "B05"],
}],
output: {
id: "default",
bands: 3,
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
if (ndvi<-0.5) return [0.05,0.05,0.05]
else if (ndvi<-0.2) return [0.75,0.75,0.75]
else if (ndvi<-0.1) return [0.86,0.86,0.86]
else if (ndvi<0) return [0.92,0.92,0.92]
else if (ndvi<0.025) return [1,0.98,0.8]
else if (ndvi<0.05) return [0.93,0.91,0.71]
else if (ndvi<0.075) return [0.87,0.85,0.61]
else if (ndvi<0.1) return [0.8,0.78,0.51]
else if (ndvi<0.125) return [0.74,0.72,0.42]
else if (ndvi<0.15) return [0.69,0.76,0.38]
else if (ndvi<0.175) return [0.64,0.8,0.35]
else if (ndvi<0.2) return [0.57,0.75,0.32]
else if (ndvi<0.25) return [0.5,0.7,0.28]
else if (ndvi<0.3) return [0.44,0.64,0.25]
else if (ndvi<0.35) return [0.38,0.59,0.21]
else if (ndvi<0.4) return [0.31,0.54,0.18]
else if (ndvi<0.45) return [0.25,0.49,0.14]
else if (ndvi<0.5) return [0.19,0.43,0.11]
else if (ndvi<0.55) return [0.13,0.38,0.07]
else if (ndvi<0.6) return [0.06,0.33,0.04]
else return [0,0.27,0]
}'
```
## Exact NDVI values using a floating point GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B05"]
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
return [ ndvi ]
}'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return{
input: [{
bands: ["B04", "B05"]
}],
output: {
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
}
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
return [ ndvi ]
}'
```
## NDVI image and value (multi-part response png and GeoTIFF)
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B05"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO
}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
if (ndvi < -0.5) image = [0.05, 0.05, 0.05]
else if (ndvi < -0.2) image = [0.75, 0.75, 0.75]
else if (ndvi < -0.1) image = [0.86, 0.86, 0.86]
else if (ndvi < 0) image = [0.92, 0.92, 0.92]
else if (ndvi < 0.025) image = [1, 0.98, 0.8]
else if (ndvi < 0.05) image = [0.93, 0.91, 0.71]
else if (ndvi < 0.075) image = [0.87, 0.85, 0.61]
else if (ndvi < 0.1) image = [0.8, 0.78, 0.51]
else if (ndvi < 0.125) image = [0.74, 0.72, 0.42]
else if (ndvi < 0.15) image = [0.69, 0.76, 0.38]
else if (ndvi < 0.175) image = [0.64, 0.8, 0.35]
else if (ndvi < 0.2) image = [0.57, 0.75, 0.32]
else if (ndvi < 0.25) image = [0.5, 0.7, 0.28]
else if (ndvi < 0.3) image = [0.44, 0.64, 0.25]
else if (ndvi < 0.35) image = [0.38, 0.59, 0.21]
else if (ndvi < 0.4) image = [0.31, 0.54, 0.18]
else if (ndvi < 0.45) image = [0.25, 0.49, 0.14]
else if (ndvi < 0.5) image = [0.19, 0.43, 0.11]
else if (ndvi < 0.55) image = [0.13, 0.38, 0.07]
else if (ndvi < 0.6) image = [0.06, 0.33, 0.04]
else image = [0, 0.27, 0]
return {
default: [ndvi],
ndvi_image: image
}
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-H 'Accept: application/tar' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "ndvi_image",
"format": {
"type": "image/png"
}
},
{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}
]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B05"],
}],
output: [{
id: "default",
bands: 1,
sampleType: SampleType.FLOAT32
},
{
id: "ndvi_image",
bands: 3,
sampleType: SampleType.AUTO
}
]
}
}
function evaluatePixel(sample) {
let ndvi = (sample.B05 - sample.B04) / (sample.B05 + sample.B04)
if (ndvi < -0.5) image = [0.05, 0.05, 0.05]
else if (ndvi < -0.2) image = [0.75, 0.75, 0.75]
else if (ndvi < -0.1) image = [0.86, 0.86, 0.86]
else if (ndvi < 0) image = [0.92, 0.92, 0.92]
else if (ndvi < 0.025) image = [1, 0.98, 0.8]
else if (ndvi < 0.05) image = [0.93, 0.91, 0.71]
else if (ndvi < 0.075) image = [0.87, 0.85, 0.61]
else if (ndvi < 0.1) image = [0.8, 0.78, 0.51]
else if (ndvi < 0.125) image = [0.74, 0.72, 0.42]
else if (ndvi < 0.15) image = [0.69, 0.76, 0.38]
else if (ndvi < 0.175) image = [0.64, 0.8, 0.35]
else if (ndvi < 0.2) image = [0.57, 0.75, 0.32]
else if (ndvi < 0.25) image = [0.5, 0.7, 0.28]
else if (ndvi < 0.3) image = [0.44, 0.64, 0.25]
else if (ndvi < 0.35) image = [0.38, 0.59, 0.21]
else if (ndvi < 0.4) image = [0.31, 0.54, 0.18]
else if (ndvi < 0.45) image = [0.25, 0.49, 0.14]
else if (ndvi < 0.5) image = [0.19, 0.43, 0.11]
else if (ndvi < 0.55) image = [0.13, 0.38, 0.07]
else if (ndvi < 0.6) image = [0.06, 0.33, 0.04]
else image = [0, 0.27, 0]
return {
default: [ndvi],
ndvi_image: image
}
}
'
```
## All Landsat 8-9 L1 & L2 bands as GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08", "B09", "B10", "B11", "BQA"]
}],
output: {
id: "default",
bands: 12,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands B01-B09, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.B01, 10000 * sample.B02, 10000 * sample.B03, 10000 * sample.B04, 10000 * sample.B05, 10000 * sample.B06, 10000 * sample.B07, 10000 * sample.B08, 10000 * sample.B09, sample.B10, sample.B11, sample.BQA]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.480661,
41.965872
],
[
12.523909,
41.96817
],
[
12.553084,
41.931401
],
[
12.525968,
41.906365
],
[
12.491645,
41.894355
],
[
12.449084,
41.896911
],
[
12.433295,
41.926292
],
[
12.442219,
41.950043
],
[
12.480661,
41.965872
]
]
]
}
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: ["B01", "B02", "B03", "B04", "B05", "B06", "B07", "B10", "BQA"]
}],
output: {
id: "default",
bands: 9,
sampleType: SampleType.UINT16 //floating point values are automatically rounded to the nearest integer by the service.
}
}
}
function evaluatePixel(sample) {
// For optical bands B01-B09, return reflectance multiplied by 10000 as integers to save processing units. To obtain reflectance values, simply divide the resulting pixel values by 10000.
return [10000 * sample.B01, 10000 * sample.B02, 10000 * sample.B03, 10000 * sample.B04, 10000 * sample.B05, 10000 * sample.B06, 10000 * sample.B07, sample.B10, sample.BQA]
}
'
```
## Thermal Band as jpeg image with bounds given as bounding box
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = 200
let maxVal = 375
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"B10",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.B10
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/png"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
let minVal = 200
let maxVal = 375
let viz = ColorGradientVisualizer.createBlueRed(minVal, maxVal)
function setup() {
return {
input: [{
bands: [
"B10",
"dataMask"
]
}],
output: {
bands: 4
}
}
}
function evaluatePixel(samples) {
let val = samples.B10
val = viz.process(val)
val.push(samples.dataMask)
return val
}
'
```
## Extract Thermal band Kelvin values using a FLOAT32 GeoTIFF
* L1
* L2
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l1",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B10"
]
}],
output: {
bands: 1,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.B10]
}
'
```
```
curl -X POST \
https://services-uswest2.sentinel-hub.com/process/v1 \
-H 'Authorization: Bearer ' \
-F 'request={
"input": {
"bounds": {
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
},
"bbox": [
12.401213,
41.855754,
12.609214,
41.996243
]
},
"data": [{
"type": "landsat-ot-l2",
"dataFilter": {
"timeRange": {
"from": "2020-07-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
}
}
}]
},
"output": {
"width": 512,
"height": 512,
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
}
}
' \
-F 'evalscript=//VERSION=3
function setup() {
return {
input: [{
bands: [
"B10"
]
}],
output: {
bands: 1,
sampleType: "FLOAT32"
}
}
}
function evaluatePixel(samples) {
return [samples.B10]
}
'
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/)
# Developer Overview
## Authentication
Planet APIs use different authentication methods depending on the domain (`api.planet.com` or `sentinel-hub.com`). See the [authentication section](https://docs.planet.com/develop/authentication.md) for details.
## Errors
Understand common HTTP and API-specific errors you may encounter when using Planet APIs — and how to resolve them. See the [errors section](https://docs.planet.com/develop/errors.md) for details.
## Rate Limiting
Learn how Planet enforces rate limits, and how to manage 429 errors using strategies like exponential backoff. See the [rate limiting section](https://docs.planet.com/develop/rate-limiting.md) for details.
## SDKs and Developer Resources
Explore official SDKs, CLI tools, and open-source libraries for working with Planet and Sentinel data. See the [SDKs section](https://docs.planet.com/develop/sdks.md) for guides, examples, and frameworks like `eo-learn` and `eo-grow`.
## Evalscripts
Write custom JavaScript scripts to process and visualize satellite data, apply logic, and extract metadata using Planet's Evalscript engine.
### [Functions](https://docs.planet.com/develop/evalscripts/functions.md)
[Evalscript is a powerful tool for imagery visualization, multitemporal scripting, datafusion, scene filtering, and more.](https://docs.planet.com/develop/evalscripts/functions.md)
### [Utilities](https://docs.planet.com/develop/evalscripts/utilities.md)
[Explore the nonstandard javascript visualizers and helper functions, that can be used in your evalscript.](https://docs.planet.com/develop/evalscripts/utilities.md)
### [Examples](https://docs.planet.com/develop/evalscripts/examples.md)
[Explore examples of evalscripts using the Sentinel-2 L2A data collection.](https://docs.planet.com/develop/evalscripts/examples.md)
### [Data Fusion](https://docs.planet.com/develop/evalscripts/data-fusion.md)
[Combine multiple data sources — different collections, or the same collection at different dates — in a single evalscript request.](https://docs.planet.com/develop/evalscripts/data-fusion.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/)
# APIs
## Data Access and Management
[](https://docs.planet.com/develop/apis/data.md)
### [Data API](https://docs.planet.com/develop/apis/data.md)
[Search for Planet data programmatically based on your filters for areas, time, constellation, and more.](https://docs.planet.com/develop/apis/data.md)
[](https://docs.planet.com/develop/apis/orders.md)
### [Orders API](https://docs.planet.com/develop/apis/orders.md)
[Request Planet data to be downloaded, delivered to your cloud, or delivered to data collections.](https://docs.planet.com/develop/apis/orders.md)
[](https://docs.planet.com/develop/apis/subscriptions.md)
### [Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md)
[Subscribe to continuous cloud delivery of imagery and metadata that match your filter criteria.](https://docs.planet.com/develop/apis/subscriptions.md)
[](https://docs.planet.com/develop/apis/basemaps.md)
### [Basemaps API](https://docs.planet.com/develop/apis/basemaps.md)
[View and download Mosaics.](https://docs.planet.com/develop/apis/basemaps.md)
[](https://docs.planet.com/develop/apis/byoc.md)
### [Bring Your Own COG API](https://docs.planet.com/develop/apis/byoc.md)
[Use your own Cloud Optimized GeoTIFFs with Processing, Statistics, and OGC APIs.](https://docs.planet.com/develop/apis/byoc.md)
[](https://docs.planet.com/develop/apis/zarr.md)
### [Zarr Import API](https://docs.planet.com/develop/apis/zarr.md)
[Import Zarr format datasets for use across the platform.](https://docs.planet.com/develop/apis/zarr.md)
[](https://docs.planet.com/develop/apis/catalog.md)
### [Catalog API](https://docs.planet.com/develop/apis/catalog.md)
[Search and access metadata from imagery collections.](https://docs.planet.com/develop/apis/catalog.md)
[](https://docs.planet.com/develop/apis/features.md)
### [Features API](https://docs.planet.com/develop/apis/features.md)
[Save areas of interest to reference when making requests in other Planet APIs.](https://docs.planet.com/develop/apis/features.md)
[](https://docs.planet.com/develop/apis/destinations.md)
### [Destinations API](https://docs.planet.com/develop/apis/destinations.md)
[Save cloud storage credentials to reference when making requests in other Planet APIs.](https://docs.planet.com/develop/apis/destinations.md)
## Visualization APIs
[](https://docs.planet.com/develop/apis/tiles.md)
### [Tiles API](https://docs.planet.com/develop/apis/tiles.md)
[Visualize data through XYZ and WMTS tile services.](https://docs.planet.com/develop/apis/tiles.md)
[](https://docs.planet.com/platform/integrations/ogc.md)
### [OGC API](https://docs.planet.com/platform/integrations/ogc.md)
[Stream imagery into GIS tools using Open Geospatial Consortium (OGC) compliant services.](https://docs.planet.com/platform/integrations/ogc.md)
## Tasking
[](https://docs.planet.com/develop/apis/tasking.md)
### [Tasking API](https://docs.planet.com/develop/apis/tasking.md)
[Manage your satellite tasking orders.](https://docs.planet.com/develop/apis/tasking.md)
## Analysis
[](https://docs.planet.com/develop/apis/analytics.md)
### [Analytics API](https://docs.planet.com/develop/apis/analytics.md)
[Search and retrieve the outputs of Planet Analytics Feeds.](https://docs.planet.com/develop/apis/analytics.md)
[](https://docs.planet.com/develop/apis/processing.md)
### [Processing API](https://docs.planet.com/develop/apis/processing.md)
[Request imagery from Planet collections with custom scripts for raw data, composites, or indices.](https://docs.planet.com/develop/apis/processing.md)
[](https://docs.planet.com/develop/apis/async-processing.md)
### [Asynchronous Processing API](https://docs.planet.com/develop/apis/async-processing.md)
[Request larger datasets in one call and deliver results to storage.](https://docs.planet.com/develop/apis/async-processing.md)
[](https://docs.planet.com/develop/apis/batch-processing.md)
### [Batch Processing API](https://docs.planet.com/develop/apis/batch-processing.md)
[Request imagery for large areas or long time ranges and deliver results to storage.](https://docs.planet.com/develop/apis/batch-processing.md)
[](https://docs.planet.com/develop/apis/statistical.md)
### [Statistical API](https://docs.planet.com/develop/apis/statistical.md)
[Request statistics, histograms, and percentiles from imagery without downloads.](https://docs.planet.com/develop/apis/statistical.md)
[](https://docs.planet.com/develop/apis/batch-statistical.md)
### [Batch Statistical API](https://docs.planet.com/develop/apis/batch-statistical.md)
[Request statistics for large areas or long time ranges.](https://docs.planet.com/develop/apis/batch-statistical.md)
## Account Management
[](https://docs.planet.com/develop/apis/quota.md)
### [Quota Reservations API](https://docs.planet.com/develop/apis/quota.md)
[Create, estimate, and view area quota reservations for Planetary Variables, ARPS, and PlanetScope.](https://docs.planet.com/develop/apis/quota.md)
[](https://docs.planet.com/develop/apis/reports.md)
### [Reports API](https://docs.planet.com/develop/apis/reports.md)
[Download usage reports for your organization for downloads, tiles, tasking, and more.](https://docs.planet.com/develop/apis/reports.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/analytics/)
# Analytics Overview
Planet Analytics transforms satellite imagery into actionable intelligence using computer vision and machine learning. The Analytics API provides programmatic access to Analytic Feeds—automated detections and classifications of objects, geographic features, and changes over time.
The [Analytic Feeds Viewer](https://www.planet.com/feeds) showcases the Analytics API in action. See the [Viewer documentation](https://docs.planet.com/platform/get-started/analyze-data/analytic-feeds-viewer.md) to learn more.
## Analytics API components
### [Feeds and Subscriptions](https://docs.planet.com/develop/apis/analytics/list-feeds-subscriptions.md)
[Learn how to list feeds and subscriptions in the Analytics API.](https://docs.planet.com/develop/apis/analytics/list-feeds-subscriptions.md)
### [Querying Results](https://docs.planet.com/develop/apis/analytics/querying-results.md)
[Learn how to query subscription results in the Analytics API.](https://docs.planet.com/develop/apis/analytics/querying-results.md)
### [API Reference](https://docs.planet.com/develop/apis/analytics/reference.md)
[OpenAPI specification for REST API](https://docs.planet.com/develop/apis/analytics/reference.md)
## Feeds
Feeds define the analytic models and processing pipelines that transform Planet imagery into structured outputs. Each feed targets a specific use case with optimized performance and quality. For example, the Monthly [Road Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) Feed identifies roads in PlanetScope Mosaics and outputs raster segmentation masks.
## Analytic Subscriptions
**Note:** Analytic subscriptions are distinct from data subscriptions in the [Subscriptions API](https://docs.planet.com/develop/apis/subscriptions.md).
An analytic subscription defines your Area of Interest (AOI) and Time Interval of Interest (TOI) for a specific feed. For example: [Road Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) over San Francisco, California for 12 months. Use the Analytics API to list and manage your subscriptions.
## Results
When new imagery is published within your subscription's AOI, Planet's models automatically process it and add results to your subscription. For instance, a [Vessel Detection](https://docs.planet.com/data/analytic-feeds/vessel-detection.md) subscription generates new vessel detections each time daily imagery is published.
Each result links to the source imagery accompanying it, enabling visual verification and detailed analysis.
### Vector Results
Vector-based feeds output GeoJSON feature collections conforming to the OGC Web Feature Service specification. Each feature represents an individual detection (for example, a vessel) or change event (for example, new building construction).
### Raster Results
Raster-based feeds output GeoTIFF files referenced in GeoJSON feature collections. Each feature corresponds to a mosaic quad containing links to the accompanying imagery.
### Available Feeds, Imagery, and Output Formats
| Feed | Accompanying Imagery | Result Format |
| ---------------------------------------------------------------------------------------------------------- | -------------------- | ------------- |
| [Building Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) | Mosaic | Raster |
| [Road Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) | Mosaic | Raster |
| [Vessel Detection](https://docs.planet.com/data/analytic-feeds/vessel-detection.md) | Scene | Vector |
| [Aircraft Detection](https://docs.planet.com/data/analytic-feeds/aircraft-detection.md) | Scene | Vector |
| [Building Change Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) | Multiple Mosaics | Vector |
| [Road Change Detection](https://docs.planet.com/data/analytic-feeds/road-building-change-detection.md) | Multiple Mosaics | Vector |
## Web Map Tile Service
Stream source imagery and raster analytic results directly into ArcGIS, QGIS, or other GIS platforms using Planet's WMTS endpoint:
`https://api.planet.com/basemaps/v1/mosaics/wmts?api_key={api-key}`
Derivative raster outputs follow the naming convention `SIF--yyyy-mm-dd`:
| Item Title | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Global Monthly 2020 01 Mosaic | Planet's global visual mosaic product for January 2020 |
| sif-b442c53b-fc72-4bee-bab4-0b7aa318ccd9-2020-01-01 | Derivative raster output for feed ID "b442c53b-fc72-4bee-bab4-0b7aa318ccd9" (monthly building detection) |
Learn more in the [tile service reference documentation](https://docs.planet.com/develop/apis/tiles/wmts.md).
## OGC Features API
The Analytics API conforms to the OGC Features API specification, enabling WFS integration with GIS platforms. Query this endpoint to list available results:
`https://api.planet.com/analytics/`
## API Mechanics
### Pagination
Responses are paginated with a default limit of 250 items per page. Each response includes a `next` link to retrieve additional results. See this [Jupyter notebook](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/api_guides/analytics_api/quickstart/02_fetching_feed_results.ipynb) for a detailed pagination guide.
### Rate Limiting
All Analytics API endpoints are rate limited to 10 requests per second per API key. See [rate limiting](https://docs.planet.com/develop/rate-limiting.md) for details.
### Errors
See the [errors page](https://docs.planet.com/develop/errors.md) for API error information.
## Additional Resources
[📓Analytics API Jupyter Notebooks](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks/api_guides/analytics_api)
[Check out the Jupyter notebook tutorials on GitHub for using the Analytics API.](https://github.com/planetlabs/notebooks/tree/master/jupyter-notebooks/api_guides/analytics_api)
[📖Planet APIs Overview](https://docs.planet.com/develop/apis.md)
[Learn more about Planet APIs](https://docs.planet.com/develop/apis.md)
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/analytics/list-feeds-subscriptions/)
# Feeds and Subscriptions
## List Subscriptions
```
https://api.planet.com/analytics/subscriptions
```
Returns all analytic subscriptions enabled for your API key. Each subscription defines the spatial area of interest (AOI), temporal window (start and end time), and the analytic feed to apply over that region and time period.
### Example
* CURL
* Python
```
curl "https://api.planet.com/analytics/subscriptions" \
-H "Authorization: api-key $PL_API_KEY"
```
```
import os
import requests
from requests.auth import HTTPBasicAuth
API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
raise ValueError(
"Please set the PL_API_KEY environment variable as your Planet API key"
)
def list_analytic_subscriptions():
auth = HTTPBasicAuth(API_KEY, "")
resp = requests.get("https://api.planet.com/analytics/subscriptions", auth=auth)
if not resp.ok:
raise Exception(f"Failed to list analytic subscriptions: {resp.text}")
return resp.json()
```
### Response Properties
Each subscription includes the following properties:
| Field | Description | Example |
| ------------- | ---------------------------------------------------------------------------- | -------------------------------------- |
| `created` | UTC timestamp when the subscription was created | `2019-03-08T18:11:57.488Z` |
| `description` | Human-readable description of the subscription | `Building Detection in New Cairo` |
| `id` | UUID for the subscription | `f301b8c9-04e1-49f6-ab31-24a8c25edbd5` |
| `feedID` | UUID for the feed | `1ce86055-cad0-4960-bdf3-32763c17f19b` |
| `startTime` | Start of the subscription's temporal window | `2019-01-01T00:00:00.000Z` |
| `endTime` | End of the subscription's temporal window (omitted if no end time is set) | `2019-01-31T00:00:00.000Z` |
| `geometry` | GeoJSON polygon defining the subscription's spatial extent | See example below |
| `links` | HATEOAS links to the subscription, results, feed, and subscriptions endpoint | See example below |
| `title` | Human-readable title of the subscription | `Demo_Subscription_Singapore` |
| `updated` | UTC timestamp of the most recent update to subscription results | `2019-04-10T04:40:20.261Z` |
#### Geometry Example
```
{
"type": "Polygon",
"coordinates": [
[
[103.849296569824, 1.2513119542594],
[103.880882263184, 1.2513119542594],
[103.880882263184, 1.27293604010387],
[103.849296569824, 1.27293604010387],
[103.849296569824, 1.2513119542594]
]
]
}
```
#### Links Example
```
[
{
"href": "https://api.planet.com/analytics/subscriptions/f301b8c9-04e1-49f6-ab31-24a8c25edbd5",
"rel": "self"
},
{
"href": "https://api.planet.com/analytics/collections/f301b8c9-04e1-49f6-ab31-24a8c25edbd5/items",
"rel": "results"
},
{
"href": "https://api.planet.com/analytics/feeds/e2ee4fca-e998-46fc-abe4-2ccaa7b7d285",
"rel": "feed"
},
{
"href": "https://api.planet.com/analytics/subscriptions",
"rel": "subscriptions"
}
]
```
## List Feeds
```
https://api.planet.com/analytics/feeds
```
Returns all feeds enabled for your API key. Each feed defines the analytic model, source imagery type, and output format for a specific computer vision capability.
### Example
* CURL
* Python
```
curl "https://api.planet.com/analytics/feeds" \
-H "Authorization: api-key $PL_API_KEY"
```
```
import os
import requests
from requests.auth import HTTPBasicAuth
API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
raise ValueError(
"Please set the PL_API_KEY environment variable as your Planet API key"
)
def list_analytic_feeds():
auth = HTTPBasicAuth(API_KEY, "")
resp = requests.get("https://api.planet.com/analytics/feeds", auth=auth)
if not resp.ok:
raise Exception(f"Failed to list analytic feeds: {resp.text}")
return resp.json()
```
### Response Properties
Each feed includes the following properties:
| Field | Description | Example |
| ------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `created` | UTC timestamp when the feed was created | `2019-03-08T18:11:57.488Z` |
| `description` | Human-readable description of the feed | `Ship detections from rectified PlanetScope imagery` |
| `id` | UUID for the feed | `f35f37ce-4ba9-4b0d-b7d7-b687834223c3` |
| `links` | HATEOAS links to the feed and feeds collection | See example below |
| `source` | Source imagery configuration including bundle type, item types, and query filters | See example below |
| `target` | Output type: `collection` for vector feeds or `mosaic` with `series_id` for raster feeds | See example below |
| `title` | Human-readable title of the feed | `Ship Detections` |
| `updated` | UTC timestamp of the most recent feed update | `2019-04-11T17:51:39.771Z` |
#### Links Example
```
[
{
"href": "https://api.planet.com/analytics/feeds/f35f37ce-4ba9-4b0d-b7d7-b687834223c3",
"rel": "self"
},
{
"href": "https://api.planet.com/analytics/feeds",
"rel": "feeds"
}
]
```
#### Source Example
```
{
"config": {
"bundle": "visual",
"query": {
"filter": {
"config": ["true"],
"field_name": "ground_control",
"type": "StringInFilter"
},
"item_types": ["PSScene3Band"]
}
},
"type": "image"
}
```
#### Target Examples
**Vector Output:**
```
{
"type": "collection"
}
```
**Raster Output:**
```
{
"config": {
"series_id": "431b62a0-eaf9-45e7-acf1-d58278176d52"
},
"type": "mosaic"
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/analytics/querying-results/)
# Querying Results
## List Collections
```
https://api.planet.com/analytics/collections
```
Returns all result collections from your active subscriptions. Each collection contains the output from running an analytic feed over a subscription's defined area and time period.
### Example: List Collections
* CURL
* Python
```
curl "https://api.planet.com/analytics/collections" \
-H "Authorization: api-key $PL_API_KEY"
```
```
import os
import requests
from requests.auth import HTTPBasicAuth
API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
raise ValueError(
"Please set the PL_API_KEY environment variable as your Planet API key"
)
def list_collections():
auth = HTTPBasicAuth(API_KEY, "")
resp = requests.get("https://api.planet.com/analytics/collections", auth=auth)
if not resp.ok:
raise Exception(f"Failed to list collections: {resp.text}")
return resp.json()
```
### Response Properties
Each collection includes the following properties:
| Field | Description | Example |
| ------------- | -------------------------------------------------------------------- | -------------------------------------- |
| `created` | UTC timestamp when the collection was created | `2019-03-08T18:11:57.488Z` |
| `description` | Human-readable description of the collection | `Building Detection in New Cairo` |
| `id` | UUID for the collection | `1ce86055-cad0-4960-bdf3-32763c17f19b` |
| `title` | Human-readable title of the collection | `New Cairo Buildings` |
| `links` | HATEOAS links to the collection, its items, and collections endpoint | See example below |
#### Links Example
```
[
{
"href": "https://api.planet.com/analytics/collections/0c400b73-17e9-43be-884a-c30851d79ca3",
"rel": "self"
},
{
"href": "https://api.planet.com/analytics/collections/0c400b73-17e9-43be-884a-c30851d79ca3/items",
"rel": "items"
},
{
"href": "https://api.planet.com/analytics/collections",
"rel": "collections"
}
]
```
## Query Collection Results
```
https://api.planet.com/analytics/collections/{collection_id}/items
```
### Example
* CURL
* Python
```
curl https://api.planet.com/analytics/collections/$SUBSCRIPTION_ID/items \
-H "Authorization: api-key $PL_API_KEY"
```
```
import os
import requests
from requests.auth import HTTPBasicAuth
API_KEY = os.getenv("PL_API_KEY")
if not API_KEY:
raise ValueError(
"Please set the PL_API_KEY environment variable as your Planet API key"
)
def query_results(subscription_id):
auth = HTTPBasicAuth(API_KEY, "")
resp = requests.get(
f"https://api.planet.com/analytics/collections/{subscription_id}/items",
auth=auth,
)
if not resp.ok:
raise Exception(f"Failed to query results: {resp.text}")
return resp.json()
```
Response structure depends on the analytic feed type. Each feed returns specific metadata fields as described below.
***
## Vessel Detection
Returns GeoJSON features representing individual detected vessels with bounding box coordinates and vessel-specific metadata.
### Key Fields
| Field | Description | Example |
| -------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
| `geometry` | GeoJSON polygon defining the vessel's bounding box | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Unique identifier (UUID) | `17f21835-93c4-4664-b2ef-c2f57f5809a5` |
| `angle` | Mathematical angle of the vessel bounding box (0-180°) | `106.7` |
| `area_m2` | Area of the bounding box in square meters | `2543.2` |
| `bunkered` | Whether vessel is engaged in ship-to-ship transfer (Enhanced Vessel Detection only) | `false` |
| `heading` | Estimated heading direction (0-360°) | `162` |
| `length_m` | Estimated vessel length in meters | `113.79` |
| `width_m` | Estimated vessel width in meters | `22.35` |
| `object_class_label` | Vessel classification (Enhanced Vessel Detection only) | `"tanker"` |
| `score` | Detection confidence (0-1, higher = greater certainty) | `0.943` |
| `source_item_id` | Source imagery item ID | `"20251016_072148_62_2507"` |
| `observed` | UTC timestamp when vessel was observed | `"2025-10-16T07:21:48.627212Z"` |
See the full [Vessel Detection metadata reference](https://docs.planet.com/data/analytic-feeds/vessel-detection/techspec.md#full-metadata-reference) for all available fields.
***
## Aircraft Detection
Returns GeoJSON features representing individual detected aircraft with bounding box coordinates and aircraft-specific metadata.
### Key Fields
| Field | Description | Example |
| ----------------- | ------------------------------------------------------ | ------------------------------------------- |
| `geometry` | GeoJSON polygon defining the aircraft's bounding box | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Unique identifier (UUID) | `17f21835-93c4-4664-b2ef-c2f57f5809a5` |
| `bbox_area_m2` | Area of the bounding box in square meters | `1292.76` |
| `bbox_diagonal_m` | Diagonal length of the bounding box in meters | `51.09` |
| `bbox_length_m` | Estimated aircraft length in meters | `38.55` |
| `bbox_width_m` | Estimated aircraft width in meters | `33.53` |
| `score` | Detection confidence (0-1, higher = greater certainty) | `0.805` |
| `source_item_id` | Source imagery item ID | `"20260209_080938_54_24fd"` |
| `observed` | UTC timestamp when aircraft was observed | `"2026-02-09T08:09:38.541005Z"` |
See the full [Aircraft Detection metadata reference](https://docs.planet.com/data/analytic-feeds/aircraft-detection/techspec.md#full-metadata-reference) for all available fields.
***
## Building Detection (Raster)
Returns raster GeoTIFF outputs for mosaic quads where building detection was performed. Results reference both source and target quads.
### Key Fields
| Field | Description | Example |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| `geometry` | GeoJSON polygon defining the quad's spatial extent | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Result identifier (UUID) | `50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b` |
| `links.target-quad` | Download link for the detection GeoTIFF | Link to two-band raster |
| `links.source-quad` | Download link for the source imagery quad | Link to source GeoTIFF |
| `observed` | UTC timestamp when source imagery was captured | `2019-03-20T07:57:18.186039Z` |
| `source_mosaic_name` | Source mosaic identifier for WMTS queries | `global_monthly_2018_07_mosaic` |
| `source_quad_id` | X-Y tile identifier of the source quad | `434-1216` |
| `target_mosaic_name` | Result mosaic identifier (format: `sif-{feed_id}-{date}`) | `sif-b8ee0ab1-4500-485d-80b1-a24d92ee4cd5-2018-07-01` |
**GeoTIFF Structure:**
* **Band 1 (Detection mask):** Binary mask where `0` = no building detected, `255` = building detected
* **Band 2 (Alpha channel):** Validity mask where `255` = valid pixel, `0` = invalid pixel
***
## Road Detection (Raster)
Returns raster GeoTIFF outputs for mosaic quads where road detection was performed. Results reference both source and target quads.
### Key Fields
| Field | Description | Example |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| `geometry` | GeoJSON polygon defining the quad's spatial extent | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Result identifier (UUID) | `50e7d65b-9ec6-4ec1-8f46-c80bcbfffb2b` |
| `links.target-quad` | Download link for the detection GeoTIFF | Link to two-band raster |
| `links.source-quad` | Download link for the source imagery quad | Link to source GeoTIFF |
| `observed` | UTC timestamp when source imagery was captured | `2019-03-20T07:57:18.186039Z` |
| `source_mosaic_name` | Source mosaic identifier for WMTS queries | `global_monthly_2018_07_mosaic` |
| `source_quad_id` | X-Y tile identifier of the source quad | `434-1216` |
| `target_mosaic_name` | Result mosaic identifier (format: `sif-{feed_id}-{date}`) | `sif-b8ee0ab1-4500-485d-80b1-a24d92ee4cd5-2018-07-01` |
**GeoTIFF Structure:**
* **Band 1 (Detection mask):** Binary mask where `0` = no road detected, `255` = road detected
* **Band 2 (Alpha channel):** Validity mask where `255` = valid pixel, `0` = invalid pixel
***
## Building Change Detection (Vector)
Returns GeoJSON features representing newly constructed buildings detected through temporal analysis. Each feature contains an aggregation of 8x8 pixel grid cells ("change cells") where building development was detected.
### Key Fields
| Field | Description | Example |
| -------------------- | ---------------------------------------------------------- | ------------------------------------------- |
| `geometry` | GeoJSON polygon of the change cell area | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Unique identifier (UUID) | `17f21835-93c4-4664-b2ef-c2f57f5809a5` |
| `class_label` | Classification label | `"building"` |
| `change_direction` | Direction of change | `"positive"` |
| `date` | End date when change was detected | `"2026-02-02T00:00:00Z"` |
| `observed` | Start date of observation period | `"2026-01-26T00:00:00Z"` |
| `object_area_m2` | Area of detected change in square meters | `461.04` |
| `score` | Detection confidence (0.5-1.0, higher = greater certainty) | `0.594` |
| `source_mosaic_name` | Source mosaic used for detection | `rnb_weekly_v2_2026_01_26_2026_02_02` |
| `source_quad_id` | X-Y identifier of the source quad | `1140-1295` |
| `visual_mosaic_name` | Visual mosaic for imagery display | `ps_weekly_visual_subscription_...` |
See the full [Road & Building Change Detection metadata reference](https://docs.planet.com/data/analytic-feeds/road-building-change-detection/techspec.md#full-metadata-reference) for all available fields.
***
## Road Change Detection (Vector)
Returns GeoJSON features representing newly constructed roads detected through temporal analysis. Each feature contains an aggregation of 8x8 pixel grid cells ("change cells") where road development was detected.
### Key Fields
| Field | Description | Example |
| -------------------- | ---------------------------------------------------------- | ------------------------------------------- |
| `geometry` | GeoJSON polygon of the change cell area | `{"type": "Polygon", "coordinates": [...]}` |
| `id` | Unique identifier (UUID) | `17f21835-93c4-4664-b2ef-c2f57f5809a5` |
| `class_label` | Classification label | `"road"` |
| `change_direction` | Direction of change | `"positive"` |
| `date` | End date when change was detected | `"2026-02-02T00:00:00Z"` |
| `observed` | Start date of observation period | `"2026-01-26T00:00:00Z"` |
| `object_area_m2` | Area of detected change in square meters | `461.04` |
| `score` | Detection confidence (0.5-1.0, higher = greater certainty) | `0.594` |
| `source_mosaic_name` | Source mosaic used for detection | `rnb_weekly_v2_2026_01_26_2026_02_02` |
| `source_quad_id` | X-Y identifier of the source quad | `1140-1295` |
| `visual_mosaic_name` | Visual mosaic for imagery display | `ps_weekly_visual_subscription_...` |
See the full [Road & Building Change Detection metadata reference](https://docs.planet.com/data/analytic-feeds/road-building-change-detection/techspec.md#full-metadata-reference) for all available fields.
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/analytics/reference/)
# Analytics API Reference
* Feeds
* getList feeds
* getGet feed
* Subscriptions
* getList subscriptions
* getGet subscription
* Results
* getGet collection
* getList results
* getGet result
* OGC
* getService root
* getConformance details
[API docs by Redocly](https://redocly.com/redoc/)
# Planet Analytics (v1)
Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/analytics-api-spec.yaml)
Planet Analytics leverages computer vision to transform our imagery into analytic feeds that detect and classify objects, identify geographic features, and monitor change over time across the globe.
The Analytics API provides operations for working with [feeds](#tag/Feeds), [subscriptions](#tag/Subscriptions), and collections of [results](#tag/Results).
## [](#tag/Feeds)Feeds
A feed represents an analytic derived from Planet imagery. For example, a roads feed represents roads detected on monthly Planet mosaics and a vessels feed represents ships detected on daily Planet imagery.
## [](#tag/Feeds/paths/~1feeds~1/get)List feeds
Get a list of available feeds. Feeds are returned in descending creation order (most recently created first).
##### Authorizations:
*JWT**APIKey**Basic*
##### query Parameters
| | |
| ------ | ------------------------------------------------------------------------------------------ |
| before | stringWhen paginating, provide the identifier for last feed on previous page. |
| limit | integer \ \[ 1 .. 10000 ]Default: 250Upper limit for the number of feeds returned. |
### Responses
**200**
List of feeds.
**401**
Authentication information is missing or invalid.
**default**
Trouble listing feeds.
get/feeds/
https\://api.planet.com/analytics/feeds/
### Response samples
* 200
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"data": [
{
"created": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"source": [
{
"config": {
"property1": { },
"property2": { }
},
"name": "string",
"type": "image"
}
],
"target": {
"config": {
"property1": { },
"property2": { }
},
"type": "collection"
},
"title": "string",
"updated": "2019-08-24T14:15:22Z"
}
],
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"more": true
}`
## [](#tag/Feeds/paths/~1feeds~1{id}/get)Get feed
Get details for a feed.
##### Authorizations:
*JWT**APIKey**Basic*
##### path Parameters
| | |
| ---------- | -------------- |
| idrequired | stringFeed ID. |
### Responses
**200**
Feed info.
**401**
Authentication information is missing or invalid.
**404**
The requested resource was not found.
**default**
Trouble getting feed.
get/feeds/{id}
https\://api.planet.com/analytics/feeds/{id}
### Response samples
* 200
* 404
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"created": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"source": [
{
"config": {
"property1": { },
"property2": { }
},
"name": "string",
"type": "image"
}
],
"target": {
"config": {
"property1": { },
"property2": { }
},
"type": "collection"
},
"title": "string",
"updated": "2019-08-24T14:15:22Z"
}`
## [](#tag/Subscriptions)Subscriptions
Users have subscriptions to feeds in a specific area of interest (AOI) and time interval of interest (TOI). For example, a subscription could be road detection over twelve months in San Francisco, California.
## [](#tag/Subscriptions/paths/~1subscriptions~1/get)List subscriptions
Get a list of all subscriptions. Subscriptions are returned in descending creation order (most recently created first).
##### Authorizations:
*JWT**APIKey**Basic*
##### query Parameters
| | |
| ------ | -------------------------------------------------------------------------------------------------- |
| feedID | string |
| before | stringWhen paginating, provide the identifier for last subscription on previous page. |
| limit | integer \ \[ 1 .. 10000 ]Default: 250Upper limit for the number of subscriptions returned. |
### Responses
**200**
Subscription list.
**401**
Authentication information is missing or invalid.
**default**
Trouble listing subscriptions.
get/subscriptions/
https\://api.planet.com/analytics/subscriptions/
### Response samples
* 200
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"data": [
{
"created": "2019-08-24T14:15:22Z",
"description": "string",
"endTime": "2019-08-24T14:15:22Z",
"feedID": "string",
"geometry": {
"type": "string"
},
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"sourceUpdated": "2019-08-24T14:15:22Z",
"startTime": "2019-08-24T14:15:22Z",
"title": "string",
"updated": "2019-08-24T14:15:22Z"
}
],
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"more": true
}`
## [](#tag/Subscriptions/paths/~1subscriptions~1{id}/get)Get subscription
Get subscription info.
##### Authorizations:
*JWT**APIKey**Basic*
##### path Parameters
| | |
| ---------- | ---------------------- |
| idrequired | stringSubscription ID. |
### Responses
**200**
Subscription info.
**401**
Authentication information is missing or invalid.
**404**
The requested resource was not found.
**default**
Trouble getting subscription.
get/subscriptions/{id}
https\://api.planet.com/analytics/subscriptions/{id}
### Response samples
* 200
* 404
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"created": "2019-08-24T14:15:22Z",
"description": "string",
"endTime": "2019-08-24T14:15:22Z",
"feedID": "string",
"geometry": {
"type": "string"
},
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"sourceUpdated": "2019-08-24T14:15:22Z",
"startTime": "2019-08-24T14:15:22Z",
"title": "string",
"updated": "2019-08-24T14:15:22Z"
}`
## [](#tag/Results)Results
When new imagery is published in a user's subscription, Planet’s computer vision operations process the imagery, and its output is added to the collection of results associated with the subscription. For example, if a user has a subscription for the vessel feed, newly published daily imagery within that subscription AOI will be processed and new ship detections will be added to the subscription results. For raster-based output like building detections, results representing the footprint and linking to the raster data are added to the collection of subscription results.
## [](#tag/Results/paths/~1collections~1{id}/get)Get collection
Get metadata for a single results collection.
##### Authorizations:
*JWT**APIKey**Basic*
##### path Parameters
| | |
| ---------- | ---------------------- |
| idrequired | stringSubscription ID. |
### Responses
**200**
Collection info.
**401**
Authentication information is missing or invalid.
**404**
The requested resource was not found.
**default**
Trouble getting collection.
get/collections/{id}
https\://api.planet.com/analytics/collections/{id}
### Response samples
* 200
* 404
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"created": "2019-08-24T14:15:22Z",
"description": "string",
"extent": {
"spatial": {
"bbox": [
"[-180, -90, 180, 90]"
]
},
"temporal": {
"interval": [
"[\"2019-01-01T00:00:00.00Z\", \"2019-02-01T00:00:00.00Z\"]"
]
}
},
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"title": "string"
}`
## [](#tag/Results/paths/~1collections~1{subscriptionID}~1items~1/get)List results
Paginate through results for a subscription. Results are returned in descending creation order. Result IDs act as cursors when paginating backwards or forwards. To get older pages of results, use the `before` query parameter with the id of the oldest (last) result in a page of results. When returning to the API to query for newly created results, use the `after` query parameter with the id of the newest (first) result in a page. Results have a `created` field that can be stored and used later for sorting to determine the oldest or newest result from a previous query.
##### Authorizations:
*JWT**APIKey**Basic*
##### path Parameters
| | |
| ---------------------- | ---------------------- |
| subscriptionIDrequired | stringSubscription ID. |
##### query Parameters
| | |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit | integer \ \[ 1 .. 10000 ]Default: 250Upper limit for the number of results returned. |
| bbox | Array of numbers = 4 itemsOnly return results that intersect the provided bounding box. Bounding box values are min longitude, min latitude, max longitude, and max latitude (e.g. `-100,-50,100,50`). |
| time | stringAlias for `datetime`. Please use the `datetime` parameter instead. This property is deprecated and will be removed in a future release. |
| datetime | stringOnly return results that were observed in the given interval or instant. The time can be a closed interval (e.g. `2019-01-01T00:00:00.00Z/2019-02-01T00:00:00.00Z` for the month of January), an open interval (e.g. `2019-01-01T00:00:00.00Z/..` for all results in January or later and `../2019-01-01T00:00:00.00Z` for all results before January), or an instant (e.g. `2019-01-01T00:00:00.00Z`). Start times for intervals are inclusive, and end times are exclusive. |
| before | stringGet results published before the item with the provided ID. |
| after | stringGet results published after the item with the provided ID. |
### Responses
**200**
A GeoJSON FeatureCollection representing a page of result.
**401**
Authentication information is missing or invalid.
**404**
The requested resource was not found.
**default**
Trouble getting results.
get/collections/{subscriptionID}/items/
https\://api.planet.com/analytics/collections/{subscriptionID}/items/
### Response samples
* 200
* 404
* default
Content type
application/geo+json
Copy
Expand all Collapse all
`{
"features": [
{
"created": "2019-08-24T14:15:22Z",
"geometry": {
"type": "string"
},
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"properties": {
"property1": { },
"property2": { }
},
"type": "Feature"
}
],
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"type": "FeatureCollection"
}`
## [](#tag/Results/paths/~1collections~1{subscriptionID}~1items~1{resultID}/get)Get result
Get a single result.
##### Authorizations:
*JWT**APIKey**Basic*
##### path Parameters
| | |
| ---------------------- | ---------------------- |
| subscriptionIDrequired | stringSubscription ID. |
| resultIDrequired | stringResult ID. |
### Responses
**200**
A GeoJSON Feature representing a result.
**401**
Authentication information is missing or invalid.
**404**
The requested resource was not found.
**default**
Trouble getting result.
get/collections/{subscriptionID}/items/{resultID}
https\://api.planet.com/analytics/collections/{subscriptionID}/items/{resultID}
### Response samples
* 200
* 404
* default
Content type
application/geo+json
Copy
Expand all Collapse all
`{
"created": "2019-08-24T14:15:22Z",
"geometry": {
"type": "string"
},
"id": "string",
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
],
"properties": {
"property1": { },
"property2": { }
},
"type": "Feature"
}`
## [](#tag/OGC)OGC
Operations specific to the OGC API - Features interface.
## [](#tag/OGC/paths/~1/get)Service root
Get links to resources provided by the service.
##### Authorizations:
*JWT**APIKey**Basic*
### Responses
**200**
Service root.
**default**
Trouble rendering service root.
get/
https\://api.planet.com/analytics/
### Response samples
* 200
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"links": [
{
"href": "string",
"rel": "next",
"title": "Title of the Document",
"type": "application/json"
}
]
}`
## [](#tag/OGC/paths/~1conformance/get)Conformance details
Get details about OGC API - Features conformance.
##### Authorizations:
*JWT**APIKey**Basic*
### Responses
**200**
Conformance details.
**default**
Trouble rendering service conformance.
get/conformance
https\://api.planet.com/analytics/conformance
### Response samples
* 200
* default
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"conformsTo": [
"string"
]
}`
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/async-processing/)
# Asynchronous Processing API
The Asynchronous Processing API allows you to process more data with a single request than the Processing API. This is possible because the processing results are not returned immediately but are delivered to your object storage after some time. We recommend using Async API for processing larger images when you prefer not to deal with tiled results and when immediate processing results are not crucial.
The Async API allows you to process the data in a similar way as the Processing API; you define the input data, area of interest, and time range in the body of an Async API request, and the data is processed according to your evalscript. When using Async API keep in mind that:
* The maximum output image size cannot exceed 10,000 pixels in any dimension.
* Evalscript can be either sent directly in the request or it can be stored in S3 and referenced in an async request (see parameter `evalscriptReference` in [Async API reference](https://docs.planet.com/develop/apis/async-processing/reference.md#tag/async_process/operation/createNewAsyncProcessRequest) for more details). This allows you to use bigger evalscripts.
* The processing is asynchronous, which means that you do not get results in the response of your request. Instead, they are delivered to your object storage.
* A copy of each Async API request is also stored in your object storage. After processing completes, this copy is updated with additional details, including cost information.
* Only a limited number of asynchronous requests can run concurrently per user. The exact limit depends on your account type.
* Processing time depends on the request size and the current service load. Typically, the first request takes longer, while subsequent requests are faster.
* When using the Asynchronous Processing API, a multiplication factor of 2/3 is applied to all requests with an area of at least 10,000 px. This means you can process up to 1.5× more data compared to the Processing API for the same amount of Processing Units (PUs). Requests defining an area smaller than 10,000 px are charged at the standard rate (no multiplication factor applied).
## Async API Deployments
| Deployment | API endpoint | Region |
| ------------------ | ------------------------------------------------------------ | ------------ |
| AWS EU (Frankfurt) | | eu-central-1 |
| AWS US (Oregon) | | us-west-2 |
## Rate Limiting
The Asynchronous Processing API follows the general rate limiting policies described in [Rate Limiting](https://docs.planet.com/develop/rate-limiting.md). Your plan determines the number of concurrent requests allowed.
## Data Sources Restrictions
All data sources must be from the same deployment where the request is made.
## Object Storage Configuration
The Asynchronous Processing API requires access to object storage for reading evalscripts (optional) and storing processing results. We support two object storage providers:
* **Amazon S3**
* **Google Cloud Storage (GCS)**
### Supported Use Cases
Object storage is used for:
* Reading evalscript files from storage (optional, evalscripts can also be provided directly in the request)
* Uploading processing results (required)
* Storing a copy of each request with additional details including cost information
### AWS S3 Configuration
The Asynchronous Processing API supports two authentication methods for AWS S3. **We recommend using the IAM Assume Role method** for enhanced security and fine-grained access control.
#### Authentication Methods
##### Option 1: IAM Assume Role (Recommended)
The IAM Assume Role method provides better security by allowing temporary credentials and fine-grained access control without exposing long-term credentials.
To use this method, provide the ARN of an IAM role that has access to your S3 bucket:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
}
```
**Setup Steps:**
1. **Create an IAM Policy for S3 Access**
Create a policy that grants the necessary permissions to your S3 bucket:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": ["arn:aws:s3:::{bucket}", "arn:aws:s3:::{bucket}/*"]
}
]
}
```
2. **Create an IAM Role**
* In the AWS IAM console, create a new role
* Choose "AWS account" as the trusted entity type
* Select "Another AWS account" and enter account ID: `614251495211`
* Attach the policy created in step 1
* Note the Role ARN for use in your API requests
3. **Configure Trust Relationship (Optional but Recommended)**
For additional security, modify the role's trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::614251495211:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{domain-account-id}"
},
"StringLike": {
"sts:RoleSessionName": "sentinelhub"
}
}
}
]
}
```
Replace `{domain-account-id}` with your domain account ID from the [Dashboard](https://insights.planet.com/account/#/).
##### Option 2: Access Key & Secret Key
Alternatively, you can provide AWS access credentials directly:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}",
"region": "{region}"
}
}
}
}
```
The access key and secret must be linked to an IAM user with the following permissions on your S3 bucket:
* `s3:GetObject`
* `s3:PutObject`
* `s3:ListBucket`
To create access keys, see the [AWS documentation on programmatic access](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html).
#### Using S3 Configuration in Requests
The S3 configuration can be used in:
* `evalscriptReference.s3` - to specify the bucket where the evalscript .js file is available (optional)
* `output.delivery.s3` - to specify the bucket where the results will be stored (required)
Check [Async API reference](https://docs.planet.com/develop/apis/async-processing/reference.md#tag/async_process/operation/createNewAsyncProcessRequest) for more information.
### Google Cloud Storage Configuration
Google Cloud Storage is supported for both evalscript input and output delivery. Authentication requires a service account with base64-encoded credentials.
#### Preparing Credentials
1. Download your service account credentials in JSON format (not P12)
2. Encode them as a base64 string:
```
cat my_creds.json | base64
```
#### Using GCS for Evalscript Input
To read an evalscript from Google Cloud Storage:
```
{
"evalscriptReference": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
```
#### Using GCS for Output
To deliver results to Google Cloud Storage:
```
{
"output": {
"delivery": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
}
```
#### Required GCS Permissions
The service account must have the following permissions on the specified bucket:
* `storage.objects.create`
* `storage.objects.get`
* `storage.objects.delete`
* `storage.objects.list`
These permissions can be granted through IAM roles such as `Storage Object Admin` or custom roles. If possible, restrict access to the specific delivery path within the bucket for enhanced security.
#### Using GCS Configuration in Requests
The GCS configuration can be used in:
* `evalscriptReference.gs` - to specify the bucket where the evalscript .js file is available (optional)
* `output.delivery.gs` - to specify the bucket where the results will be stored (required)
Check [Async API reference](https://docs.planet.com/develop/apis/async-processing/reference.md#tag/async_process/operation/createNewAsyncProcessRequest) for more information.
### Cross-Cloud and Cross-Region Support
The Asynchronous Processing API provides complete flexibility in choosing storage locations for both input and output. Surcharges apply based on where your **processing results are delivered** (output storage location).
#### Storage Configuration Options
The table below shows output storage options for each deployment and their associated costs. Surcharges apply only to the volume of output data transferred to your storage.
**Important:** Input and output storage can be configured independently - you can mix and match any combination. For example, you can read evalscripts from GCS and write output to S3, or read from S3 in one region and write to S3 in another region. Input storage location does not affect costs.
| Deployment | Region | Output Storage Location | Additional PU Cost |
| ------------------ | ------------ | ----------------------- | ------------------ |
| AWS EU (Frankfurt) | eu-central-1 | S3 eu-central-1 | None |
| AWS EU (Frankfurt) | eu-central-1 | S3 (any other region) | 0.03 PU/MB |
| AWS EU (Frankfurt) | eu-central-1 | Google Cloud Storage | 0.1 PU/MB |
| AWS US (Oregon) | us-west-2 | S3 us-west-2 | None |
| AWS US (Oregon) | us-west-2 | S3 (any other region) | 0.03 PU/MB |
| AWS US (Oregon) | us-west-2 | Google Cloud Storage | 0.1 PU/MB |
**Output Data Transfer Surcharges Summary:**
* Cross-region (same cloud): 0.03 PU per MB
* Cross-cloud: 0.1 PU per MB
**Important Notes:**
* Surcharges apply only to output data transfer (processing results)
* Input location (evalscript files) does not affect costs
* When using a bucket in a different region than the deployment, specify the `region` parameter in your request:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"region": "{region}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
}
```
## Checking the Status of the Request
While the request is running, you can get its status (see this [example](https://docs.planet.com/develop/apis/async-processing/examples.md#get-information-about-your-asynchronous-processing-request)). Once the processing is finished, the request is deleted from our system. If you try to check its status after it has been deleted, you will get a '404 Not Found' response even if the request was processed successfully.
## Troubleshooting
In case anything goes wrong when creating an Async request, we will return an error message immediately. If anything goes wrong once the Async request has been created, we will deliver an "error.json" file with an error message to your object storage (S3).
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/async-processing/examples/)
# Async API Examples
The requests below are written in Python. To execute them, you need to create an OAuth client as is explained [here](https://docs.planet.com/develop/authentication.md#sentinel-hub-authentication). It is named `oauth` in these examples.
## Create an Asynchronous Processing Request
Before running the example, you will have to replace placeholders `{bucket}/{key}`, `{access-key}`, and `{secret-access-key}` with your values.
* Python SDK
```
url = 'https://services.sentinel-hub.com/async/v1/process'
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: [
"B04",
"B08"
]
}],
output: {
bands: 3
}
}
}
let viz = ColorGradientVisualizer.createWhiteGreen();
function evaluatePixel(samples) {
let ndvi = index(samples.B08, samples.B04);
vizualizedNdvi = viz.process(ndvi);
return vizualizedNdvi;
}
"""
payload = {
"input" : {
"bounds" : {
"bbox" : [ 426000, 3960000, 462000, 3994000 ],
"properties" : {
"crs" : "http://www.opengis.net/def/crs/EPSG/0/32633"
}
},
"data" : [ {
"dataFilter" : {
"timeRange" : {
"from" : "2022-06-20T00:00:00Z",
"to" : "2022-06-30T23:59:59Z"
}
},
"type" : "S2L2A"
} ]
},
"output" : {
"resx" : 10,
"resy" : 10,
"responses" : [ {
"identifier" : "default",
"format" : {
"type" : "image/tiff"
}
} ],
"delivery" : {
"s3" : {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}"
}
}
},
"evalscript" : evalscript
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.post(url, headers=headers, json=payload)
response.json()
```
Extracting the asynchronous request ID from the response:
* Python SDK
```
request_id = response.json()['id']
```
## Create an Asynchronous Processing Request with Google Storage Delivery
This example demonstrates how to use Google Cloud Storage for delivery of results instead of S3.
* Python SDK
```
url = 'https://services.sentinel-hub.com/async/v1/process'
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: [
"B04",
"B08"
]
}],
output: {
bands: 3
}
}
}
let viz = ColorGradientVisualizer.createWhiteGreen();
function evaluatePixel(samples) {
let ndvi = index(samples.B08, samples.B04);
vizualizedNdvi = viz.process(ndvi);
return vizualizedNdvi;
}
"""
payload = {
"input" : {
"bounds" : {
"bbox" : [ 426000, 3960000, 462000, 3994000 ],
"properties" : {
"crs" : "http://www.opengis.net/def/crs/EPSG/0/32633"
}
},
"data" : [ {
"dataFilter" : {
"timeRange" : {
"from" : "2022-06-20T00:00:00Z",
"to" : "2022-06-30T23:59:59Z"
}
},
"type" : "S2L2A"
} ]
},
"output" : {
"resx" : 10,
"resy" : 10,
"responses" : [ {
"identifier" : "default",
"format" : {
"type" : "image/tiff"
}
} ],
"delivery" : {
"gs" : {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
},
"evalscript" : evalscript
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.post(url, headers=headers, json=payload)
response.json()
```
To prepare your Google Cloud Storage credentials, download your service account credentials in JSON format and encode them as base64:
* CURL
```
cat my_creds.json | base64
```
Replace `{base64-encoded-credentials}` with the output of this command in the delivery section of your request.
## Get Information About Your Asynchronous Processing Request
* Python SDK
```
response = oauth.get(url=f"{url}/{request_id}")
response.json()
```
## Cloudless Mosaic Example
* Python SDK
```
url = 'https://services.sentinel-hub.com/async/v1/process'
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: [
"B04",
"B03",
"B02",
"SCL"
]
}],
output: { bands: 3, sampleType: "UINT16" },
mosaicking: "ORBIT"
}
}
function preProcessScenes(collections) {
collections.scenes.orbits = collections.scenes.orbits.filter(function (orbit) {
var orbitDateFrom = new Date(orbit.dateFrom)
return orbitDateFrom.getTime() >= (collections.to.getTime() - 3 * 31 * 24 * 3600 * 1000);
})
return collections
}
function getValue(values) {
values.sort(function (a, b) { return a - b; });
return getFirstQuartile(values);
}
function getFirstQuartile(sortedValues) {
var index = Math.floor(sortedValues.length / 4);
return sortedValues[index];
}
function getDarkestPixel(sortedValues) {
return sortedValues[0]; // darkest pixel
}
function validate(samples) {
var scl = samples.SCL;
if (scl === 3) { // SC_CLOUD_SHADOW
return false;
} else if (scl === 9) { // SC_CLOUD_HIGH_PROBA
return false;
} else if (scl === 8) { // SC_CLOUD_MEDIUM_PROBA
return false;
} else if (scl === 7) { // SC_CLOUD_LOW_PROBA / UNCLASSIFIED
// return false;
} else if (scl === 10) { // SC_THIN_CIRRUS
return false;
} else if (scl === 11) { // SC_SNOW_ICE
return false;
} else if (scl === 1) { // SC_SATURATED_DEFECTIVE
return false;
} else if (scl === 2) { // SC_DARK_FEATURE_SHADOW
// return false;
}
return true;
}
function evaluatePixel(samples, scenes) {
var clo_b02 = []; var clo_b03 = []; var clo_b04 = [];
var clo_b02_invalid = []; var clo_b03_invalid = []; var clo_b04_invalid = [];
var a = 0; var a_invalid = 0;
for (var i = 0; i < samples.length; i++) {
var sample = samples[i];
if (sample.B02 > 0 && sample.B03 > 0 && sample.B04 > 0) {
var isValid = validate(sample);
if (isValid) {
clo_b02[a] = sample.B02;
clo_b03[a] = sample.B03;
clo_b04[a] = sample.B04;
a = a + 1;
} else {
clo_b02_invalid[a_invalid] = sample.B02;
clo_b03_invalid[a_invalid] = sample.B03;
clo_b04_invalid[a_invalid] = sample.B04;
a_invalid = a_invalid + 1;
}
}
}
var rValue;
var gValue;
var bValue;
if (a > 0) {
rValue = getValue(clo_b04);
gValue = getValue(clo_b03);
bValue = getValue(clo_b02);
} else if (a_invalid > 0) {
rValue = getValue(clo_b04_invalid);
gValue = getValue(clo_b03_invalid);
bValue = getValue(clo_b02_invalid);
} else {
rValue = 0;
gValue = 0;
bValue = 0;
}
return [rValue * 10000,
gValue * 10000,
bValue * 10000]
}
"""
payload = {
"input" : {
"bounds" : {
"bbox" : [
11.193762,
44.684277,
18.622922,
47.872144
],
},
"data" : [ {
"dataFilter" : {
"timeRange" : {
"from" : "2019-06-01T00:00:00Z",
"to" : "2019-10-31T23:59:59Z"
},
"mosaickingOrder": "leastCC"
},
"type" : "S2L2A"
} ]
},
"output" : {
"width" : 5000,
"height" : 5000,
"responses" : [ {
"identifier" : "default",
"format" : {
"type" : "image/tiff"
}
} ],
"delivery" : {
"s3" : {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}"
}
}
},
"evalscript" : evalscript
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.post(url, headers=headers, json=payload)
response.json()
```
## Large True Color Example
* Python SDK
```
url = 'https://services.sentinel-hub.com/async/v1/process'
evalscript = """
//VERSION=3
function setup() {
return {
input: ["B02", "B03", "B04"],
output: {
bands: 3,
sampleType: "AUTO" // default value - scales the output values from [0,1] to [0,255].
}
}
}
function evaluatePixel(sample) {
return [2.5 * sample.B04, 2.5 * sample.B03, 2.5 * sample.B02]
}
"""
payload = {
"input" : {
"bounds" : {
"bbox" : [
11.193762,
44.684277,
18.622922,
47.872144
],
},
"data" : [ {
"dataFilter" : {
"timeRange" : {
"from" : "2022-10-01T00:00:00Z",
"to" : "2022-10-31T00:00:00Z"
},
},
"type" : "S2L1C"
} ]
},
"output" : {
"width" : 10000,
"height" : 10000,
"responses" : [ {
"identifier" : "default",
"format" : {
"type" : "image/tiff"
}
} ],
"delivery" : {
"s3" : {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}"
}
}
},
"evalscript" : evalscript
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.post(url, headers=headers, json=payload)
response.json()
```
## Median NDVI Over Three Years, Which Excludes CLM
```
url = 'https://services.sentinel-hub.com/async/v1/process'
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: ["B08", "B04", "B03", "B02", "CLM", "SCL"], //Requests required bands, s2cloudless mask and scene classification layer
units: "DN"
}],
output: {
bands: 4,
sampleType: SampleType.UINT16
},
mosaicking: "ORBIT"
};
}
function filterScenes (scenes, inputMetadata) {
return scenes.filter(function (scene) {
return scene.date.getTime()>=(inputMetadata.to.getTime()-12*30*24*3600*1000); //Defines the time range, e.g. from 1st June until 31st October counts 5 months with 30 days, 24 hours...
});
}
function getValue(values) {
values.sort( function(a,b) {return a - b;} );
return getMedian(values);
}
function getMedian(sortedValues) {
var index = Math.floor(sortedValues.length / 2);
return sortedValues[index];
}
function getDarkestPixel(sortedValues) {
return sortedValues[0]; // darkest pixel
}
function validate (samples) {
var scl = samples.SCL;
var clm = samples.CLM;
if (clm === 1 || clm === 255) {
return false;
} else if (scl === 1) { // SC_SATURATED_DEFECTIVE
return false;
} else if (scl === 3) { // SC_CLOUD_SHADOW
return false;
} else if (scl === 7) { // SC_CLOUD_LOW_PROBA
return false;
} else if (scl === 8) { // SC_CLOUD_MEDIUM_PROBA
return false;
} else if (scl === 9) { // SC_CLOUD_HIGH_PROBA
return false;
} else if (scl === 10) { // SC_THIN_CIRRUS
return false;
} else if (scl === 11) { // SC_SNOW_ICE
return false;
} else {
return true;
}
}
function evaluatePixel(samples, scenes) {
var clo_b02 = []; var clo_b03 = []; var clo_b04 = []; var clo_b08 = [];
var clo_b02_invalid = []; var clo_b03_invalid = []; var clo_b04_invalid = []; var clo_b08_invalid = [];
var a = 0; var a_invalid = 0;
for (var i = 0; i < samples.length; i++) {
var sample = samples[i];
if (sample.B02 > 0 && sample.B03 > 0 && sample.B04 > 0 && sample.B08 > 0) {
var isValid = validate(sample);
if (isValid) {
clo_b02[a] = sample.B02;
clo_b03[a] = sample.B03;
clo_b04[a] = sample.B04;
clo_b08[a] = sample.B08;
a = a + 1;
} else {
clo_b02_invalid[a_invalid] = sample.B02;
clo_b03_invalid[a_invalid] = sample.B03;
clo_b04_invalid[a_invalid] = sample.B04;
clo_b08_invalid[a_invalid] = sample.B08;
a_invalid = a_invalid + 1;
}
}
}
var rValue;
var gValue;
var bValue;
var nirValue;
if (a > 0) {
nirValue = getValue(clo_b08);
rValue = getValue(clo_b04);
gValue = getValue(clo_b03);
bValue = getValue(clo_b02);
} else if (a_invalid > 0) {
nirValue = getValue(clo_b08_invalid);
rValue = getValue(clo_b04_invalid);
gValue = getValue(clo_b03_invalid);
bValue = getValue(clo_b02_invalid);
} else {
nirValue = 0;
rValue = 0;
gValue = 0;
bValue = 0;
}
return [nirValue, rValue, gValue, bValue]
}
"""
payload = {
"input" : {
"bounds" : {
"bbox" : [
11.193762,
44.684277,
18.622922,
47.872144
],
},
"data" : [ {
"dataFilter" : {
"timeRange" : {
"from" : "2019-10-01T00:00:00Z",
"to" : "2022-10-01T00:00:00Z"
},
},
"type" : "S2L2A"
} ]
},
"output" : {
"width" : 5000,
"height" : 5000,
"responses" : [ {
"identifier" : "default",
"format" : {
"type" : "image/tiff"
}
} ],
"delivery" : {
"s3" : {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}"
}
}
},
"evalscript" : evalscript
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.post(url, headers=headers, json=payload)
response.json()
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/async-processing/reference/)
# Asynchronous Processing API Reference
* Async API
* Async Process
* postSubmit a new async process request
* getGet status of the request
[API docs by Redocly](https://redocly.com/redoc/)
# API Reference (1.0.0)
Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/sh-prod-async-process-api-spec.yaml)
## [](#tag/async_process)Async Process
**NOTE:** *Asynchronous Processing API is currently in beta release.*
## [](#tag/async_process/operation/createNewAsyncProcessRequest)Submit a new async process request
##### Authorizations:
*OAuth2*
##### Request Body schema: application/json
| | |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inputrequired | object (ProcessRequestInput) |
| outputrequired | object (AsyncProcessRequestOutput) |
| evalscript | stringYour evalscript. For details, click [here](https://docs.planet.com/develop/evalscripts/).Either this or `evalscriptReference` parameter is required. |
| evalscriptReference | S3BucketInfo (object) or GSBucketInfo (object) (ObjectStorageInfoV2) |
### Responses
**200**
Request submitted
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
**429**
Maximum number of concurrent async requests reached.
post/async/v1/process
https\://services.sentinel-hub.com/async/v1/process
### Request samples
* Payload
Content type
application/json
Copy
Expand all Collapse all
`{
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"width": 512,
"height": 512,
"resx": 0.1,
"resy": 0.1,
"responses": [
{
"identifier": "",
"format": {
"type": "image/png"
}
}
],
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"evalscript": "string",
"evalscriptReference": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
}`
### Response samples
* 200
* 400
Content type
application/json
Copy
`{
"id": "string",
"status": "RUNNING"
}`
## [](#tag/async_process/operation/getStatusAsyncRequest)Get status of the request
The status of the request will only be returned while it's running. After completion (either succeed or failure) this endpoint will return 404.
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| ----------------- | ------------------------ |
| requestIdrequired | string \Request ID |
### Responses
**200**
Successful response
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
get/async/v1/process/{requestId}
https\://services.sentinel-hub.com/async/v1/process/{requestId}
### Response samples
* 200
* 404
Content type
application/json
Copy
`{
"id": "string",
"status": "RUNNING"
}`
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/basemaps/)
# Basemaps API
The Basemaps API enables developers to access and download Mosaics products.
Within the Basemaps API, the terms "basemaps" and "mosaics" are often used interchangeably.
info
To learn more about Mosaics products, see the [product page](https://docs.planet.com/data/imagery/mosaics.md).
## Key Concepts
The Basemaps API is organized around the following key concepts:
* series: time-series collections of related mosaics (e.g. Global Monthly)
* mosaics: individual mosaics for a single time interval and their associated data and metadata
Data for a mosaic can be downloaded as **quads** (tiled data in Cloud Optimized GeoTIFF format) directly from Basemaps API, or accessed as tiles using the Tiles API.
## Access
Access to the Basemaps API (listing and downloading series and mosaics) is based on your Planet plan. You will need your Planet API key and an active plan with Mosaics access to view and download these products. The ability to view mosaics and download data is constrained by your Area of Access.
## Usage
### Series
A series is a growing time-series of related mosaics created on a regular cadence. Its mosaics may change over time if the temporal period of access allows.
#### List series
List series using the `/basemaps/v1/series` endpoint:
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/"
```
Series can also be filtered by name:
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/?name__is=Global%20Monthly"
```
### Mosaics
#### List mosaics
Mosaics belong to a series, but they can also be listed separately and filtered by name or other attributes.
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/"
```
Filtering mosaics by name:
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/?name__is=${MOSAIC_NAME}"
```
Browsing mosaics within a series:
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${SERIES_ID}/mosaics/"
```
#### Get single mosaic
Requesting a single mosaic returns metadata and links.
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/"
```
For each mosaic, there is an endpoint for searching for downloadable quads and, if enabled, a link to an XYZ tile service for streaming.
#### Get mosaic quads
Quads are downloadable Cloud Optimized GeoTIFF files. They are organized as a tiled grid. Search for quads for a mosaic by providing the mosaic name and a bounding box given by `lx,ly,ux,uy` (lower x, lower y, upper x, upper y in degrees).
* CURL
```
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/quads/?bbox=${LX},${LY},${UX},${UY}"
```
The response contains quads that intersect with the provided bounding box. Quad metadata includes direct download links for each file.
#### WMTS GetCapabilities
A WMTS capabilities document is available for each series, all mosaics, or a specific mosaic. Similar to the XYZ tile service link, third-party software may consume this service.
info
For more on WMTS and XYZ tile services, see the [Tiles API documentation](https://docs.planet.com/develop/apis/tiles.md).
## Example: Browsing Mosaics to Download Quads or Import into GIS Software
A typical workflow for a user with access to several series over a period of time might be to:
* list series and determine which one is suitable for a given task
* list mosaics within the series, selecting one or more based on time(s) of interest
* use the quad search endpoint with an AOI to query each mosaic and iterate over the quads, downloading them
* alternately, fetch the XYZ or WMTS tile service link and paste into third-party GIS software (QGIS or other compatible mapping client)
- CURL
```
# List series
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/series/"
# For the selected series, list mosaics.
# This URL is also available as a link for each entry in the list series response.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${SERIES_ID}/mosaics/"
# Select an individual mosaic, and look up metadata.
# This link is also available in the entry for each mosaic in the list mosaics response.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/"
# Find quads over an AOI for the selected mosaic
# the bbox parameter must contain two corners (lower left and upper right) of a bounding box in the format lx,ly,ux,uy.
# The response contains links that can be used to directly download quad files in GeoTIFF format.
curl --request GET \
-u "${PL_API_KEY}:" \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/quads/?bbox=-87.1,35,-87,35.1"
# Alternately, use the GetCapabilities URL with compatible GIS software.
# note: most GIS software may only require the URL. This example uses curl to fetch the full document
# in XML format.
curl --request GET \
--url "https://api.planet.com/basemaps/v1/mosaics/${MOSAIC_ID}/wmts?api_key=${PL_API_KEY}"
```
## Rate Limiting
To improve the experience for all users, Planet uses [rate limiting](https://docs.planet.com/develop/rate-limiting.md) to prevent overloading the system.
The following rate limits are currently in place for Basemaps API:
| Endpoint | Rate Limit
(r/s, per API key) |
| --------------- | ---------------------------------- |
| Quads | 100 |
| Other endpoints | 600 |
## Resources and Guides
Learn more about [working with Mosaics](https://docs.planet.com/platform/get-started/access-data/work-with-mosaics.md) in the Platform and examples of accessing and working with Mosaics in our [Jupyter Notebooks Guides](https://docs.planet.com/guides.md#jupyter-notebooks).
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/basemaps/pixprov/)
# Pixel Provenance
Pixel Provenance is an API that allows a user to understand what scene was used to produce a given pixel in a given mosaic.
Because a mosaic may span relatively large intervals, the provenance of a given pixel may be important when interpreting the imagery.
For example, a landscape altering event, such as timber harvesting or a fire, may have occurred anytime with the 3 months of imagery a quarterly mosaic might potentially consider.
Because of the way the best pixel for any location is selected, it is possible a contiguous feature is not represented correctly in the final mosaic as gradual changes in the landscape may have been missed due to atmospheric conditions making a given pixel less appealing.
Going back to the fire example, if the interval of mosaic generation overlaps half of the fire's temporal extent, the final mosaic might contain portions of the burned area but also now burned areas that appear unburned as they were only visible prior to the fire.
The raw pixel provenance products are described further in the [Mosaics Data](https://docs.planet.com/data/imagery/mosaics.md) section.
There are two APIs to query pixel provenance:
* Query endpoint - allows querying for the scene metadata associated with a given latitude and longitude.
* UTFGrid - a format that allows for more interactive mapping applications (with proper software support).
## Query Endpoint
The query endpoint is fairly simple to use if you know the name of the mosaic and the coordinates in degrees latitude and longitude.
The format for the request is:
```
GET https://tiles.planet.com/basemaps/v1/pixprov/{mosaic-name}/query?x={longitude}&y={latitude}
```
The response will be one of two variants:
* The metadata for the scene that contributed the pixel at the query coordinates. This will be the same as the response for the scene from the Data API's [Get Item](https://docs.planet.com/develop/apis/data/items.md#get-an-individual-item-by-item-id) operation.
* A JSON object with a single `status` property with one of `unknown` or `no data`. Unknown signifies that an image that is not available in the Data API - this can happen for a variety of reasons. The `no data` response corresponds to an empty pixel.
## UTFGrid
UTFGrid is an XYZ tiled protocol that requires a specialized client - for for information, see the section in [Tiles](https://docs.planet.com/develop/apis/tiles/xyz.md#pixel-provenance).
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/basemaps/reference/)
# Basemaps API Reference
* Basemaps and Mosaics
* getList Mosaics
* getGet Mosaic
* getGet Mosaic Grid
* getList Mosaic Quads
* postCreate a Mosaic Quad search
* getQuad Search Results
* getGet Mosaic Quad
* getGet Mosaic Quad URL
* getList Mosaic Quad Items
* getGet Mosaic TileJSON
* getList Mosaic Series
* getGet Mosaic Series
* getList Series' Mosaics
[API docs by Redocly](https://redocly.com/redoc/)
# Planet Mosaics API (1.0)
Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/basemaps-api-spec.yaml)
An API to interact with Mosaics generated on Planet's platform.
## [](#tag/Basemaps-and-Mosaics)Basemaps and Mosaics
## [](#tag/Basemaps-and-Mosaics/operation/listMosaics)List Mosaics
List all accessible mosaics.
##### query Parameters
| | |
| ---------------- | ------------------------------------------------------------------------------------ |
| \_page | integerInteger representing a specific page of results. |
| \_page\_size | integerNumber of results to return per page. |
| name\_\_is | stringIf provided, returns up to one result that exactly matches the provided value. |
| name\_\_contains | stringIf provided, returns only results that contain the fragment, case-insensitive. |
### Responses
**200**
List of mosaics.
**401**
Access denied - insufficient privileges.
**default**
Other error.
get/mosaics
https\://docs.planet.com/basemaps/v1/mosaics
### Response samples
* 200
* 401
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_next": "string",
"_self": "string"
},
"mosaics": [
{
"_links": {
"_self": "string",
"quads": "string",
"tiles": "string"
},
"bands": 0,
"bbox": [
0
],
"coordinate_system": "string",
"datatype": "string",
"first_acquired": "2019-08-24T14:15:22Z",
"grid": {
"quad_size": 0,
"resolution": 0
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"interval": "string",
"item_types": [
"string"
],
"last_acquired": "2019-08-24T14:15:22Z",
"level": 0,
"name": "string",
"product_type": "string",
"quad_download": true
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/getMosaic)Get Mosaic
Get a mosaic by id.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
### Responses
**200**
Mosaic details.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_self": "string",
"quads": "string",
"tiles": "string"
},
"bands": 0,
"bbox": [
0
],
"coordinate_system": "string",
"datatype": "string",
"first_acquired": "2019-08-24T14:15:22Z",
"grid": {
"quad_size": 0,
"resolution": 0
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"interval": "string",
"item_types": [
"string"
],
"last_acquired": "2019-08-24T14:15:22Z",
"level": 0,
"name": "string",
"product_type": "string",
"quad_download": true
}`
## [](#tag/Basemaps-and-Mosaics/operation/getMosaicGrid)Get Mosaic Grid
Get extended mosaic metadata by id.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
### Responses
**200**
Extended mosaic details.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/grid
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/grid
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
`{
"quad_size": 0,
"resolution": 0
}`
## [](#tag/Basemaps-and-Mosaics/operation/getQuadDownloadLinks)List Mosaic Quads
List of quad download links for a mosaic.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
##### query Parameters
| | |
| ------------ | ------------------------------------------------------------- |
| bboxrequired | stringComma separated bounding box in degrees as lx,ly,ux,uy. |
| minimal | booleanIf true, only return quad download links. |
| \_page | stringInteger representing a specific page of results. |
| \_page\_size | integerNumber of results to return per page. |
### Responses
**200**
List of quad download links.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/quads
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_next": "string",
"_self": "string"
},
"items": [
{
"_links": {
"_self": "string",
"download": "string",
"items": "string",
"thumbnail": "string"
},
"bbox": [
0
],
"id": "string",
"percent_covered": 0.1
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/createQuadSearch)Create a Mosaic Quad search
List of quad download links for a mosaic.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
##### query Parameters
| | |
| ------------ | ------------------------------------------------ |
| minimal | booleanIf true, only return quad download links. |
| \_page\_size | integerNumber of results to return per page. |
##### Request Body schema: application/jsonrequired
Search request
object (Search)
Search is a valid GeoJSON Polygon or MultiPolygon with 1500 or fewer vertices.
### Responses
**302**
302 redirect to results.
**400**
Invalid request.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
post/mosaics/{mosaic\_id}/quads/search
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads/search
### Request samples
* Payload
Content type
application/json
Copy
Expand all Collapse all
`{
"coordinates": [ [ [
-122.430755,
37.830635
], [
-122.430755,
37.822746
], [
-122.415158,
37.822746
], [
-122.415158,
37.830635
], [
-122.430755,
37.830635
]
]
],
"type": "Polygon"
}`
### Response samples
* 400
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"field": {
"property1": [
{
"message": "string"
}
],
"property2": [
{
"message": "string"
}
]
},
"general": [
{
"message": "string"
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/getQuadSearchLinks)Quad Search Results
List of quad download links for a mosaic.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
| search\_idrequired | stringsearch id. |
##### query Parameters
| | |
| ------------ | ------------------------------------------------------ |
| minimal | booleanIf true, return only download link. |
| \_page | stringInteger representing a specific page of results. |
| \_page\_size | integerNumber of results to return per page. |
### Responses
**200**
List of quad download links.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/quads/search/{search\_id}
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads/search/{search\_id}
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_next": "string",
"_self": "string"
},
"items": [
{
"_links": {
"_self": "string",
"download": "string",
"items": "string",
"thumbnail": "string"
},
"bbox": [
0
],
"id": "string",
"percent_covered": 0.1
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/getQuad)Get Mosaic Quad
Get mosaic quad by id.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
| quad\_idrequired | stringQuad identifier. |
### Responses
**200**
Mosaic quad details.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/quads/{quad\_id}
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads/{quad\_id}
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_self": "string",
"download": "string",
"items": "string",
"thumbnail": "string"
},
"bbox": [
0
],
"id": "string",
"percent_covered": 0.1
}`
## [](#tag/Basemaps-and-Mosaics/operation/getQuadDownload)Get Mosaic Quad URL
Get a full quad download URL quad id.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
| quad\_idrequired | stringQuad identifier. |
### Responses
**302**
302 redirect to quad download.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/quads/{quad\_id}/full
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads/{quad\_id}/full
### Response samples
* 401
* 404
* default
Content type
application/json
Copy
`{
"message": "string"
}`
## [](#tag/Basemaps-and-Mosaics/operation/getQuadItems)List Mosaic Quad Items
List items that contributed to a quad.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
| quad\_idrequired | stringQuad identifier. |
### Responses
**200**
List of items.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/quads/{quad\_id}/items
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/quads/{quad\_id}/items
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"items": [
{
"item_id": "string",
"item_type": "string",
"link": "string"
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/getMosaicTileJSON)Get Mosaic TileJSON
Get TileJSON for Mosaic. See
##### path Parameters
| | |
| ------------------ | ------------------------ |
| mosaic\_idrequired | stringMosaic identifier. |
### Responses
**200**
Gets a single Mosaic extended record.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/mosaics/{mosaic\_id}/tiles
https\://docs.planet.com/basemaps/v1/mosaics/{mosaic\_id}/tiles
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
`{ }`
## [](#tag/Basemaps-and-Mosaics/operation/listSeries)List Mosaic Series
List all mosaic series available to the authenticated user.
##### query Parameters
| | |
| ------------------- | ------------------------------------------------------------------------------------ |
| \_page | integerInteger representing a specific page of results. |
| \_page\_size | integerNumber of results to return per page. |
| name\_\_is | stringIf provided, returns up to one result that exactly matches the provided value. |
| name\_\_contains | stringIf provided, returns only results that contain the fragment, case-insensitive. |
| acquired\_\_between | stringAcquired between comma separated dates or date-times |
| acquired\_\_gt | stringAcquired greater than date or date-time |
| acquired\_\_lt | stringAcquired less than date or date-time |
### Responses
**200**
A list of mosaic series.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/series
https\://docs.planet.com/basemaps/v1/series
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_next": "string",
"_self": "string"
},
"series": [
{
"_links": {
"_self": "string",
"mosaics": "string"
},
"first_acquired": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"interval": "string",
"last_acquired": "2019-08-24T14:15:22Z",
"name": "string",
"product_type": "basemap",
"selector": "string"
}
]
}`
## [](#tag/Basemaps-and-Mosaics/operation/getSeries)Get Mosaic Series
Get a mosaic series by id.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| series\_idrequired | stringSeries identifier. |
### Responses
**200**
Mosaic Series details.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/series/{series\_id}
https\://docs.planet.com/basemaps/v1/series/{series\_id}
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_self": "string",
"mosaics": "string"
},
"first_acquired": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"interval": "string",
"last_acquired": "2019-08-24T14:15:22Z",
"name": "string",
"product_type": "basemap",
"selector": "string"
}`
## [](#tag/Basemaps-and-Mosaics/operation/getSeriesMosaics)List Series' Mosaics
List mosaics in this series.
##### path Parameters
| | |
| ------------------ | ------------------------ |
| series\_idrequired | stringSeries identifier. |
##### query Parameters
| | |
| ------------------- | ---------------------------------------------------------- |
| acquired\_\_between | stringAcquired between comma separated dates or date-times |
| acquired\_\_gt | stringAcquired greater than date or date-time |
| acquired\_\_lt | stringAcquired less than date or date-time |
### Responses
**200**
List of mosaics in this series.
**401**
Access denied - insufficient privileges.
**404**
Item not found.
**default**
Other error.
get/series/{series\_id}/mosaics
https\://docs.planet.com/basemaps/v1/series/{series\_id}/mosaics
### Response samples
* 200
* 401
* 404
* default
Content type
application/json
Copy
Expand all Collapse all
`{
"_links": {
"_self": "string"
},
"mosaics": [
{
"_links": {
"_self": "string",
"quads": "string",
"tiles": "string"
},
"bands": 0,
"bbox": [
0
],
"coordinate_system": "string",
"datatype": "string",
"first_acquired": "2019-08-24T14:15:22Z",
"grid": {
"quad_size": 0,
"resolution": 0
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"interval": "string",
"item_types": [
"string"
],
"last_acquired": "2019-08-24T14:15:22Z",
"level": 0,
"name": "string",
"product_type": "string",
"quad_download": true
}
]
}`
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-processing/)
# Batch Processing API
Requires Enterprise License
The Batch Processing API is only available for users on enterprise plans. If you do not have an enterprise plan, and would like to try it out, [contact us](https://www.planet.com/contact-sales) or [upgrade](https://www.planet.com/pricing/?tab=platform).
The Batch Processing API enables you to request data for large areas and longer time periods for any supported collection, including BYOC (Bring Your Own COG). It is typically more cost-effective when processing large amounts of data. For details, see [Processing Units](https://docs.planet.com/platform/processing-units.md#batch-processing-api).
It is an asynchronous REST service, meaning data will not be returned immediately but delivered to your specified object storage instead.
## Deployments
| Deployment | API endpoint | Region |
| ------------------ | ---------------------------------------------------- | ------------ |
| AWS EU (Frankfurt) | | eu-central-1 |
| AWS US (Oregon) | | us-west-2 |
## Rate Limiting
The Batch Processing API follows the general rate limiting policies described in [Rate Limiting](https://docs.planet.com/develop/rate-limiting.md). Rate limits are in place for service protection and should not affect normal usage.
## Data Sources Restrictions
All data sources must be from the same deployment where the request is made.
## Workflow
The Batch V2 Processing API comes with the set of REST APIs which support the execution of various workflows. The diagram below shows all possible statuses of a batch task:
* `CREATED`
* `ANALYSING`
* `ANALYSIS_DONE`
* `PROCESSING`
* `DONE`
* `FAILED`
* `STOPPED`
and user's actions:
* `ANALYSE`
* `START`
* `STOP`
which trigger transitions among them.
The workflow starts when a user posts a new batch request. In this step the system:
* creates a new batch task with the status `CREATED`
* validates the user's input (except the evalscript)
* ensures the user's account has at least 1000 PUs
* uploads a JSON of the original request to the user's bucket
* and returns the overview of the created task
The user can then decide to either request an additional analysis of the task or start the processing. When an additional analysis is requested:
* the status of the task changes to `ANALYSING`
* the evalscript is validated
* a [feature manifest](https://docs.planet.com/develop/apis/batch-processing.md#feature-manifest) file is uploaded to the user's bucket
* after the analysis is finished, the status of the task changes to `ANALYSIS_DONE`
If the user chooses to directly start processing, the system still executes the analysis but when the analysis is done it automatically proceeds with processing. This is not explicitly shown in the diagram in order to keep it simple.
When the user starts the processing:
* the status of the task changes to `PROCESSING` (this may take a while, depending on the load on the service)
* the processing starts
* an [execution database](https://docs.planet.com/develop/apis/batch-processing.md#execution-database) is periodically uploaded to the user's bucket
* spent processing units are billed periodically
When the processing is finished, the status of the task changes to `DONE`.
### Stopping the Request
A task might be stopped for the following reasons:
* it is requested by a user (user action)
* user is out of processing units
* something is wrong with the processing of the task (for example, the system is not able to process the data)
A user may stop the request in following states: `ANALYSING`, `ANALYSIS_DONE` and `PROCESSING`. However:
* if the status is `ANALYSING`, the analysis will complete
* if the status is `PROCESSING`, all features (polygons) that have been processed or are being processed at that moment are charged for
* user is not allowed to restart the task in the next 30 minutes
## Input Features
BatchV2 API supports two ways of specifying the input features of your batch task:
1. Pre-defined [Tiling Grid](https://docs.planet.com/develop/apis/batch-processing.md#1-tiling-grid)
2. User-defined [GeoPackage](https://docs.planet.com/develop/apis/batch-processing.md#2-geopackage)
### 1. Tiling Grid
For more effective processing we divide the area of interest into tiles and process each tile separately. While `process` API uses grids which come together with each datasource for processing of the data, the `batch` API uses one of the predefined tiling grids. The tiling grids 0-2 are based on the [Sentinel-2 tiling](https://www.esa.int/Applications/Observing_the_Earth/Copernicus/Sentinel-2/Data_products) in WGS84/UTM projection with some adjustments:
* The width and height of tiles in the original Sentinel 2 grid is 100 km. The width and height of tiles in our grids are given in the table below.
* All redundant tiles (for example, fully overlapped tiles) are removed.
All available tiling grids can be requested with:
note
To run this example you need to first create an OAuth client as is explained [here](https://docs.planet.com/develop/authentication.md#sentinel-hub-authentication).
* Python SDK
```
url = "https://services.sentinel-hub.com/batch/v2/tilinggrids/"
response = oauth.request("GET", url)
response.json()
```
This returns the list of available grids and information about tile size and available resolutions for each grid. Currently, available grids are:
| name | id | tile size | resolutions | coverage | output CRS | download the grid \[zip with shp file] \* |
| ------------------- | -- | --------- | ------------------------- | ----------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| S2 UTM 20km grid | 0 | 20040 m | 10 m, 20 m, 60 m | World, latitudes from -80.7° to 80.7° | UTM | [UTM 20km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-0.zip) |
| S2 UTM 10km grid | 1 | 10000 m | 10 m, 20 m | World, latitudes from -80.6° to 80.6° | UTM | [UTM 10km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-1.zip) |
| S2 UTM 100km grid | 2 | 100080 m | 60 m, 120 m, 240 m, 360 m | World, latitudes from -81° to 81° | UTM | [UTM 100km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-2.zip) |
| WGS84 1 degree grid | 3 | 1 ° | 0.0001°, 0.0002° | World, all latitudes | WGS84 | [WGS84 1 degree grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-3.zip) |
| LAEA 100km grid | 6 | 100000 m | 40 m, 50 m, 100 m | Europe, including Turkey, Iceland, Svalbald, Azores, and Canary Islands | EPSG:3035 | [LAEA 100km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-6.zip) |
| LAEA 20km grid | 7 | 20000 m | 10 m, 20 m | Europe, including Turkey, Iceland, Svalbald, Azores, and Canary Islands | EPSG:3035 | [LAEA 20km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-7.zip) |
\* The geometries of the tiles are reprojected to WGS84 for download. Because of this and other reasons the geometries of the output rasters may differ from the tile geometries provided here.
To use `20km` grid with 60 m resolution, for example, specify `id` and `resolution` parameters of the `tilingGrid` object when creating a new batch request (see an example of [full request](https://docs.planet.com/develop/apis/batch-processing/examples.md#create-a-batchv2-processing-request)) as:
* JSON
```
{
...
"input": {
"type" : "tiling-grid",
"id": 0,
"resolution": 60.0
},
...
}
```
### 2. GeoPackage
In addition to the tiling grids, BatchV2 API now also support user-defined features through [GeoPackages](https://www.geopackage.org/spec/). This allows you to specify features of any shape as long as the underlying geometry is a POLYGON or MULTIPOLYGON in an **EPSG compliant** CRS listed [here](https://docs.planet.com/develop/apis.md). The GeoPackage can also have multiple layers, offering more flexibility in specifying features in multiple CRS.
The GeoPackage must adhere to the [GeoPackage spec](https://www.geopackage.org/spec/) and contain at **least one feature table with any name**. The table must include a column that holds the geometry data. This column can be named arbitrarily, but it must be listed as the geometry column in the `gpkg_geometry_columns` table. The table schema should include the following columns:
| Column | Type | Example |
| ---------------- | ----------------------- | -------------------------------------------------------- |
| id - primary key | INTEGER **(UNIQUE)** | 1000 |
| identifier | TEXT **(UNIQUE)** | FEATURE\_NAME |
| geometry | POLYGON or MULTIPOLYGON | Feature geometry representation in GeoPackage WKB format |
| width | INTEGER | 1000 |
| height | INTEGER | 1000 |
| resolution | REAL | 0.005 |
#### Caveats
* You must specify either both width and height, or alternatively, specify resolution. If both values are provided, width and height will be used, and resolution will be ignored.
* The feature table must use a CRS that is **EPSG compliant**.
* `identifier` values must not be null and unique across all feature tables.
* There can be a maximum of 700.000 features in the GeoPackage.
* The feature output width and height cannot exceed 3500 by 3500 pixels or the equivalent in resolution.
Below you will find a list of example GeoPackages that serve as a showcase of how a GeoPackage file should be structured. Please note that these examples do not serve as production-ready GeoPackages and should only be used for testing purposes. If you would like to use these tiling grids for processing, use the equivalent tiling grid with the tiling grid input instead.
| name | id | output CRS | geopackage |
| ------------------- | -- | ---------- | ---------------------------------------------------------------------------------------------- |
| UTM 20km grid | 0 | UTM | [UTM 20km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-0.gpkg) |
| UTM 10km grid | 1 | UTM | [UTM 10km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-1.gpkg) |
| UTM 100km grid | 2 | UTM | [UTM 100km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-2.gpkg) |
| WGS84 1 degree grid | 3 | WGS84 | [WGS84 1 degree grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-3.gpkg) |
| LAEA 100km grid | 6 | EPSG:3035 | [LAEA 100km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-6.gpkg) |
| LAEA 20km grid | 7 | EPSG:3035 | [LAEA 20km grid](https://s3.eu-central-1.amazonaws.com/sh-batch-grids/tiling-grid-7.gpkg) |
An example of a batch task with GeoPackage input is available [here](https://docs.planet.com/develop/apis/batch-processing/examples.md#option-3-geopackage-input-and-geotiff-output).
### Area of Interest and PUs
When using either [Tiling Grid](https://docs.planet.com/develop/apis/batch-processing.md#1-tiling-grid) or [GeoPackage](https://docs.planet.com/develop/apis/batch-processing.md#2-geopackage) as input, the features that end up being processed are determined by the `processRequest.input.bounds` parameter specified in the request, called Area of Interest or AOI.
The way the AOI parameter is used and its effect depend on the input type used:
* Tiling grid: The AOI **must** be specified in the request. Only the tiles (features) that intersect with the AOI will be processed.
* GeoPackage: The AOI can optionally be omitted. If the AOI is omitted, all the features inside your GeoPackage will be processed. Conversely, if AOI is specified, only the features that intersect with the AOI will be processed.
Please note that in both cases of input types, if the feature is only **partially** covered by the AOI, the feature will be processed in its **entirety**.
You are only charged PUs for the features that are processed. If a feature does not intersect with the AOI, it will not be charged for.
## Processing Results
The outputs of a batch task will be stored to your object storage in either:
* GeoTIFF (and JSON for metadata) or
* Zarr format
### GeoTIFF Output Format
**The GeoTIFF format will be used if your request includes the `output.type` parameter set to `raster`, along with other relevant parameters specified in the [BatchV2 API reference](https://docs.planet.com/develop/apis/batch-processing/reference.md#tag/batch_v2_process/operation/createNewBatchV2ProcessingRequest). An example of a batch task with GeoTIFF output is available [here](https://docs.planet.com/develop/apis/batch-processing/examples.md#option-1-geotiff-format-output).**
By default, the results will be organized in sub-folders where one sub-folder will be created for each feature. Each sub-folder might contain one or more images depending on how many outputs were defined in the [evalscript](https://docs.planet.com/develop/evalscripts/functions.md#setup-function) of the request. For example:
Batch Processing API Sub Folders
You can also customize the sub-folder structure and file naming as described in the `delivery` parameter under `output` in [BatchV2 API reference](https://docs.planet.com/develop/apis/batch-processing/reference.md#tag/batch_v2_process/operation/createNewBatchV2ProcessingRequest).
You can choose to return your GeoTIFF files as Cloud Optimized GeoTIFF (COG), by setting the `cogOutput` parameter under `output` in your request as `true`. Several advanced COG options can be selected as well - read about the parameter in [BatchV2 API reference](https://docs.planet.com/develop/apis/batch-processing/reference.md#tag/batch_v2_process/operation/createNewBatchV2ProcessingRequest).
The output projection depends on the selected input, either tiling grid or GeoPackage:
1. If the input is a tiling grid, the results of batch processing will be in the projection of the selected [tiling grid](https://docs.planet.com/develop/apis/batch-processing.md#1-tiling-grid). For UTM-based grids, each part of the AOI (Area of Interest) is delivered in the UTM zone with which it intersects. In other words, in case your AOI intersects with more UTM zones, the results will be delivered as tiles in different UTM zones (and thus different CRSs).
2. If the input is a GeoPackage, the results will be in the same CRS as the input feature's CRS.
### Zarr Output Format
The Zarr format will be used if your request includes the `output.type` parameter set to `zarr`, along with other relevant parameters specified in the [BatchV2 API reference](https://docs.planet.com/develop/apis/batch-processing/reference.md#tag/batch_v2_process/operation/createNewBatchV2ProcessingRequest). An example of a batch request with Zarr output is available [here](https://docs.planet.com/develop/apis/batch-processing/examples.md#option-2-zarr-format-output). Your request **must** only have one band per output and the `application/json` format in responses is **not** supported.
The outputs of batch processing will be stored as a single Zarr group containing one data array for each evalscript output and multiple coordinate arrays. The output will be stored in a subfolder named after the `requestId` that you pass to the API in the delivery URL parameter under `output` (for example, `delivery.s3.url` for AWS S3 or `delivery.gs.url` for Google Cloud Storage).
## Ingesting Results into BYOC
### Purpose
Enables automatic ingestion of processing results into a BYOC collection, allowing you to:
* Access data with Processing API, by using the collection ID
* Create a configuration with custom layers
* Make OGC requests to a configuration
* View data in EO Browser
### Configuration
In order to enable this functionality, you need to specify either ID of an existing BYOC collection (`collectionId`) or set `createCollection = true`.
* JSON
```
{
...
"output": {
...
"createCollection": true,
"collectionId": "{byoc-collection-id}",
...
},
...
}
```
If `collectionId` is provided, the existing collection will be used for data ingestion.
If `createCollection` is set to `true` and `collectionId` is not provided, a new BYOC collection will be created automatically and the collection bands will be set according to the request output `responses` definitions.
Regardless of whether you specify an existing collection or request a new one, processed data will still be uploaded to your object storage bucket (S3 or Google Cloud Storage), where it will be available for download and analysis.
### Important Restrictions
#### BYOC Ingestion Region and Cloud Provider Requirements
When using BYOC ingestion, the output storage **must be in the same region AND same cloud provider** as the API deployment you are using. Cross-region or cross-cloud delivery is **not supported** for BYOC ingestion.
**Deployment-to-Storage Mapping:**
| API Deployment | API Endpoint | Required Output Storage |
| ------------------ | ---------------------------------------------------- | ----------------------- |
| AWS EU (Frankfurt) | | AWS S3 eu-central-1 |
| AWS US (Oregon) | | AWS S3 us-west-2 |
**Example:** If you send your request to `https://services.sentinel-hub.com/batch/v2` (AWS EU deployment) and want to ingest results into BYOC, you must use an S3 bucket in the `eu-central-1` region. Using a bucket in `us-west-2` or Google Cloud Storage will fail.
For general output delivery without BYOC ingestion, you can use any region or cloud provider. See [Cross-Cloud and Cross-Region Support](#cross-cloud-and-cross-region-support) for details.
### Requirements and Best Practices
When creating a new batch collection or using an existing one, be careful to:
* Make sure that `cogOutput=true` and that the output format is `image/tiff`
* If an existing BYOC collection is used, make sure that `identifier` and `sampleType` from the output definition(s) match the name and the type of the BYOC band(s). Single band and multi-band outputs are supported.
* If multi-band output is used in the request, the additionally generated bands will be named using a numerical suffix in ascending order (for example, 2, ... 99). For example, if the `output: { id: "result", bands: 3 }` is used in the evalscript setup function, the produced BYOC bands will be named: `result` for band 1, `result2` for band 2 and `result3` for band 3. Make sure that no other output band has any of these automatically generated names, as this will throw an error during the analysis phase. The `output: [{ id: "result", bands: 3 },{ id: "result2", bands: 1 }]` will throw an exception.
* Keep sampleType in mind, as the values the evalscript returns when creating a collection will be the values available when making a request to access it.
### Mandatory Bucket Settings
#### AWS S3 Bucket Policy
Regardless of the credentials provided in the request (IAM role or access keys), you must set an AWS S3 bucket policy to allow our services to access the data. For detailed instructions on how to configure your S3 bucket policy, please refer to the [BYOC bucket settings documentation](https://docs.planet.com/develop/apis/byoc.md#aws-bucket-settings).
#### Google Cloud Storage Permissions
For Google Cloud Storage, ensure your service account has the required permissions: `storage.objects.create`, `storage.objects.get`, `storage.objects.delete`, and `storage.objects.list`. See [Google Cloud Storage Configuration](#google-cloud-storage-configuration) for more details.
## Object Storage Configuration
The Batch Processing API requires access to object storage for reading input data (GeoPackage files) and storing processing results. We support two object storage providers:
* **Amazon S3**
* **Google Cloud Storage (GCS)**
### Supported Use Cases
Object storage is used for:
* Reading GeoPackage input files (optional, if using GeoPackage input type)
* Uploading processing results (required)
* Uploading the original request JSON, [feature manifest](#feature-manifest), and [execution database](#execution-database)
### AWS S3 Configuration
The Batch Processing API supports two authentication methods for AWS S3. **We recommend using the IAM Assume Role method** for enhanced security and fine-grained access control.
#### Authentication Methods
##### Option 1: IAM Assume Role (Recommended)
The IAM Assume Role method provides better security by allowing temporary credentials and fine-grained access control without exposing long-term credentials.
To use this method, provide the ARN of an IAM role that has access to your S3 bucket:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
}
```
**Setup Steps:**
1. **Create an IAM Policy for S3 Access**
Create a policy that grants the necessary permissions to your S3 bucket:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": ["arn:aws:s3:::{bucket}", "arn:aws:s3:::{bucket}/*"]
}
]
}
```
2. **Create an IAM Role**
* In the AWS IAM console, create a new role
* Choose "AWS account" as the trusted entity type
* Select "Another AWS account" and enter account ID: `614251495211`
* Attach the policy created in step 1
* Note the Role ARN for use in your API requests
3. **Configure Trust Relationship (Optional but Recommended)**
For additional security, modify the role's trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::614251495211:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{domain-account-id}"
},
"StringLike": {
"sts:RoleSessionName": "sentinelhub"
}
}
}
]
}
```
Replace `{domain-account-id}` with your domain account ID from the [Dashboard](https://insights.planet.com/account/#/).
##### Option 2: Access Key & Secret Key
Alternatively, you can provide AWS access credentials directly:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}"
}
}
}
}
```
The access key and secret must be linked to an IAM user with the following permissions on your S3 bucket:
* `s3:GetObject`
* `s3:PutObject`
* `s3:DeleteObject`
* `s3:ListBucket`
To create access keys, see the [AWS documentation on programmatic access](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html).
#### S3 Bucket Policy for BYOC Ingestion
If you plan to use [BYOC ingestion](#ingesting-results-into-byoc), you must also configure your S3 bucket policy to allow our services to access the data. For detailed instructions, refer to the [BYOC bucket settings documentation](https://docs.planet.com/develop/apis/byoc.md#aws-bucket-settings).
### Google Cloud Storage Configuration
Google Cloud Storage is supported for both input (GeoPackage files) and output delivery. Authentication requires a service account with base64-encoded credentials.
#### Preparing Credentials
1. Download your service account credentials in JSON format (not P12)
2. Encode them as a base64 string:
```
cat my_creds.json | base64
```
#### Using GCS for Input
To read a GeoPackage from Google Cloud Storage:
```
{
"input": {
"type": "geopackage",
"features": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
}
```
#### Using GCS for Output
To deliver results to Google Cloud Storage:
```
{
"output": {
"type": "raster",
"delivery": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
}
```
#### Required GCS Permissions
The service account must have the following permissions on the specified bucket:
* `storage.objects.create`
* `storage.objects.get`
* `storage.objects.delete`
* `storage.objects.list`
These permissions can be granted through IAM roles such as `Storage Object Admin` or custom roles. If possible, restrict access to the specific delivery path within the bucket for enhanced security.
### Cross-Cloud and Cross-Region Support
When **not** using [BYOC ingestion](#ingesting-results-into-byoc), you have complete flexibility in choosing storage locations for both input and output. The Batch Processing API applies surcharges based on where your **processing results are delivered** (output storage location).
#### Storage Configuration Options
The table below shows output storage options for each deployment and their associated costs. Surcharges apply only to the volume of output data transferred to your storage.
**Important:** Input and output storage can be configured independently - you can mix and match any combination. For example, you can read input from GCS and write output to S3, or read from S3 in one region and write to S3 in another region. Input storage location does not affect PUs.
| Deployment | Region | Output Storage Location | Additional PU Cost | BYOC Ingestion Supported |
| ------------------ | ------------ | ----------------------- | ------------------ | ------------------------ |
| AWS EU (Frankfurt) | eu-central-1 | S3 eu-central-1 | None | ✅ Yes |
| AWS EU (Frankfurt) | eu-central-1 | S3 (any other region) | 0.03 PU/MB | ❌ No |
| AWS EU (Frankfurt) | eu-central-1 | Google Cloud Storage | 0.1 PU/MB | ❌ No |
| AWS US (Oregon) | us-west-2 | S3 us-west-2 | None | ✅ Yes |
| AWS US (Oregon) | us-west-2 | S3 (any other region) | 0.03 PU/MB | ❌ No |
| AWS US (Oregon) | us-west-2 | Google Cloud Storage | 0.1 PU/MB | ❌ No |
**Output Data Transfer Surcharges Summary:**
* Cross-region (same cloud): 0.03 PU per MB
* Cross-cloud: 0.1 PU per MB
**Important Notes:**
* Surcharges apply only to output data transfer (processing results)
* Input location (GeoPackage files) does not affect PUs
* When using an S3 bucket in a different region than the deployment region, specify the `region` parameter in your request:
```
{
"output": {
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"region": "{region}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
}
```
## Feature Manifest
### Purpose
* Provides a detailed overview of features scheduled for processing during the `PROCESSING` step.
* Enables users to verify feature information and corresponding output paths prior to processing.
#### Key information
* **File Type:** [GeoPackage](https://www.geopackage.org/spec/)
* **File Name:** `featureManifest-.gpkg`
* **Location:** Root folder of the specified output delivery path
* **Structure:**
* May contain multiple feature tables, one per distinct CRS used by the features.
* Table names follow the format `feature_` (for example. `feature_4326`).
During task analysis, the system uploads a file to the user's bucket called the `featureManifest-.gpkg`. This file is a GeoPackage that contains basic information about the features that will be processed during the `PROCESSING` step. It is intended to be used by users to check the features that will be processed and their corresponding output paths.
If the output type is set to `raster`, the output paths will be the paths to the GeoTIFF files. If the output type is `zarr`, the output paths will just be the root of the output folder.
The database may contain multiple feature tables; one feature table for each CRS of all features. The tables will be named `feature_`, for example, `feature_4326`.
The schema of feature tables inside the database is currently the following:
| Name | Type | Description |
| ---------- | -------- | -------------------------------------------------------------------------------- |
| fid | INTEGER | Auto-incrementing ID |
| outputId | TEXT | Output identifier defined in the `processRequest` |
| identifier | TEXT | ID of the feature |
| path | TEXT | The object storage path URI where the output of this feature will be uploaded to |
| width | INTEGER | Width of the feature in pixels |
| height | INTEGER | Height of the feature in pixels |
| geometry | GEOMETRY | Feature geometry representation in GeoPackage WKB format |
## Execution Database
### Purpose
The Execution Database serves as a monitoring tool for tracking the progress of feature execution within a specific task. It provides users with insight into the status of each feature being processed.
### Key Information
* **File Type:** SQLite
* **File Name:** `execution-.sqlite`
* **Location:** Root folder of specified output delivery path
* **Structure:**
* Contains a single table called `features`.
You can monitor the execution of your features for a specific task by checking the SQLite database that is uploaded to your bucket. The database contains the name and status of each feature. The database is updated periodically during the execution of the task.
The database can be found in your bucket in the root output folder and is named `execution-.sqlite`.
The schema of the `features` table is currently the following:
| Name | Type | Description |
| --------- | ------- | ---------------------------------------------------------------- |
| id | INTEGER | Numerical ID of the feature |
| name | TEXT | Textual ID of the feature |
| status | TEXT | Status of the feature |
| error | TEXT | Error message in case processing has failed |
| delivered | BOOLEAN | `True` if output delivered to delivery bucket, otherwise `False` |
The status of the feature can be one of the following:
* **PENDING**: The feature is waiting to be processed.
* **DONE**: Feature was successfully processed.
Caveat: If there was no data to process for this feature, the feature will still be marked with status `DONE` but with a '**No data**' message in the error column.
* **FATAL**: Feature has failed X amount of times and will not be retried. The error column details the issue.
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-processing/examples/)
# Examples
The requests below are written in Python. To execute them you need to create an OAuth client as is explained [here](https://docs.planet.com/develop/authentication.md#sentinel-hub-authentication). It is named `oauth` in these examples.
### Create a BatchV2 Processing Request
#### Option 1: GeoTiff format output
This request defines which data is requested and how it will be processed. In this example, we will calculate the maximum NDVI over two months for an area in Corsica and visualize the results using a built-in visualizer. The resulting image will be in a GeoTIFF format. To create a batch processing request, replace `{bucket}` with the name of your S3 bucket and run the following:
* Python SDK
```
url = "https://services.sentinel-hub.com/batch/v2/process"
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B08"]
}],
output: [{
id: "default",
bands: 3
}],
mosaicking: Mosaicking.ORBIT
}
}
function calcNDVI(sample) {
var denom = sample.B04 + sample.B08
return ((denom != 0) ? (sample.B08 - sample.B04) / denom : 0.0)
}
const maxNDVIcolors = [
[-0.2, 0xbfbfbf],
[0, 0xebebeb],
[0.1, 0xc8c682],
[0.2, 0x91bf52],
[0.4, 0x4f8a2e],
[0.6, 0x0f540c]
]
const visualizer = new ColorRampVisualizer(maxNDVIcolors);
function evaluatePixel(samples) {
var max = 0
for (var i = 0; i < samples.length; i++) {
var ndvi = calcNDVI(samples[i])
max = ndvi > max ? ndvi : max
}
ndvi = max
return visualizer.process(ndvi)
}
"""
payload = {
"processRequest": {
"input": {
"bounds": {
"bbox": [
8.44,
41.31,
9.66,
43.1
],
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [{
"dataFilter": {
"timeRange": {
"from": "2019-04-01T00:00:00Z",
"to": "2019-06-30T00:00:00Z"
},
"maxCloudCoverage": 70.0
},
"type": "sentinel-2-l2a"
}]
},
"output": {
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
},
"evalscript": evalscript
},
"input": {
"type" : "tiling-grid",
"id": 0,
"resolution": 60.0
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "s3://{bucket}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
},
"description": "Max NDVI over Corsica"
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.request("POST", url, headers=headers, json = payload)
response.json()
```
Extracting the batch request id from the response:
* Python SDK
```
batch_request_id = response.json()['id']
```
#### Option 2: Zarr format output
In this example, we will calculate the maximum NDVI over two months for an area in Corsica. Besides the maximum NDVI, we will also return the values of bands B04 and B08, which were used to calculate the maximum NDVI. All three results will be stored as arrays in an output Zarr file. To create a batch processing request replace `{bucket}` with the name of your S3 bucket and run the following:
* Python SDK
```
url = "https://services.sentinel-hub.com/batch/v2/process"
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B08"]
}],
output: [{
id: "maxNDVI",
sampleType: "FLOAT32",
bands: 1
},
{
id: "band04",
sampleType: "UINT16",
bands: 1
},
{
id: "band08",
sampleType: "UINT16",
bands: 1
}],
mosaicking: Mosaicking.ORBIT
}
}
function calcNDVI(sample) {
var denom = sample.B04 + sample.B08
return ((denom != 0) ? (sample.B08 - sample.B04) / denom : 0.0)
}
function evaluatePixel(samples) {
var maxNDVI = 0
var band04 = 0
var band08 = 0
for (var i = 0; i < samples.length; i++) {
var ndvi = calcNDVI(samples[i])
if (ndvi > maxNDVI){
maxNDVI = ndvi
band04 = samples[i].B04
band08 = samples[i].B08
}
}
return {
maxNDVI: [maxNDVI],
band04: [band04],
band08: [band08]
}
}
"""
payload = {
"processRequest": {
"input": {
"bounds": {
"bbox": [
8.44,
41.31,
9.66,
43.1
],
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"dataFilter": {
"timeRange": {
"from": "2019-04-01T00:00:00Z",
"to": "2019-06-30T00:00:00Z"
},
"maxCloudCoverage": 70
},
"type": "sentinel-2-l2a"
}
]
},
"output": {
"responses": [
{
"identifier": "band08",
"format": {
"type": "zarr/array"
}
},
{
"identifier": "band04",
"format": {
"type": "zarr/array"
}
},
{
"identifier": "maxNDVI",
"format": {
"type": "zarr/array"
}
}
]
},
"evalscript": evalscript
},
"input": {
"type": "tiling-grid",
"id": 6,
"resolution": 100.0
},
"output": {
"type": "zarr",
"delivery": {
"s3": {
"url": "s3://{bucket}/{key}",
"iamRoleARN": "{IAM-role-ARN}"
}
},
"group": {
"zarr_format": 2
},
"arrayParameters": {
"dtype": " max ? ndvi : max
}
ndvi = max
return visualizer.process(ndvi)
}
"""
payload = {
"processRequest": {
"input": {
"bounds": {
"bbox": [
8.44,
41.31,
9.66,
43.1
],
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [{
"dataFilter": {
"timeRange": {
"from": "2019-04-01T00:00:00Z",
"to": "2019-06-30T00:00:00Z"
},
"maxCloudCoverage": 70.0
},
"type": "sentinel-2-l2a"
}]
},
"output": {
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
},
"evalscript": evalscript
},
"input": {
"type" : "geopackage",
"features": {
"s3": {
"url": "s3://{bucket}/{path-to-geopackage}",
"iamRoleARN": "{IAM-role-ARN}",
}
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "s3://{bucket}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
},
"description": "Max NDVI over Corsica"
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.request("POST", url, headers=headers, json=payload)
response.json()
```
#### Option 4: Google Storage Bucket Input and Delivery
This example demonstrates how to use Google Cloud Storage buckets for both GeoPackage input and delivery of results.
* Python SDK
```
url = "https://services.sentinel-hub.com/batch/v2/process"
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: ["B04", "B08"]
}],
output: [{
id: "default",
bands: 3
}],
mosaicking: Mosaicking.ORBIT
}
}
function calcNDVI(sample) {
var denom = sample.B04 + sample.B08
return ((denom != 0) ? (sample.B08 - sample.B04) / denom : 0.0)
}
const maxNDVIcolors = [
[-0.2, 0xbfbfbf],
[0, 0xebebeb],
[0.1, 0xc8c682],
[0.2, 0x91bf52],
[0.4, 0x4f8a2e],
[0.6, 0x0f540c]
]
const visualizer = new ColorRampVisualizer(maxNDVIcolors);
function evaluatePixel(samples) {
var max = 0
for (var i = 0; i < samples.length; i++) {
var ndvi = calcNDVI(samples[i])
max = ndvi > max ? ndvi : max
}
ndvi = max
return visualizer.process(ndvi)
}
"""
payload = {
"processRequest": {
"input": {
"bounds": {
"bbox": [
8.44,
41.31,
9.66,
43.1
],
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [{
"dataFilter": {
"timeRange": {
"from": "2019-04-01T00:00:00Z",
"to": "2019-06-30T00:00:00Z"
},
"maxCloudCoverage": 70.0
},
"type": "sentinel-2-l2a"
}]
},
"output": {
"responses": [{
"identifier": "default",
"format": {
"type": "image/tiff"
}
}]
},
"evalscript": evalscript
},
"input": {
"type" : "geopackage",
"features": {
"gs": {
"url": "gs://{bucket}/{path-to-geopackage}",
"credentials": "{base64-encoded-credentials}"
}
}
},
"output": {
"type": "raster",
"delivery": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
},
"description": "Max NDVI over Corsica with Google Storage"
}
headers = {
'Content-Type': 'application/json'
}
response = oauth.request("POST", url, headers=headers, json=payload)
response.json()
```
To prepare your Google Cloud Storage credentials, download your service account credentials in JSON format and encode them as base64:
* CURL
```
cat my_creds.json | base64
```
Replace `{base64-encoded-credentials}` with the output of this command in both the input and output sections of your request.
### Get Information About All of Your Batch Processing Requests
* Python SDK
```
url = "https://services.sentinel-hub.com/batch/v2/process"
response = oauth.request("GET", url)
response.json()
```
### Get Information About a Batch Processing Request
* Python SDK
```
url = f"https://services.sentinel-hub.com/batch/v2/process/{batch_request_id}"
response = oauth.request("GET", url)
response.json()
```
### Request Detailed Analysis (ANALYSE)
* Python SDK
```
url = f"https://services.sentinel-hub.com/batch/v2/process/{batch_request_id}/analyse"
response = oauth.request("POST", url)
response.status_code
```
### Request the Start of Processing (START)
* Python SDK
```
url = f"https://services.sentinel-hub.com/batch/v2/process/{batch_request_id}/start"
response = oauth.request("POST", url)
response.status_code
```
### Cancel a Batch Processing Request (STOP)
* Python SDK
```
url = f"https://services.sentinel-hub.com/batch/v2/process/{batch_request_id}/stop"
response = oauth.request("POST", url)
response.status_code
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-processing/reference/)
# Batch Processing API Reference
* BatchV2 API
* Process
* postSubmit new batch processing request
* getQuery batch process requests
* getRetrieve a single batch process task by ID
* putUpdate a batch process request
* postRequest analysis of a batch process request
* postStart (confirm) processing of a batch process request
* postStop a batch process request
* Tiling grid
* getGet properties of all supported tiling grids
* getGet properties of a single tiling grid
[API docs by Redocly](https://redocly.com/redoc/)
# API Reference (1.0.0)
Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/sh-prod-batchv2-api-spec.yaml)
## [](#tag/batch_v2_process)Process
## [](#tag/batch_v2_process/operation/createNewBatchV2ProcessingRequest)Submit new batch processing request
##### Authorizations:
*OAuth2*
##### Request Body schema:application/jsonapplication/json
| | |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| processRequestrequired | object (ProcessRequestForBatchV2)Batch processing equivalent of the [Process request](#operation/process). |
| inputrequired | GeoPackageInput (object) or TilingGridInput (object) (BatchV2ProcessInput) |
| outputrequired | RasterOutput (object) or ZarrOutput (object) (BatchV2ProcessOutput) |
| description | stringOptional description that can be used to keep track of requests |
### Responses
**201**
Request submitted
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
post/batch/v2/process
https\://services.sentinel-hub.com/batch/v2/process
### Request samples
* Payload
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"processRequest": {
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"responses": [
{
"identifier": "",
"format": {
"type": "image/tiff"
}
}
]
},
"evalscript": "string"
},
"input": {
"type": "geopackage",
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"defaults": {
"width": 512,
"height": 512,
"resolution": 0.1
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"overwrite": false,
"skipExisting": false,
"cogOutput": false,
"cogParameters": {
"overviewLevels": [
0
],
"overviewMinSize": 0,
"resamplingAlgorithm": "nearest",
"blockxsize": 256,
"blockysize": 256,
"usePredictor": true
},
"createCollection": false,
"collectionId": "string"
},
"description": "string"
}`
### Response samples
* 201
* 400
Content type
application/json
Copy
Expand all Collapse all
`{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"request": {
"processRequest": {
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"responses": [
{
"identifier": "",
"format": {
"type": "image/tiff"
}
}
]
},
"evalscript": "string"
},
"input": {
"type": "geopackage",
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"defaults": {
"width": 512,
"height": 512,
"resolution": 0.1
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"overwrite": false,
"skipExisting": false,
"cogOutput": false,
"cogParameters": {
"overviewLevels": [
0
],
"overviewMinSize": 0,
"resamplingAlgorithm": "nearest",
"blockxsize": 256,
"blockysize": 256,
"usePredictor": true
},
"createCollection": false,
"collectionId": "string"
},
"description": "string"
},
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",
"status": "CREATED",
"error": "string",
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"created": "2019-08-24T14:15:22Z",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"stoppedStatusReason": "OUT_OF_PU"
}`
## [](#tag/batch_v2_process/operation/getAllBatchV2ProcessRequests)Query batch process requests
##### Authorizations:
*OAuth2*
##### query Parameters
| | |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count | integer \Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use *viewtoken* to page through. |
| viewtoken | stringWhen the total number of items is larger than *count*, the response contains *viewtoken*. This *viewtoken* can be used in the next request to retrieve the next page of items.The next page can be retrieved by repeating the query. However, replace your URL with the next URL in the returned links object. |
| sort | stringEnum: "created" "created:desc" "status" "status:desc"Sort the batch process requests by given field. Omit for default ordering. |
### Responses
**200**
Successful response
**401**
Unauthorized
**403**
Insufficient permissions
get/batch/v2/process
https\://services.sentinel-hub.com/batch/v2/process
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{
"data": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"request": {
"processRequest": {
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"responses": [
{
"identifier": "",
"format": {
"type": "image/tiff"
}
}
]
},
"evalscript": "string"
},
"input": {
"type": "geopackage",
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"defaults": {
"width": 512,
"height": 512,
"resolution": 0.1
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"overwrite": false,
"skipExisting": false,
"cogOutput": false,
"cogParameters": {
"overviewLevels": [
0
],
"overviewMinSize": 0,
"resamplingAlgorithm": "nearest",
"blockxsize": 256,
"blockysize": 256,
"usePredictor": true
},
"createCollection": false,
"collectionId": "string"
},
"description": "string"
},
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",
"status": "CREATED",
"error": "string",
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"created": "2019-08-24T14:15:22Z",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"stoppedStatusReason": "OUT_OF_PU"
}
],
"links": {
"currentToken": "string",
"nextToken": "string",
"previousToken": "string",
"@id": "http://example.com",
"next": "http://example.com",
"previous": "http://example.com"
}
}`
## [](#tag/batch_v2_process/operation/getSingleBatchV2ProcessTaskById)Retrieve a single batch process task by ID
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| -------------- | --------------------- |
| taskIdrequired | string \Task ID |
### Responses
**200**
Successful response
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
get/batch/v2/process/{taskId}
https\://services.sentinel-hub.com/batch/v2/process/{taskId}
### Response samples
* 200
* 404
Content type
application/json
Copy
Expand all Collapse all
`{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"request": {
"processRequest": {
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"responses": [
{
"identifier": "",
"format": {
"type": "image/tiff"
}
}
]
},
"evalscript": "string"
},
"input": {
"type": "geopackage",
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"defaults": {
"width": 512,
"height": 512,
"resolution": 0.1
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"overwrite": false,
"skipExisting": false,
"cogOutput": false,
"cogParameters": {
"overviewLevels": [
0
],
"overviewMinSize": 0,
"resamplingAlgorithm": "nearest",
"blockxsize": 256,
"blockysize": 256,
"usePredictor": true
},
"createCollection": false,
"collectionId": "string"
},
"description": "string"
},
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",
"status": "CREATED",
"error": "string",
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"created": "2019-08-24T14:15:22Z",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"stoppedStatusReason": "OUT_OF_PU"
}`
## [](#tag/batch_v2_process/operation/updateBatchV2ProcessRequest)Update a batch process request
Only the requests that are not currently being processed nor waiting to be processed can be updated.
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| -------------- | --------------------- |
| taskIdrequired | string \Task ID |
##### Request Body schema: application/json
| | |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| description | stringOptional description that can be used to keep track of requests. If omitted, the description will not be changed. |
### Responses
**200**
Successful response
**400**
Unauthorized
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
**409**
Conflict in the request
put/batch/v2/process/{taskId}
https\://services.sentinel-hub.com/batch/v2/process/{taskId}
### Request samples
* Payload
Content type
application/json
Copy
`{
"description": "string"
}`
### Response samples
* 200
* 404
* 409
Content type
application/json
Copy
Expand all Collapse all
`{
"processRequest": {
"input": {
"bounds": {
"bbox": [
13.822174072265625,
45.85080395917834,
14.55963134765625,
46.29191774991382
],
"geometry": {
"type": "Polygon",
"coordinates": [ [ [
14.000701904296873,
46.23685258143992
], [
13.822174072265625,
46.09037664604301
], [
14.113311767578125,
45.85080395917834
], [
14.55963134765625,
46.038922598236
], [
14.441528320312498,
46.28717293114449
], [
14.17236328125,
46.29191774991382
], [
14.000701904296873,
46.23685258143992
]
]
]
},
"properties": {
"crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"output": {
"responses": [
{
"identifier": "",
"format": {
"type": "image/tiff"
}
}
]
},
"evalscript": "string"
},
"input": {
"type": "geopackage",
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"defaults": {
"width": 512,
"height": 512,
"resolution": 0.1
}
},
"output": {
"type": "raster",
"delivery": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"overwrite": false,
"skipExisting": false,
"cogOutput": false,
"cogParameters": {
"overviewLevels": [
0
],
"overviewMinSize": 0,
"resamplingAlgorithm": "nearest",
"blockxsize": 256,
"blockysize": 256,
"usePredictor": true
},
"createCollection": false,
"collectionId": "string"
},
"description": "string"
}`
## [](#tag/batch_v2_process/operation/batchV2Analyse)Request analysis of a batch process request
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| -------------- | --------------------- |
| taskIdrequired | string \Task ID |
### Responses
**204**
Success
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
post/batch/v2/process/{taskId}/analyse
https\://services.sentinel-hub.com/batch/v2/process/{taskId}/analyse
### Response samples
* 400
* 404
Content type
application/json
Copy
Expand all Collapse all
`{
"error": {
"status": 0,
"reason": "string",
"message": "string",
"code": "COMMON_BAD_PAYLOAD",
"errors": { }
}
}`
## [](#tag/batch_v2_process/operation/batchV2StartProcessRequest)Start (confirm) processing of a batch process request
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| -------------- | --------------------- |
| taskIdrequired | string \Task ID |
### Responses
**204**
Success
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
post/batch/v2/process/{taskId}/start
https\://services.sentinel-hub.com/batch/v2/process/{taskId}/start
### Response samples
* 400
* 404
Content type
application/json
Copy
Expand all Collapse all
`{
"error": {
"status": 0,
"reason": "string",
"message": "string",
"code": "COMMON_BAD_PAYLOAD",
"errors": { }
}
}`
## [](#tag/batch_v2_process/operation/batchV2StopProcessRequest)Stop a batch process request
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| -------------- | --------------------- |
| taskIdrequired | string \Task ID |
### Responses
**204**
Success
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
post/batch/v2/process/{taskId}/stop
https\://services.sentinel-hub.com/batch/v2/process/{taskId}/stop
### Response samples
* 400
* 404
Content type
application/json
Copy
Expand all Collapse all
`{
"error": {
"status": 0,
"reason": "string",
"message": "string",
"code": "COMMON_BAD_PAYLOAD",
"errors": { }
}
}`
## [](#tag/batch_v2_tiling_grid)Tiling grid
## [](#tag/batch_v2_tiling_grid/operation/getBatchV2TilingGridsProperties)Get properties of all supported tiling grids
##### Authorizations:
*OAuth2*
##### query Parameters
| | |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count | integer \Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use *viewtoken* to page through. |
| viewtoken | stringWhen the total number of items is larger than *count*, the response contains *viewtoken*. This *viewtoken* can be used in the next request to retrieve the next page of items.The next page can be retrieved by repeating the query. However, replace your URL with the next URL in the returned links object. |
### Responses
**200**
Successful response
**401**
Unauthorized
get/batch/v2/tilinggrids
https\://services.sentinel-hub.com/batch/v2/tilinggrids
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{
"data": [
{
"id": 0,
"name": "string",
"properties": {
"tileWidth": 0.1,
"tileHeight": 0.1,
"resolutions": [
0.1
],
"unit": "METRE"
}
}
],
"links": {
"currentToken": "string",
"nextToken": "string",
"previousToken": "string",
"@id": "http://example.com",
"next": "http://example.com",
"previous": "http://example.com"
}
}`
## [](#tag/batch_v2_tiling_grid/operation/getBatchV2TilingGridProperties)Get properties of a single tiling grid
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| ---------- | ------------------------------ |
| idrequired | integer \Tilinggrids ID |
### Responses
**200**
Successful response
**400**
Bad request
**401**
Unauthorized
get/batch/v2/tilinggrids/{id}
https\://services.sentinel-hub.com/batch/v2/tilinggrids/{id}
### Response samples
* 200
* 400
Content type
application/json
Copy
Expand all Collapse all
`{
"id": 0,
"name": "string",
"properties": {
"tileWidth": 0.1,
"tileHeight": 0.1,
"resolutions": [
0.1
],
"unit": "METRE"
}
}`
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-statistical/)
# Batch Statistical API
Requires Enterprise License
The Batch Statistical API is only available for users on enterprise plans. If you do not have an enterprise plan, and would like to try it out, [contact us](https://www.planet.com/contact-sales) or [upgrade](https://www.planet.com/pricing/?tab=platform).
The Batch Statistical API enables you to request statistics similarly to the [Statistical API](https://docs.planet.com/develop/apis/statistical.md), but for multiple polygons at once and/or for longer aggregations. A typical use case would be calculating statistics for all parcels in a country.
Similar to the [Batch Processing API](https://docs.planet.com/develop/apis/batch-processing.md), this is an asynchronous REST service. This means that data will not be immediately returned in the response of the request but delivered to your object storage, which needs to be specified in the request.
You can find more details about the API in the [API Reference](https://docs.planet.com/develop/apis/batch-statistical/reference.md) or in the [examples](https://docs.planet.com/develop/apis/batch-statistical/examples.md) of the workflow.
## Deployments
| Deployment | API endpoint | Region |
| ------------------ | ------------------------------------------------------- | ------------ |
| AWS EU (Frankfurt) | | eu-central-1 |
## Rate Limiting
The Batch Statistical API follows the general rate limiting policies described in [Rate Limiting](https://docs.planet.com/develop/rate-limiting.md). Rate limits are in place for service protection and should not affect normal usage.
## Data Sources Restrictions
All data sources must be from the same deployment where the request is made.
## Workflow
The Batch Statistical API workflow in many ways resembles the [Batch Processing API workflow](https://docs.planet.com/develop/apis/batch-processing.md#workflow). Available actions and statuses are:
* user's actions: `ANALYSE`, `START` and `STOP`.
* request statuses: `CREATED`, `ANALYSING`, `ANALYSIS_DONE`, `STOPPED`, `PROCESSING`, `DONE`, and `FAILED`.
The Batch Statistical API comes with a set of REST actions that support the execution of various steps in the workflow. The diagram below shows all possible statuses of the Batch Statistical request and users' actions that trigger transitions among them.
The workflow starts when you post a new Batch Statistical request. In this step, the system:
* creates a new Batch Statistical request with status `CREATED`,
* validates your input (not the evalscript),
* returns the overview of the created request.
You can then decide to either request an additional analysis of the request or start the processing. When an additional analysis is requested:
* the status of the request changes to `ANALYSING`,
* the evalscript is validated,
* After the analysis is finished, the status of the request changes to `ANALYSIS_DONE`.
If you choose to start processing directly, the system still executes the analysis, but when the analysis is done, it automatically starts processing. This is not explicitly shown in the diagram to keep it simple.
When you start the processing:
* the status of the request changes to `PROCESSING` (this may take a while),
* the processing starts,
* spent processing units are billed periodically.
When the processing finishes, the status of the request changes to `DONE`.
#### Stopping the request
A request might be stopped for the following reasons:
* it is requested by a user (user action)
* user is out of processing units (see chapter below)
* something is wrong with the processing of the request
A user may stop the request in the following states: `ANALYSING`, `ANALYSIS_DONE`, and `PROCESSING`. However:
* if the status is `ANALYSING`, the analysis will complete
* if the status is `PROCESSING`, all features (polygons) that have been processed or are being processed at that moment are charged for
* you are not allowed to restart the request in the next 30 minutes
The service itself may also stop the request when processing of a lot of features is repeatedly failing. `stoppedStatusReason` of such requests will be `UNHEALTHY`. This can happen if the service is unstable or if something is wrong with the request. If the former, the request should eventually be restarted by our team.
#### Processing unit costs
To create, analyse, or initiate a request, the user must have at least 1000 processing units available in their account. If available processing units of a user drop below `1000` while the request is being processed, the request is automatically stopped and cannot be restarted in the next 60 minutes. Therefore, it is highly recommended to start a request with a sufficient reserve.
More information about batch statistical costs is available [here](https://docs.planet.com/platform/processing-units.md#batch-statistical-api).
#### Automatic deletion of stale data
Stale (inactive) requests will be deleted after a specific period of inactivity, depending on their status:
* requests with status `CREATED` are deleted after 7 days of inactivity
* requests with status `FAILED` are deleted after 15 days of inactivity
* all other requests are deleted after 30 days of inactivity
note
Note that only such requests themselves will be deleted, while the requests' result (created statistics) will remain under your control in your object storage bucket.
## Input Polygons as a GeoPackage File
The Batch Statistical API accepts a [GeoPackage file](https://www.geopackage.org/) containing features (polygons) as an input. The GeoPackage must be stored in your object storage and must be accessible to the service for reading (find more details about this in the [object storage configuration](#object-storage-configuration) section below). In a batch statistical request, the input GeoPackage is specified by setting the path to the `.gpkg` file in the `input.features.s3` or `input.features.gs` parameter.
All features (polygons) in an input GeoPackage must be in the same CRS [supported by us](https://docs.planet.com/develop/apis/processing.md#crs-support). There can be a maximum of 700,000 features in the GeoPackage.
## Evalscript and Batch Statistical API
The exact specifics as described for [evalscript and Statistical API](https://docs.planet.com/develop/apis/statistical.md#statistical-api-and-evalscripts) also apply to the Batch Statistical API.
Evalscripts smaller than 32KB in size can be provided directly in a batch statistical request under `evalscript` parameter. If your evalscript exceeds this limit, you can store it in your object storage bucket and provide a reference to it in a batch statistical request under the `evalscriptReference` parameter.
## Processing Results
Outputs of a Batch Statistical API request are JSON files stored in your object storage. Each `.json` file will contain the requested statistics for one feature (polygon) in the provided GeoPackage. You can connect statistics in a JSON file with the corresponding feature (polygon) in the GeoPackage based on:
* `id` of a feature from GeoPackage is used as the name of the JSON file (for example, `1.json`, `2.json`) and available in the JSON file as `id` property OR
* a custom column `identifier` of type string can be added to GeoPackage and its value will be available in json file as `identifier` property
The outputs will be stored in the bucket and the folder specified by `output.s3.url` or `output.gs.url` parameter of the batch statistical request. The URL supports templating with placeholders like ``, ``, and `` to customize output file organization (see [API Reference](https://docs.planet.com/develop/apis/batch-statistical/reference.md) for details). The outputs will be available in a sub-folder named after the ID of your request (for example, `s3://{bucket}/{my-folder}/db7de265-dfd4-4dc0-bc82-74866078a5ce`).
## Object Storage Configuration
The Batch Statistical API requires access to object storage for reading input data and storing processing results. We support two object storage providers:
* **Amazon S3**
* **Google Cloud Storage (GCS)**
### Supported Use Cases
Object storage is used for:
* Reading GeoPackage files with input features (polygons)
* Reading evalscript files (optional, evalscripts can also be provided directly in the request)
* Uploading processing results (JSON files with statistics)
One bucket or different buckets can be used for all three purposes.
### AWS S3 Configuration
The Batch Statistical API supports two authentication methods for AWS S3. **We recommend using the IAM Assume Role method** for enhanced security and fine-grained access control.
#### Authentication Methods
##### Option 1: IAM Assume Role (Recommended)
The IAM Assume Role method provides better security by allowing temporary credentials and fine-grained access control without exposing long-term credentials.
To use this method, provide the ARN of an IAM role that has access to your S3 bucket:
```
{
"output": {
"s3": {
"url": "s3://{bucket}/{key}",
"region": "{region}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
```
**Setup Steps:**
1. **Create an IAM Policy for S3 Access**
Create a policy that grants the necessary permissions to your S3 bucket:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": ["arn:aws:s3:::{bucket}", "arn:aws:s3:::{bucket}/*"]
}
]
}
```
2. **Create an IAM Role**
* In the AWS IAM console, create a new role
* Choose "AWS account" as the trusted entity type
* Select "Another AWS account" and enter account ID: `614251495211`
* Attach the policy created in step 1
* Note the Role ARN for use in your API requests
3. **Configure Trust Relationship (Optional but Recommended)**
For additional security, modify the role's trust policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::614251495211:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{domain-account-id}"
},
"StringLike": {
"sts:RoleSessionName": "sentinelhub"
}
}
}
]
}
```
Replace `{domain-account-id}` with your domain account ID from the [Dashboard](https://insights.planet.com/account/#/).
##### Option 2: Access Key & Secret Key
Alternatively, you can provide AWS access credentials directly:
```
{
"output": {
"s3": {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key}",
"secretAccessKey": "{secret-access-key}",
"region": "{region}"
}
}
}
```
The access key and secret must be linked to an IAM user with the following permissions on your S3 bucket:
* `s3:GetObject`
* `s3:PutObject`
* `s3:DeleteObject`
* `s3:ListBucket`
To create access keys, see the [AWS documentation on programmatic access](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html).
#### Using S3 Configuration in Requests
The S3 configuration can be used in:
* `input.features.s3` - to specify the bucket where the GeoPackage file is available (required)
* `evalscriptReference.s3` - to specify the bucket where the evalscript .js file is available (optional)
* `output.s3` - to specify the bucket where the results will be stored (required)
Check [Batch Statistical API reference](https://docs.planet.com/develop/apis/batch-statistical/reference.md) for more information.
### Google Cloud Storage Configuration
Google Cloud Storage is supported for GeoPackage input, evalscript input, and output delivery. Authentication requires a service account with base64-encoded credentials.
#### Preparing Credentials
1. Download your service account credentials in JSON format (not P12)
2. Encode them as a base64 string:
```
cat my_creds.json | base64
```
#### Using GCS for Input
To read a GeoPackage or evalscript from Google Cloud Storage:
```
{
"input": {
"features": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
}
```
#### Using GCS for Output
To deliver results to Google Cloud Storage:
```
{
"output": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
```
#### Required GCS Permissions
The service account must have the following permissions on the specified bucket:
* `storage.objects.create`
* `storage.objects.get`
* `storage.objects.delete`
* `storage.objects.list`
These permissions can be granted through IAM roles such as `Storage Object Admin` or custom roles. If possible, restrict access to the specific delivery path within the bucket for enhanced security.
### Cross-Cloud and Cross-Region Support
The Batch Statistical API provides complete flexibility in choosing storage locations for both input and output. Surcharges apply based on where your **processing results are delivered** (output storage location).
#### Storage Configuration Options
The table below shows output storage options for each deployment and their associated costs. Surcharges apply only to the volume of output data transferred to your storage.
**Important:** Input and output storage can be configured independently - you can mix and match any combination. For example, you can read input from GCS and write output to S3, or read from S3 in one region and write to S3 in another region. Input storage location does not affect costs.
| Deployment | Region | Output Storage Location | Additional PU Cost |
| ------------------ | ------------ | ----------------------- | ------------------ |
| AWS EU (Frankfurt) | eu-central-1 | S3 eu-central-1 | None |
| AWS EU (Frankfurt) | eu-central-1 | S3 (any other region) | 0.03 PU/MB |
| AWS EU (Frankfurt) | eu-central-1 | Google Cloud Storage | 0.1 PU/MB |
**Output Data Transfer Surcharges Summary:**
* Cross-region (same cloud): 0.03 PU per MB
* Cross-cloud: 0.1 PU per MB
**Important Notes:**
* Surcharges apply only to output data transfer (processing results)
* Input location (GeoPackage and evalscript files) does not affect costs
* When using an AWS S3 bucket in a different region than the deployment, specify the `region` parameter in your request:
```
{
"output": {
"s3": {
"url": "s3://{bucket}/{key}",
"region": "{region}",
"iamRoleARN": "{IAM-role-ARN}"
}
}
}
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-statistical/examples/)
# Examples of Batch Statistical Workflow
The requests below are written in Python. To execute them, you need to create an OAuth client as is explained [here](https://docs.planet.com/develop/authentication.md#sentinel-hub-authentication). It is named `oauth` in these examples.
## Create a Batch Statistical Request
This request defines which data is requested and how it will be processed. In this example, we will receive the statistics for a single band on a given day. To create a batch statistical request, replace the `input.features.s3.url` field with the actual path to the GeoPackage features, and the `output.s3.url` field with the desired path where the output data will be processed.
* Python SDK
```
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: [
"B04",
"dataMask"
]
}],
output: [
{
id: "output_B04",
bands: 1,
sampleType: "FLOAT32"
},
{
id: "dataMask",
bands: 1
}]
}
}
function evaluatePixel(samples) {
return {
output_B04: [samples.B04],
dataMask: [samples.dataMask]
}
}
"""
request_payload = {
"input": {
"features":{
"s3": {
"url": "s3://{bucket}/{path-to-geopackage}",
"accessKey": "{access-key},
"secretAccessKey": "{secret-access-key}
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"mosaickingOrder": "leastCC"
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2020-06-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"aggregationInterval": {
"of": "P30D"
},
"evalscript": evalscript,
"resx": 10,
"resy": 10
},
"output": {
"s3": {
"url": "s3://{bucket}/{key}",
"accessKey": "{access-key},
"secretAccessKey": "{secret-access-key}
}
}
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
url = "https://services.sentinel-hub.com/statistics/batch/v1"
response = oauth.request("POST", url=url, headers=headers, json=request_payload)
request_id = response.json()['id']
```
Note that in the above example, we are specifying an `accessKey` and `secretAccessKey`, so we can read and write to the user's bucket. You can find more details about this under the [Object Storage Configuration section](https://docs.planet.com/develop/apis/batch-statistical.md#object-storage-configuration).
## Create a Batch Statistical Request with Google Storage
This example demonstrates how to use Google Cloud Storage for both GeoPackage input and delivery of results instead of S3.
* Python SDK
```
evalscript = """
//VERSION=3
function setup() {
return {
input: [{
bands: [
"B04",
"dataMask"
]
}],
output: [
{
id: "output_B04",
bands: 1,
sampleType: "FLOAT32"
},
{
id: "dataMask",
bands: 1
}]
}
}
function evaluatePixel(samples) {
return {
output_B04: [samples.B04],
dataMask: [samples.dataMask]
}
}
"""
request_payload = {
"input": {
"features":{
"gs": {
"url": "gs://{bucket}/{path-to-geopackage}",
"credentials": "{base64-encoded-credentials}"
}
},
"data": [
{
"type": "sentinel-2-l2a",
"dataFilter": {
"mosaickingOrder": "leastCC"
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2020-06-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"aggregationInterval": {
"of": "P30D"
},
"evalscript": evalscript,
"resx": 10,
"resy": 10
},
"output": {
"gs": {
"url": "gs://{bucket}/{key}",
"credentials": "{base64-encoded-credentials}"
}
}
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
url = "https://services.sentinel-hub.com/statistics/batch/v1"
response = oauth.request("POST", url=url, headers=headers, json=request_payload)
request_id = response.json()['id']
```
To prepare your Google Cloud Storage credentials, download your service account credentials in JSON format and encode them as base64:
* CURL
```
cat my_creds.json | base64
```
Replace `{base64-encoded-credentials}` with the output of this command in both the input and output sections of your request.
### Get Information About a Batch Statistical Request
* Python SDK
```
response = oauth.request("GET", f"https://services.sentinel-hub.com/statistics/batch/v1/{request_id}")
response.json()
```
### Get Status Information About a Batch Statistical Request
* Python SDK
```
response = oauth.request("GET", f"https://services.sentinel-hub.com/statistics/batch/v1/{request_id}/status")
response.json()
```
### Request Analysis of a Batch Statistical Request (ANALYSIS)
* Python SDK
```
response = oauth.request("POST", f"https://services.sentinel-hub.com/statistics/batch/v1/{request_id}/analyse")
response.status_code
```
### Request the Start of a Batch Statistical Request (START)
* Python SDK
```
response = oauth.request("POST", f"https://services.sentinel-hub.com/statistics/batch/v1/{request_id}/start")
response.status_code
```
### Stop a Batch Statistical Request (STOP)
* Python SDK
```
response = oauth.request("POST", f"https://services.sentinel-hub.com/statistics/batch/v1/{request_id}/stop")
response.status_code
```
---
Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/batch-statistical/reference/)
# Batch Statistical API Reference
* Batch Stats API
* Statistical
* postSubmit a new statistical batch request
* getQuery statistical batch requests
* getRetrieve a single batch statistical request
* getRetrieve the status of a batch statistical request.
* postRequest analysis of a batch statistical request
* postStart (confirm) processing of a batch statistical request
* postStop a batch statistical request
[API docs by Redocly](https://redocly.com/redoc/)
# API Reference (1.0.0)
Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/sh-prod-batch-statistical-api-spec.yaml)
## [](#tag/batch_statistical)Statistical
## [](#tag/batch_statistical/operation/createNewBatchStatisticsRequest)Submit a new statistical batch request
##### Authorizations:
*OAuth2*
##### Request Body schema:application/jsonapplication/json
| | |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inputrequired | object (BatchStatisticalInput) |
| aggregationrequired | object (BatchStatisticalRequestAggregation)Specifies how data is aggregated and processed before statistics is calculated. `timeRange` and `aggregationInterval` combined define sampling intervals in time dimension. Width/height or resx/resy combined with `input.bounds` define a sample matrix (i.e. "image") in spatial dimension. |
| calculations | object (StatisticalRequestCalculations)Define which statistics and histogram to calculate. It can be specified differently for each evalscript output. If omitted only the basic statistic (min, max, mean, stDev) will be calculated. |
| outputrequired | S3BucketInfoTemplated (object) or GSBucketInfoTemplated (object) (ObjectStorageOutputInfoV2) |
### Responses
**201**
Request submitted
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
post/statistics/batch/v1
https\://services.sentinel-hub.com/statistics/batch/v1
### Request samples
* Payload
Content type
application/jsonapplication/json
Copy
Expand all Collapse all
`{
"input": {
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2019-08-24T14:15:22Z",
"to": "2019-08-24T14:15:22Z"
},
"aggregationInterval": {
"of": "string",
"lastIntervalBehavior": "SKIP"
},
"width": 512,
"height": 512,
"resx": 0.1,
"resy": 0.1,
"evalscript": "string",
"evalscriptReference": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"calculations": {
"output name1": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
},
"output name2": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
}
},
"output": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
}`
### Response samples
* 201
* 400
Content type
application/json
Copy
Expand all Collapse all
`{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "CREATED",
"error": "string",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"created": "2019-08-24T14:15:22Z",
"stoppedStatusReason": "OUT_OF_PU",
"request": {
"input": {
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2019-08-24T14:15:22Z",
"to": "2019-08-24T14:15:22Z"
},
"aggregationInterval": {
"of": "string",
"lastIntervalBehavior": "SKIP"
},
"width": 512,
"height": 512,
"resx": 0.1,
"resy": 0.1,
"evalscript": "string",
"evalscriptReference": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"calculations": {
"output name1": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
},
"output name2": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
}
},
"output": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c"
}`
## [](#tag/batch_statistical/operation/searchBatchStatisticsRequests)Query statistical batch requests
##### Authorizations:
*OAuth2*
##### query Parameters
| | |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count | integer \Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use *viewtoken* to page through. |
| viewtoken | stringWhen the total number of items is larger than *count*, the response contains *viewtoken*. This *viewtoken* can be used in the next request to retrieve the next page of items.The next page can be retrieved by repeating the query. However, replace your URL with the next URL in the returned links object. |
| sort | stringEnum: "created" "created:desc" "status" "status:desc"Sort the statistical batch requests by given field. Omit for default ordering. |
### Responses
**200**
Successful response
**401**
Unauthorized
**403**
Insufficient permissions
get/statistics/batch/v1
https\://services.sentinel-hub.com/statistics/batch/v1
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{
"data": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "CREATED",
"error": "string",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"created": "2019-08-24T14:15:22Z",
"stoppedStatusReason": "OUT_OF_PU",
"request": {
"input": {
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2019-08-24T14:15:22Z",
"to": "2019-08-24T14:15:22Z"
},
"aggregationInterval": {
"of": "string",
"lastIntervalBehavior": "SKIP"
},
"width": 512,
"height": 512,
"resx": 0.1,
"resy": 0.1,
"evalscript": "string",
"evalscriptReference": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"calculations": {
"output name1": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
null
]
}
},
"band name2": {
"percentiles": {
"k": [
null
]
}
}
}
},
"output name2": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
null
]
}
},
"band name2": {
"percentiles": {
"k": [
null
]
}
}
}
}
},
"output": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c"
}
],
"links": {
"currentToken": "string",
"nextToken": "string",
"previousToken": "string",
"@id": "http://example.com",
"next": "http://example.com",
"previous": "http://example.com"
}
}`
## [](#tag/batch_statistical/operation/getSingleBatchStatisticalRequestById)Retrieve a single batch statistical request
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| ----------------- | ------------------------ |
| requestIdrequired | string \Request ID |
### Responses
**200**
Successful response
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
get/statistics/batch/v1/{requestId}
https\://services.sentinel-hub.com/statistics/batch/v1/{requestId}
### Response samples
* 200
* 404
Content type
application/json
Copy
Expand all Collapse all
`{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "CREATED",
"error": "string",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"created": "2019-08-24T14:15:22Z",
"stoppedStatusReason": "OUT_OF_PU",
"request": {
"input": {
"features": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
},
"data": [
{
"type": "sentinel-2-l1c",
"id": "string",
"dataFilter": {
"timeRange": {
"from": "2018-10-01T00:00:00.000Z",
"to": "2018-11-01T00:00:00.000Z"
},
"mosaickingOrder": "mostRecent",
"maxCloudCoverage": 100
},
"processing": {
"upsampling": "NEAREST",
"downsampling": "NEAREST",
"harmonizeValues": true
}
}
]
},
"aggregation": {
"timeRange": {
"from": "2019-08-24T14:15:22Z",
"to": "2019-08-24T14:15:22Z"
},
"aggregationInterval": {
"of": "string",
"lastIntervalBehavior": "SKIP"
},
"width": 512,
"height": 512,
"resx": 0.1,
"resy": 0.1,
"evalscript": "string",
"evalscriptReference": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"calculations": {
"output name1": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
},
"output name2": {
"histograms": {
"band name1": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
},
"band name2": {
"nBins": 0,
"binWidth": 0,
"lowEdge": 0,
"highEdge": 0,
"bins": [
0
]
}
},
"statistics": {
"band name1": {
"percentiles": {
"k": [
1
]
}
},
"band name2": {
"percentiles": {
"k": [
1
]
}
}
}
}
},
"output": {
"s3": {
"url": "string",
"iamRoleARN": "string",
"accessKey": "string",
"secretAccessKey": "string",
"region": "string"
}
}
},
"userAction": "NONE",
"userActionUpdated": "2019-08-24T14:15:22Z",
"domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19",
"projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
"workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c"
}`
## [](#tag/batch_statistical/operation/batchStatisticalGetStatus)Retrieve the status of a batch statistical request.
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| ----------------- | ------------------------ |
| requestIdrequired | string \Request ID |
### Responses
**200**
Successful response
**400**
Bad request
**401**
Unauthorized
**403**
Insufficient permissions
**404**
Not found
get/statistics/batch/v1/{requestId}/status
https\://services.sentinel-hub.com/statistics/batch/v1/{requestId}/status
### Response samples
* 200
* 400
* 404
Content type
application/json
Copy
`{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "CREATED",
"error": "string",
"completionPercentage": 0,
"lastUpdated": "2019-08-24T14:15:22Z",
"costPU": 0,
"costMC": 0,
"created": "2019-08-24T14:15:22Z",
"stoppedStatusReason": "OUT_OF_PU"
}`
## [](#tag/batch_statistical/operation/batchStatisticalAnalyse)Request analysis of a batch statistical request
##### Authorizations:
*OAuth2*
##### path Parameters
| | |
| ----------------- | ------------------------ |
| requestIdrequired | string \