diff --git a/docs/python/sdk-guide.md b/docs/python/sdk-guide.md index 70ea5bbc..5dcd71c3 100644 --- a/docs/python/sdk-guide.md +++ b/docs/python/sdk-guide.md @@ -231,6 +231,8 @@ You will need your ACCESS_KEY_ID, SECRET_ACCESS_KEY, bucket and region name. To subscribe to scenes that match a filter, use the `subscription_request` module to build a request, and pass it to the `subscriptions.create_subscription()` method of the client. +By default, a request to create a subscription will not clip matching imagery which intersects the source geometry. To clip to the subscription source geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = True` as in the example below. To clip to a custom geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = False` (or omit it entirely to fall back on the default value), and instead configure the custom clip AOI with `planet.subscription_request.clip_tool()`. + Warning: the following code will create a subscription, consuming quota based on your plan. ```python @@ -256,11 +258,12 @@ source = catalog_source( time_range_type="acquired", ) -request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={}) - # define a delivery method. In this example, we're using AWS S3. delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1") +# build the request payload +request = build_request("Standard PSScene Ortho Analytic", source=source, delivery=delivery, clip_to_source=True) + # finally, create the subscription subscription = pl.subscriptions.create_subscription(request) ``` diff --git a/planet/subscription_request.py b/planet/subscription_request.py index 2380c3c8..4aa4b5ea 100644 --- a/planet/subscription_request.py +++ b/planet/subscription_request.py @@ -71,15 +71,11 @@ def build_request(name: str, hosting: A hosting destination e.g. Sentinel Hub. collection_id: A Sentinel Hub collection ID. create_configuration: Automatically create a layer configuration for your collection. - clip_to_source: whether to clip to the source geometry or not - (the default). If True a clip configuration will be added to - the list of requested tools unless an existing clip tool - exists. NOTE: Not all data layers support clipping, please - consult the Product reference before using this option. - NOTE: the next version of the Subscription API will remove - the clip tool option and always clip to the source geometry. - Thus this is a preview of the next API version's default - behavior. + clip_to_source: Whether or not to clip to the source geometry (defaults to False). If + True, a clip configuration that specifies the subscription source geometry as clip + AOI will be added to the list of requested tools. If True and 'clip_tool()' is + also specified, an exception will be raised. If False, no clip configuration + will be added to the list of requested tools unless 'clip_tool()' is specified. Returns: dict: a representation of a Subscriptions API request for @@ -133,10 +129,7 @@ def build_request(name: str, # If clip_to_source is True a clip configuration will be added # to the list of requested tools unless an existing clip tool - # exists. In that case an exception is raised. NOTE: the next - # version of the Subscription API will remove the clip tool - # option and always clip to the source geometry. Thus this is a - # preview of the next API version's default behavior. + # exists. In that case an exception is raised. if clip_to_source: if any(tool.get('type', None) == 'clip' for tool in tool_list): raise ClientError( @@ -656,6 +649,10 @@ def clip_tool(aoi: Mapping) -> dict: the clip aoi is so large that full scenes may be delivered without any clipping, those files will not have “_clip” appended to their file name. + NOTE: To clip to the source geometry, set the 'clip_to_source' parameter + of 'planet.subscription_request.build_request()' to True instead of using + this tool. + Parameters: aoi: GeoJSON polygon or multipolygon defining the clip area, with up to 500 vertices. The minimum geographic area of any polygon or @@ -665,6 +662,7 @@ def clip_tool(aoi: Mapping) -> dict: planet.exceptions.ClientError: If aoi is not a valid polygon or multipolygon. """ + valid_types = ['Polygon', 'MultiPolygon', 'ref'] geom = geojson.as_geom_or_ref(dict(aoi))