PSScene3Band and PSScene4Band Deprecation and Migration Plan

last updated: November 10, 2022

Deprecation Announced: March 1, 2022

Scheduled End-of-Life: January 31, 2023

This article describes the deprecation of the PSScene3Band and PSScene4Band item types.

What’s changing?

Planet is deprecating PSScene3Band and PSScene4Band item types on Tuesday, March 1, 2022 with plans to formally end-of-life the item types on Tuesday, January 31, 2023. We recommend all customers begin to migrate to the PSScene item type as soon as possible. The PSScene item type provides the same PlanetScope 3-band and 4-band items as PSScene3Band and PSScene4Band item types, but allows users to search one item type for all available 3-band, 4-Band, and 8-Band assets.

Planet will continue to publish imagery to the PSScene3Band and PSScene4Band item types until January 31, 2023. After January 31, 2023, Planet will no longer publish images to the PSScene3Band and PSScene4Band item types and will remove the ability to access these item types from the Data API, Orders API, Subscriptions API, SDK/CLI, and Planet Jupyter Notebooks. If API requests contain these item types, they will respond with a failure 400 error code.

We highly recommend that PSScene3Band and PSScene4Band item type users plan their transition to using PSScene as soon as possible to ensure there is minimal disruption to workflows.

Why is Planet removing PSScene3Band and PSScene4Band?

We are deprecating the PSScene3Band and PSScene4Band to improve the way customers access our PlanetScope imagery. We recommend customers to take advantage of PSScene, our new PlanetScope item type that unifies 3-Band, 4-Band, and 8-Band assets.

Am I affected?

This deprecation announcement affects all users accessing PlanetScope imagery from the PSScene3Band and PSScene4Band item types through Planet Data API, Orders API, Subscriptions API, SDK/CLI, and Planet Jupyter Notebooks.

What happens after January 31, 2023?

API requests with the PSScene3Band and PSScene4Band item and asset types will fail after January 31, 2023 when we remove these item types.

Who should I contact if I have questions or concerns about PSScene migration?

Please reach out to your Customer Success Manager or contact us at Planet Support for assistance.

What do I need to do?

To prepare for this release, we have provided a migration path that includes both automatic updates to existing saved search and subscriptions, as well as instructions for how to migrate your requests. Review the following top-level table, then step through the Migration Path, below.

API What Action Customers Need to Take
All Review the mapping between PSScene3Band and PSScene4Band asset types to understand the corresponding PSScene asset types.

Review how Planet intends to migrate customers with existing saved searches and subscriptions in October 2022.
Data API Update new quick and saved searches to use the PSScene item type. If applicable, adjust AssetFilter to use PSScene Asset Types.
Orders API Identify the appropriate PSScene bundle, and update order requests to use the PSScene item_type and bundle.

If an approximate Sentinel-2 spectral response is desired, use the new harmonization target sensor when using data from all Doves. Read more.
Subscriptions API Identify the appropriate PSScene Asset Types.

Create new subscriptions with the PSScene item_type and asset_types, and cancel existing subscriptions for the same AOI. (You cannot edit an item_type of an existing subscription.)

If an approximate Sentinel-2 spectral response is desired, use the new harmonization target sensor when using data from all Doves. Read more.

Migration Path

If you would like to use or maintain any requests or code that uses PlanetScope imagery, your migration path is as follows:

  1. Prepare for Planet-initiated automated tasks that will convert most saved searches and subscriptions to new PSScene assets.
  2. Review your saved searches and subscriptions for asset types that do not map directly to PSScene assets.
  3. Update Order API requests to use PSScene bundle types.

Unsupported asset types in PSScene

The following assets are unavailable with PSScene:

  • PSScene3Band: analytic_dn, analytic_dn_xml, basic_analytic, basic_analytic_dn, basic_analytic_dn_rpc, basic_analytic_dn_xml, basic_analytic_rpc, basic_analytic_xml, basic_udm, udm, visual_xml
  • PSScene4Band: analytic_dn, analytic_dn_xml, basic_analytic_dn, basic_analytic_dn_nitf, basic_analytic_dn_rpc, basic_analytic_dn_rpc_nitf, basic_analytic_dn_xml, basic_analytic_dn_xml_nitf, basic_analytic_nitf, basic_analytic_rpc_nitf, basic_analytic_xml_nitf, basic_udm, udm

Note

NITF assets are available by using the Orders API “File Format” Tool.

Prepare for Planet-initiated automated tasks

Your saved searches and subscription requests may include the PSScene3Band and PSScene4Band item types and assets. Most of these requests have assets that map to PSScene assets. Some assets do not map directly to a PSScene asset. For the requests that map directly to a PSScene asset, Planet will conduct a conversion in the background, as follows.

On October 31, 2022, Planet will remove the ability to create new saved searches and subscriptions with PSScene3Band and PSScene4Band item and asset types. We will migrate existing subscriptions to use PSScene in the background on the week of November 14. We will migrate existing saved searches in the background the week of November 28th. After the migration is complete, the results of these saved searches and subscriptions will return corresponding PSScene assets, where possible.

Behind the scenes, Planet will change item_type to PSScene. The following table shows the map Planet will use to convert asset types:

PSscene3Band Assets PSScene Assets
visual → ortho_visual
analytic → ortho_analytic_3b
analytic_xml → ortho_analytic_3b_xml
PSscene4Band Assets PSScene Assets
analytic → ortho_analytic_4b
analytic_sr → ortho_analytic_4b_sr
analytic_xml → ortho_analytic_4b_xml
basic_analytic → basic_analytic_4b
basic_analytic_rpc → basic_analytic_4b_rpc
basic_analytic_xml → basic_analytic_4b_xml
basic_udm2 → basic_udm2
udm2 → ortho_udm2

