Repository: planetlabs/planet-client-python

Issue:
Add Sentinel-2 to Harmonization tool
**Is your feature request related to a problem? Please describe.**
Our SDK only allows data harmonization with Dove Classic, however the [openAPI spec ](https://developers.planet.com/apis/orders/reference/#tag/Orders/operation/createOrder) has added Sentinel-2 as a target sensor for harmonization.

I propose we add Sentinel-2 as an option for harmonization to the Orders API.

**Describe the solution you'd like**

Current [harmonization tool](https://github.com/planetlabs/planet-client-python/blob/main/planet/order_request.py#L432):
```
def harmonize_tool() -> dict:
    '''Create the API spec representation of a harmonize tool.

    Currently, only "PS2" (Dove Classic) is supported as a target sensor, and
    it will transform only items captured by “PS2.SD” (Dove-R).
    '''
    return _tool('harmonize', {'target_sensor': 'PS2'})
```

Proposed solution:
```
def harmonize_tool(target_sensor: str) -> dict:
    '''Create the API spec representation of a harmonize tool.

    Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as 
    target sensors. Dove-R can only be transformed by PS2 and Sentinel-2 can 
    only transform surface reflectance bundles for PSScene 
    (ie., analytic_8b_sr_udm2, analytic_sr_udm2).
    '''
    return _tool('harmonize', {'target_sensor': target_sensor})
```

I also suggest adding a test for hamonization in `tests/unit/test_order_request.py`:
```
@pytest.mark.parametrize("target_sensor", ["PS2", "Sentinel-2"])
def test_harmonization_tool(target_sensor):
    ht = order_request.harmonize_tool(target_sensor)
    expected = {'harmonize': {'target_sensor': target_sensor}}
    assert ht == expected
```

**Additional context**
I would double check the sensor harmonization compatibility on the [Dev Center](https://developers.planet.com/apis/orders/tools/#harmonization).


Discussion:

Patch:
diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md
index 7804dff..f2561c7 100644
--- a/docs/cli/cli-orders.md
+++ b/docs/cli/cli-orders.md
@@ -467,7 +467,23 @@ curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/d
 
 ### Harmonize
 
-TODO
+The harmonize tool allows you to compare data to different generations of satellites by radiometrically harmonizing imagery captured by one satellite instrument type to imagery captured by another. To harmonize your data to a sensor you must define the sensor you wish to harmonize with in your `tools.json`. Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as target sensors. The Sentinel-2 target only harmonizes PSScene surface reflectance bundle types (`analytic_8b_sr_udm2`, `analytic_sr_udm2`). The PS2 target only works on analytic bundles from Dove-R (`PS2.SD`).
+
+```json
+[
+  {
+    "harmonize": {
+      "target_sensor": "Sentinel-2"
+      }
+    }
+]
+```
+
+You may create an order request by calling `tools.json` with `--tools`.
+
+```console
+planet orders request psscene analytic_sr_udm2 --name "Harmonized data" --id 20200925_161029_69_2223 --tools tools.json
+```
 
 ### STAC Metadata
 
diff --git a/planet/order_request.py b/planet/order_request.py
index 34b4cbb..586c44f 100644
--- a/planet/order_request.py
+++ b/planet/order_request.py
@@ -429,10 +429,12 @@ def toar_tool(scale_factor: Optional[int] = None, ) -> dict:
     return _tool('toar', parameters)
 
 
-def harmonize_tool() -> dict:
+def harmonize_tool(target_sensor: str) -> dict:
     '''Create the API spec representation of a harmonize tool.
 
-    Currently, only "PS2" (Dove Classic) is supported as a target sensor, and
-    it will transform only items captured by “PS2.SD” (Dove-R).
+    Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as
+    target sensors. The Sentinel-2 target only harmonizes PSScene
+    surface reflectance bundle types (analytic_8b_sr_udm2, analytic_sr_udm2).
+    The PS2 target only works on analytic bundles from Dove-R (PS2.SD).
     '''
-    return _tool('harmonize', {'target_sensor': 'PS2'})
+    return _tool('harmonize', {'target_sensor': target_sensor})


Test patch:
diff --git a/tests/unit/test_order_request.py b/tests/unit/test_order_request.py
index 0163357..49e3554 100644
--- a/tests/unit/test_order_request.py
+++ b/tests/unit/test_order_request.py
@@ -251,3 +251,10 @@ def test_toar_tool():
     tt_empty = order_request.toar_tool()
     expected_empty = {'toar': {}}
     assert tt_empty == expected_empty
+
+
+@pytest.mark.parametrize("target_sensor", ["PS2", "Sentinel-2"])
+def test_harmonization_tool(target_sensor):
+    ht = order_request.harmonize_tool(target_sensor)
+    expected = {'harmonize': {'target_sensor': target_sensor}}
+    assert ht == expected