Skip to main content

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 Basemap 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 Basemaps Data 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 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.

Last updated on