December 6 Maintenance Window

Date/Time of Impact
from December 6, 2022 20:00 UTC to December 7, 2022 20:00 UTC
Date/Time of Expected End
December 7, 2022 20:00 UTC
Product(s) or Data Impacted
PSScene3Band and PSScene4Band item types

What to expect

On Tuesday, December 6, 2022, 20:00 UTC, for 24 hours, Planet will conduct a maintenance window of planned unavailability of the item types PSScene3Band and PSScene4Band. PSScene3Band and PSScene4Band will be unavailable to customers for 24 hours.

  • Customers will be unable to access PSScene3Band and PSScene4Band item types in our viewers, such as Planet Explorer.
  • API, SDK, and CLI users will be unable to search or create orders or download data using PSScene3Band and PSScene4Band item types.

Your action

PSScene3Band and PSScene4Band item types will be unavailable for use, so you should plan to use the PSScene item type during this time period.

For more information continue reading the next section Create new saved searches and subscriptions.

Create new saved searches and subscriptions

Before October 31, 2022, create new saved searches and subscriptions using the PSScene item type.

For the assets that are not supported by PSScene (see list), Planet will be unable to automatically migrate saved searches and subscriptions using these assets. You will be unable to use these assets after the January 31, 2023 end-of-life date of PSScene3Band and PSScene4Band.

Review your saved searches

  1. Get your saved searches, either by selecting your saved searches in the Explorer or through the API.
  2. Cancel any saved searches you no longer need.
  3. Review remaining saved searches for unsupported asset types.
  4. For each saved search that contains an unsupported asset type, create a new saved search using the PSScene item type and comparable asset type by choosing to:
  5. Delete the saved search that contained the unsupported asset type.

Review your subscriptions

  1. Get your subscriptions by listing all active subscriptions through the API.
  2. Cancel any subscriptions you no longer need.
  3. Review remaining subscriptions for unsupported asset types.
  4. For each subscription that contains an unsupported asset type, create a new subscription using the PSScene item type and comparable asset type in the Subscription API.
  5. Cancel the subscription that contained the unsupported asset type through the Subscriptions API.

Before January 31, 2023, update Orders API to use the PSScene item type.

Update Order API requests to use PSScene bundle types

  1. Change all references from PSScene3Band and PSScene4Band item types to PSScene in the Order API request.
  2. For any PSScene3Band item types, search for the analytic bundle type and replace it with the analytic_3b_udm2 bundle.
  3. For any PSScene4Band item types, search for the analytic bundle type and replace it with the analytic_udm2 bundle.
  4. Finally, review all code repositories where you may be making calls using the deprecated item and asset types.

The following table assists in reviewing the new asset types for the updated bundles. The first column lists the legacy bundle types, PSScene3Band or PSScene4Band, the middle column lists the comparable PSScene bundle type, and the last column lists the new asset types for PSScene.

PSScene3Band Bundle PSScene Bundle PSScene Assets in Bundle
visual → visual (no change) ortho_visual
analytic → analytic_3b_udm2 ortho_analytic_3b
ortho_analytic_3b_xml
ortho_udm2
PSScene4Band Bundle PSScene Bundle PSScene Assets in Bundle
analytic → analytic_udm2 ortho_analytic_4b
ortho_analytic_4b_xml
ortho_udm2
analytic_udm2 → analytic_udm2 (no change) ortho_analytic_4b
ortho_analytic_4b_xml
ortho_udm2
analytic_sr_udm2 → analytic_sr_udm2 (no change) ortho_analytic_4b_sr
ortho_analytic_4b_xml
ortho_udm2
basic_analytic_udm2 → basic_analytic_udm2 (no change) basic_analytic_4b
basic_udm2 (no change)
basic_analytic_4b_rpc
basic_analytic_4b_xml

Update workflow for deprecated PlanetScope metadata

To simplify the API, scarcely used metadata previously available from PSScene3Band and PSScene4Band API calls are unavailable through PSScene. These scene property metadata can be derived from the GeoTIFF header. On the rare occasion where you may have retrieved these metadata through the API, update your workflow to retrieve these values directly from the GeoTIFF header or STAC metadata, as in the following table.

Deprecated Attribute Description Using the GeoTIFF Header Using STAC Metadata
epsg_code Ortho tile grid cell that the item is located in (not used if asset is a scene). The epsg_code can be found under the coordinate system in the GeoTIFF header. The epsg_code is included in the proj:epsg attribute in the STAC metadata.
columns Number of columns in the image. We recommend leveraging the pixel size in the GeoTIFF header instead. We recommend using the proj:transform matrix or the bbox and pixel size instead.
rows Number of rows in the image. We recommend leveraging the pixel size in the GeoTIFF header instead. We recommend using the proj:transform matrix or the bbox and pixel size instead.
origin_x ULX coordinate of the extent of the data. The coordinate references the top left corner of the top left pixel. origin_x is under the origin or corner coordinates. origin_x is in the first coordinates from the bbox or proj:transform array in position 2.
origin_y ULY coordinate of the extent of the data. The coordinate references the top left corner of the top left pixel. origin_y is under the origin or corner coordinates. origin_y is in the first coordinates from the bbox or proj:transform array in position 5.

Rate this guide: