Item Previews

last updated: May 23, 2024

Thumbnails

The Data API provides previews of Planet imagery data as thumbnails. A thumbnail is a down-sampled PNG version of an item's visual asset that can be used as a preview of the image without needing to download a full GeoTIFF. The thumbnail URL is advertised by the key thumbnail in the _links dictionary of an item's metadata. To see an example, inspect the response of https://api.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72.

"_links": {
  "_self": "https://api.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72",
  "assets": "https://api.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/assets/"
  "thumbnail": "https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb"
}

Size

The thumbnail by default is 256×256 pixels, and can be scaled up to 512×512 by passing in the width parameter and setting it to values up to 512. If you have download access to the visual asset, you can scale the thumbnail higher by setting the width parameter to a maximum of 2048.

Adjusting the Width of a Thumbnail

To adjust the width of a thumbnail, add the ?width= parameter to the thumbnail URL. Here is how you can scale a thumbnail to 512 pixels:

"https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb?width=512"

You can scale the thumbnail up to a maximum width of 2048 pixels.

Authentication

Authentication for thumbnails can be done with basic HTTP or by providing an api_key parameter to the URL.

Example of Authentication using HTTP

To authenticate using HTTP, you can use this curl command:

"curl -u YOUR_API_KEY:X https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb"

Ensure to replace YOUR_API_KEY with your Planet API key.

Example of Authenticating using an api_key Parameter

To authenticate with your API key directly in the URL, you can append the api_key parameter to the thumbnail URL.

"https://tiles.planet.com/data/v1/item-types/PSScene/items/20160223_174714_0c72/thumb?api_key=YOUR_API_KEY"

Ensure to replace YOUR_API_KEY with your Planet API key.


Rate this guide: