From 35d29012e69cddae31bfacb79e2a818dc464eeb5 Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:43:33 -0700 Subject: [PATCH 1/7] Added pymdownx.snippets as a MD ext. --- mkdocs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index c7b3bdd4..1e785440 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -81,6 +81,10 @@ nav: - cli/cli-reference.md - "Python": - python/sdk-guide.md + - python/sdk-intro.md + - python/sdk-data.md + - python/sdk-orders.md + - python/sdk-subscriptions.md - python/sdk-reference.md - "Resources": - resources/index.md @@ -91,5 +95,6 @@ markdown_extensions: - pymdownx.superfences - mkdocs-click - admonition + - pymdownx.snippets - toc: permalink: True From b12af17462f2ca2a5c92c17801d75adec41e15f6 Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:43:41 -0700 Subject: [PATCH 2/7] Updated docs requirements. --- setup.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/setup.py b/setup.py index 4a175031..d061efa4 100644 --- a/setup.py +++ b/setup.py @@ -40,8 +40,10 @@ doc_requires = [ 'mkdocs==1.3', 'mkdocs-click==0.7.0', - 'mkdocs-material==8.2.11', - 'mkdocstrings==0.18.1' + 'mkdocs-material', + 'mkdocstrings==0.18.1', + 'pymdown-extensions==9.11', + 'Pygments>=2.12' ] setup( From f6207044f0c5cf0d48abac90b7ef201c057000a9 Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:44:49 -0700 Subject: [PATCH 3/7] New Data API docs structure, based on CLI. --- docs/python/sdk-data.md | 557 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 557 insertions(+) create mode 100644 docs/python/sdk-data.md diff --git a/docs/python/sdk-data.md b/docs/python/sdk-data.md new file mode 100644 index 00000000..752e5571 --- /dev/null +++ b/docs/python/sdk-data.md @@ -0,0 +1,557 @@ +--- +title: Python SDK for Data API Tutorial +--- + +TODO: Update narrative and snippets to be SDK instead of CLI. + +## Introduction + +The `planet data` CLI commands enable interaction with the [Data API](https://developers.planet.com/docs/apis/data/), +which lets you search Planet’s catalog (including select public datasets like Sentinel 2 and Landsat 8). +Currently the CLI has focused on the core search functionality, implementing +[Quick Search](https://developers.planet.com/docs/apis/data/reference/#tag/Item-Search/operation/QuickSearch) +and [stats](https://developers.planet.com/docs/apis/data/reference/#tag/Item-Stats/operation/Stats) plus some +partial saved search functionality. + +## `data search` command basics + +At this point you should have completed [Step 5](../get-started/quick-start-guide.md#step-5-search-for-planet-imagery) +of the quick start guide, and run your first full data search command: + +```sh +planet data search PSScene --filter filter.json > recent-psscene.json +``` + +This saves the descriptions of the latest 100 standard-quality scenes you have permissions to download in a file, that you can open and look at. + +### Pretty printing + +You will likely notice that this file is quite wide, with one very long line for each Planet +item returned. You can make for a more readable file by using the `--pretty` flag: + +```sh +planet data search --pretty PSScene --filter filter.json > recent-psscene.json +``` + +The `--pretty` flag is built into most of the CLI calls. But you can also achieve the +same effect by using another CLI program: `jq`. It is a very powerful library, providing +extensive manipulation of JSON, but simply +piping any JSON output through it prints it in a more readable form. So the following +command will do the same thing as the previous one: + +```sh +planet data search PSScene --filter filter.json | jq > recent-psscene.json +``` + +You can read a bit [more about jq]((cli-intro.md#jq) in the CLI intro. + +### Output to stdin + +You also don't have to save the output to a file. If you don't redirect it into a file then +it will just print out on the console. + +```sh +planet data search PSScene --filter filter.json +``` + +If you enter this command you’ll see the output stream by. Here you can use jq again, and +it’ll often give you nice syntax highlighting in addition to formatting. + +```sh +planet data search PSScene --filter filter.json | jq +``` + +### Create filter and search in one call + +Using a unix command called a 'pipe', which looks like `|`, you can skip the step of saving to disk, +passing the output of the `data filter` command directly to be the input of the `data search` +command: + +```sh +planet data filter --permission --std-quality | planet data search --pretty PSScene --filter - +``` + +Note the dash (`-`), which explicitly tells the CLI to use the output from the call that is piped into it. + +You can learn more about the pipe command, as well as the `>` command above in the +[Piping & redirection section](cli-intro.md#piping-redirection) of the CLI Introduction. + +### Search without filtering + +If no filtering is required, the search command can be called directly: + +```sh +planet data search PSScene +``` + +This outputs the last 100 scenes. + + +### Search on Item Type + +These first searches were done on the [PSScene](https://developers.planet.com/docs/data/psscene/) 'item type', but you +can use any [Item Type](https://developers.planet.com/docs/apis/data/items-assets/#item-types) that Planet offers in +its catalog. The item type is the first argument of the `search` command, followed by the 'filter'. Note that +you can specify any number of item types here: + +```sh +planet data search PSScene,Sentinel2L1C,Landsat8L1G,SkySatCollect +``` + +This will search for all the most recent images captured by PlanetScope, SkySat, Sentinel 2 and Landsat 8 satellites. +Note that you’ll likely mostly see PlanetScope results, as they generate far more individual images than the others. +The filter you specify will apply to all item types, but not all filters work against all satellites, so you may +inadvertently filter some out if you are filtering specific properties. + +### Limits + +By default the `search` command returns only the 100 first scenes. But with the CLI you can set any limit, and the SDK +under the hood will automatically page through all the results from the API. + +```sh +planet data search --limit 3000 PSScene +``` + +Note you can also do a call with no limits if you set the limit to `0`. Though don't use this haphazardly, or you’ll be +generating a lot of JSON from your request. It’s best to use it with a number of filters to constrain the search, so +you don't get hundreds of millions of results. + +### Output as valid GeoJSON + +By default the output of Planet’s Data API is [newline-delimited GeoJSON](https://stevage.github.io/ndgeojson/), which +is much better for streaming. While more and more programs will understand the format, the CLI also provides +the `planet collect` method to transform the output from the Data API to valid GeoJSON. You just pipe the end +output to it: + +```sh +planet data search PSScene | planet collect - +``` + +If you want to visualize this you can save it as a file: + +```sh +planet data search PSScene | planet collect - > planet-search.geojson +``` + +This you can then open with your favorite GIS program, or see this +[geometry visualization](cli-plus-tutorial.md#geometry-inputs) section for some ideas that flow a bit better with +the command-line. + +### Sort + +You can also specify the sorting with your searches. The default sort is ordered by the most recent published +images. But you can also sort by `acquired`, which is often more useful. You can sort in ascending or +descending order. The options are are: + + * 'acquired asc' + * 'acquired desc' + * 'published asc' + * 'published desc' + +This lets you do things like get the ID of the most recent SkySat image taken (and that you have permissions to download): + +```sh +planet data search SkySatCollect --sort 'acquired desc' --limit 1 +``` + +And you can also just get the ID, using `jq` + +```sh +planet data search SkySatCollect --sort 'acquired desc' --limit 1 - | jq -r .id +``` + +## Filtering + +### Run a search on a bounding box + +Most searches you’ll likely want to run on a geometry. To try this out you can use the following bounding box +of Iowa. You can copy it and save as a file called `geometry.geojson` + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "properties": {}, + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + -93.7353, + 41.6236 + ], + [ + -92.2741, + 41.6236 + ], + [ + -92.2741, + 42.3747 + ], + [ + -93.7353, + 42.3747 + ], + [ + -93.7353, + 41.6236 + ] + ] + ] + } + } + ] +} +``` + +!!!note ".geojson and .json files both work" + Here we save it as .geojson, but you can also save it as .json. The CLI is happy with any file + extension, even .txt, but different extensions may make it easier to open the files with other + programs. What’s important is that the text inside the file is valid geojson. + +And then run it with this command: + +```sh +planet data filter --geom geometry.geojson | planet data search PSScene --filter - +``` + +Note that by default all searches with the command-line return 100 results, but you can easily increase that with +the `--limit` flag: + +```sh +planet data filter --geom geometry.geojson | planet data search --limit 500 PSScene --filter - +``` + +Creating geometries for search can be annoying in a command-line workflow, but there are some ideas in the +[Advanced CLI Tutorial](cli-plus-tutorial.md#geometry-inputs). + +### Date Filter + +Some of the most common filtering is by date. You could get all imagery acquired before August 2021: + +```sh +planet data filter --date-range acquired lt 2021-08-01 \ + | planet data search PSScene --filter - +``` + +The 'operator' in this case is 'less than' (`lt`). The options are: + * `gt` - greater than + * `gte` - greater than or equal to + * `lt` - less than + * `lte` - less than or equal to + +You must specify which date field you want to use, either `acquired` or `published`. + +You can use the flags multiple times, and they are logically 'AND'-ed together, so you can +do a search for all images in July of 2021: + +```sh +planet data filter \ + --date-range acquired gte 2021-07-01 \ + --date-range acquired lt 2021-08-01 | \ +planet data search PSScene --filter - +``` + +The date input understands [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) and +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formats. You can specify just the date, +or include the time, to search for all Planetscope images acquired within 5 seconds at a time +on July 1st 2021: + +```sh +planet data filter \ + --date-range acquired gte 2021-07-01:06:20:10 \ + --date-range acquired lt 2021-07-01:06:20:15 \ + | planet data search PSScene --filter - +``` + +### Range Filter + +The range filter uses the same operators as the date filter, but works against any numerical property. The most useful +of these tend to be ones about cloudy pixels. For example you can search for data with clear pixels greater than 90%: + +```sh +planet data filter --range clear_percent gt 90 \ + | planet data search PSScene --filter - +``` + +### String-In Filter + +For properties that are strings you can use the `string-in` filter. For example search for all planetscope imagery +with PS2 instrument: + +```sh +planet data filter --string-in instrument PS2 \ + | planet data search PSScene --filter - +``` + +You can specify multiple strings to match, with a comma: + +```sh +planet data filter --string-in instrument PS2,PSB.SD \ + | planet data search PSScene --filter - +``` + +Another example is to select all data in a single strip: + +```sh +planet data filter --string-in strip_id 5743640 \ + | planet data search PSScene --filter - +``` + +Note that in all these commands we are piping the results into the search. If you don't include the pipe then you’ll +get the filter output, which can be interesting to inspect to see exactly what is sent to the server. + +### Filter by asset + +You can limit your search to only data with a particular asset, for example search just for 8-band analytic assets: + +```sh +planet data filter --asset ortho_analytic_8b_sr \ + | planet data search PSScene --filter - +``` + +Or 8-band assets that also have a UDM. + +```sh +planet data filter --asset ortho_analytic_8b_sr --asset udm2 \ + | planet data search PSScene --filter - +``` + +You can find the list of available assets in each Item Type Page, like +[available assets](https://developers.planet.com/docs/data/psscene/#available-asset-types) for PSScene. You can see +[a table of all Item Types](https://developers.planet.com/docs/data/psscene/#available-asset-types), which links to +the page for each with their list of asset types. + +Note that the asset filter doesn't perform any validation, so if your searches aren't returning anything check to make +sure you got the asset right, and it’s valid for the item-types you’re searching. + +### Permission Filter + +By default, no search filters are applied. However, many people want to search only for data they have access to download +that are of standard (aka not test) quality. Therefore, these filters can be easily added with the `--permission` and +`--std-quality` flags. To use the permission and standard quality filters: + +```sh +planet data filter --permission --std-quality --asset ortho_analytic_8b_sr \ + | planet data search PSScene --filter - +``` + +## Stats + +One command that can be quite useful for getting a sense of a search is the `stats` command. It works with the +exact same filters as the main `search` command, but it just returns a count of the results, which can be +binned by different time periods. + +This can be used for things like getting the number of items in a strip: + +```sh +planet data filter --string-in strip_id 5743640 \ + | planet data stats PSScene --interval day --filter - +``` + +Or the number of PlanetScope scenes collected in California each year: + +``` +curl -s https://raw.githubusercontent.com/ropensci/geojsonio/main/inst/examples/california.geojson \ + | planet data filter --geom - \ + | planet data stats PSScene --interval year --filter - \ + | jq +``` + +Will result in output like: + +```json +{ + "buckets": [ + { + "count": 5261, + "start_time": "2014-01-01T00:00:00.000000Z" + }, + { + "count": 34377, + "start_time": "2015-01-01T00:00:00.000000Z" + }, + { + "count": 112331, + "start_time": "2016-01-01T00:00:00.000000Z" + }, + { + "count": 504377, + "start_time": "2017-01-01T00:00:00.000000Z" + }, + { + "count": 807086, + "start_time": "2018-01-01T00:00:00.000000Z" + }, + { + "count": 806945, + "start_time": "2019-01-01T00:00:00.000000Z" + }, + { + "count": 776757, + "start_time": "2020-01-01T00:00:00.000000Z" + }, + { + "count": 684095, + "start_time": "2021-01-01T00:00:00.000000Z" + }, + { + "count": 323557, + "start_time": "2022-01-01T00:00:00.000000Z" + }, + { + "count": 56733, + "start_time": "2023-01-01T00:00:00.000000Z" + } + ], + "interval": "year", + "utc_offset": "+0h" +} +``` + +You can see how the yearly output of Planet has gone up, though it actually went down in 2022 as the upgrade to SuperDove meant much larger swaths, so the number of individual items went down even as we captured the whole earth. + +The API does not support an 'all time' interval to get the total of all collections for an area, but +you can easily use [jq]((cli-intro.md#jq) to total up the results of an interval count: + +```sh +curl -s https://raw.githubusercontent.com/ropensci/geojsonio/main/inst/examples/california.geojson \ + | planet data filter --geom - \ + | planet data stats PSScene --interval year --filter - \ + | jq '.buckets | map(.count) | add' + +``` + +Just pipe the results to `jq '.buckets | map(.count) | add'` and it’ll give you the total of all the values. + +## Asset Activation and Download + +While we recommend using the Orders or Subscriptions API’s to deliver Planet data, the Data API has the capability +to activate and download data. Only one asset can be activated at once, and there is no clipping or additional +processing of the data like the great 'tools' of Subscriptions & Orders. But the advantage is that it can often +be faster for working with a small number of items & assets. + +### Activate an Asset + +All items in the Data API have a list of assets. This includes the main imagery geotiff files, usually in a few +different formats, and also accompanying files like the [Usable Data Mask](https://developers.planet.com/docs/data/udm-2/) + (UDM) and JSON metadata. You can't immediately download them, as they must first be created in the cloud, known as +'activated'. To activate data you need to get its item id, plus the name of the asset - the available ones +can be seen by looking at the Item’s JSON. Once you have the item id and asset type you can run the CLI + +```sh +planet data asset-activate PSScene 20230310_083933_71_2431 ortho_udm2 +``` + +This will kick off the activation process, and the command should return immediately. In this example +we’re activating the UDM, which is one of the most common things to do through the Data API, to +first get a sense of where there are clouds before placing a proper clipping order. + +### Download an Asset + +Once an asset is ready you can use `asset-download` with a similar command: + +```sh +planet data asset-download PSScene 20230310_083933_71_2431 ortho_udm2 +``` + +While some assets activate almost immediately (if another user has requested +it recently), some can take a few minutes. If you try to download it before it’s active +you’ll get a message like: `Error: asset missing ["location"] entry. Is asset active?` + +Thankfully the CLI has the great `asset-wait` command will complete when the asset is activated: + +```sh +planet data asset-wait PSScene 20230310_083933_71_2431 ortho_udm2 +``` + +And you can pair with download so that as soon as the asset is active it’ll be downloaded: + +```sh +planet data asset-wait PSScene 20230310_083933_71_2431 ortho_udm2 && \ +planet data asset-download PSScene 20230310_083933_71_2431 ortho_udm2 +``` + +Download has a few different options: + + * `--directory` lets you specify a base directory to put the asset in. + * `--filename` assigns a custom name to the downloaded file. + * `--overwrite` will overwrite files if they already exist. + * `--checksum` checks to make sure the file you downloaded is the exact same as the one on the server. This can be useful if you script thousands of files to download to detect any corruptions in that process. + +## Saved Searches + +The core `planet data search` command uses what is called a 'quick search' in the API. The API +also supports what we call a '[saved searches](https://developers.planet.com/docs/apis/data/quick-saved-search/#saved-search)', +and the CLI supports this as well. + +### List Searches + +You can easily get a list of all the searches you’ve made: + +```sh +planet data search-list +``` + +This defaults to returning 100 results, but you can use `--limit` to return the number you +specify, and set it to 0 to return all your searches. By default this returns both +your quick searches and saved searches, but you can also limit to to only return +your saved searches: + +```sh +planet data search-list --search-type saved +``` + +If you’ve not created any saved searches it may be an empty list. You can create +saved searches with Planet Explorer, or it’s also easy with the command-line. + +### Create Search + +To make a new saved search you can use the exact same filter syntax as the regular `search` command, +but you must also add a 'name' to refer to the search by: + +```sh +planet data filter --geom geometry.geojson \ + | planet data search-create PSScene --name 'my saved search' --filter - +``` + +### Run Search + +When you save a new search you’ll get back the JSON describing the search. If you grab the 'id' field from it then +you can get the current results for that search: + +```sh +planet data search-run da963039dbe94573a3ac9e4629d065b6 +``` + +This is just like running a normal (quick) search, and takes similar arguments: `--limit` and `--pretty`, +and also the same [sort](#sort) parameter (`--sort`). You can also run any previous `quick` search. +They don't have names (the ID is just used as the name), but they are saved in the system and can be +executed again. Searches (except those with an end date that has passed) show new results +if run later and match newly acquired imagery. + +### Update Search + +You can also update an existing search to have a different set of values. This takes similar arguments, and +will overwrite the previous values. + +```sh +planet data filter --string-in instrument PS2,PSB.SD \ + | planet data search-update da963039dbe94573a3ac9e4629d065b6 \ + --name 'my updated search' \ + --filter - SkySatCollect +``` + +### Delete Search + +If you’re no longer using a search you can delete it: + +```sh +planet data search-delete da963039dbe94573a3ac9e4629d065b6 +``` + +If the deletion was successful the command-line won't print out anything except a new line. If the +search didn't exist it will say `Error: {"general": [{"message": "The requested search id does not exist"}], "field": {}}`. +You can also delete `quick` searches, which would remove them from your history. From b96656cfd063880e2aad215fb88fadd94f8f14ee Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:45:02 -0700 Subject: [PATCH 4/7] New Orders API docs structure, based on CLI. --- docs/python/sdk-orders.md | 764 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 764 insertions(+) create mode 100644 docs/python/sdk-orders.md diff --git a/docs/python/sdk-orders.md b/docs/python/sdk-orders.md new file mode 100644 index 00000000..27f5af17 --- /dev/null +++ b/docs/python/sdk-orders.md @@ -0,0 +1,764 @@ +--- +title: Python SDK for Orders API Tutorial +--- + +TODO: Update narrative and snippets to be SDK instead of CLI. + +## Introduction + +The `planet orders` command enables interaction with the [Orders API](https://developers.planet.com/apis/orders/), +which lets you activate and download Planet data products in bulk, and apply various +'tools' to your processes. This tutorial takes you through all the main capabilities +of the CLI for creating and downloading orders. It depends on several more advanced +command-line concepts, but this tutorial should let you get a sense of what you can do, +with enough examples that you should be able to adapt the commands for what you want to do. +If you’re interested in deeper understanding what is going on +then check out our [CLI Concepts](cli-intro.md) guide. + +## Core Workflows + +### See Recent Orders + +You can use the `list` command to show your recent orders: + +```sh +planet orders list +``` + +If you’ve not placed any orders with Explorer, the CLI or the API directly, then the results +of this call will be blank, so you may want to try out some of the create order commands below. + +Sometimes that list gets too long, so you can put a limit on how many are returned: + +```sh +planet orders list --limit 5 +``` + +You can also filter orders by their `state`, which can be useful to just see orders in +progress: + +```sh +planet orders list --state running +``` + +The other options are queued, failed, success, partial and cancelled. + +Note you can also get a nice list online as well, at https://www.planet.com/account/#/orders + +### Recent Orders with Formatting + +You can also print the list of orders more nicely: + +```sh +planet orders list --pretty +``` + +The `--pretty` flag is built into most Planet CLI commands, and it formats the JSON to be +more readable. + +You can also use `jq`, a powerful command-line JSON-processing tool, that is mentioned in +the [CLI introduction]((cli-intro.md#jq). + +```sh +planet orders list | jq +``` + +Piping any output through jq will format it nicely and do syntax highlighting. You can +also `jq` to just show select information, which can be useful for getting a quick sense +of the state of the state of things and pull out id’s for other operations: + +```sh +planet orders list | jq -rs '.[] | "\(.id) \(.created_on) \(.state) \(.name)"' +``` + +You can customize which fields you want to show by changing the values. + +### Number of recent orders + +You can use jq to process the output for more insight, like +get a count of how many recent orders you’ve done. + +```sh +planet orders list | jq -s length +``` + +This uses `-s` to collect the output into a single array, and `length` then tells the +length of the array. + +### Info on an Order + +For a bit more information about an order, including the location of any downloads, use +the `get` command, using the order id. + +```sh +planet orders get 782b414e-4e34-4f31-86f4-5b757bd062d7 +``` + +### Create an Order Request + +To create an order you need a name, a [bundle](https://developers.planet.com/apis/orders/product-bundles-reference/), + one or more id’s, and an [item type](https://developers.planet.com/docs/apis/data/items-assets/#item-types): + +First lets get the ID of an item you have download access to, using the Data API: + +```sh +planet data filter | planet data search PSScene --limit 1 --filter - | jq -r .id +``` + +If you don't have access to PlanetScope data then replace PSScene with SkySatCollect. +Then make the following call: + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'My First Order' \ + 20220605_124027_64_242b +``` + +Running the above command should output the JSON needed to create an order: + +```json +{"name": "My First Order", "products": [{"item_ids": ["20220605_124027_64_242b"], "item_type": "PSScene", "product_bundle": "analytic_sr_udm2"}], "metadata": {"stac": {}}} +``` + +You can also use `jq` here to make it a bit more readable: + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'My First Order' \ + 20220605_124027_64_242b \ + | jq +``` + +```json +{ + "name": "My First Order", + "products": [ + { + "item_ids": [ + "20220605_124027_64_242b" + ], + "item_type": "PSScene", + "product_bundle": "analytic_sr_udm2" + } + ], + "metadata": { + "stac": {} + } +} +``` + +### Save an Order Request + +The above command just prints out the necessary JSON to create an order. To actually use it you can +save the output into a file: + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name "My First Order" \ + 20220605_124027_64_242b \ + > request-1.json +``` + +Note that `\` just tells the command-line to treat the next line as the same one. It’s used here so it’s +easier to read, but you can still copy and paste the full line into your command-line and it should work. + +This saves the above JSON in a file called `request-1.json` + +### Create an Order + +From there you can create the order with the request you just saved: + +```sh +planet orders create request-1.json +``` + +The output of that command is the JSON returned from the server, that reports the status: + +```json +{ + "_links": { + "_self": "https://api.planet.com/compute/ops/orders/v2/2887c43b-26be-4bec-8efe-cb9e94f0ef3d" + }, + "created_on": "2022-11-29T22:49:24.478Z", + "error_hints": [], + "id": "2887c43b-26be-4bec-8efe-cb9e94f0ef3d", + "last_message": "Preparing order", + "last_modified": "2022-11-29T22:49:24.478Z", + "metadata": { + "stac": {} + }, + "name": "My First Order", + "products": [ + { + "item_ids": [ + "20220605_124027_64_242b" + ], + "item_type": "PSScene", + "product_bundle": "analytic_sr_udm2" + } + ], + "state": "queued" +} +``` + +Note the default output will be a bit more 'flat' - if you'd like the above formatting in your +command-line just use `jq` as above: `planet orders create request-1.json | jq` (but remember +if you run that command again it will create a second order). + +### Create Request and Order in One Call + +Using a unix command called a 'pipe', which looks like `|`, you can skip the step of saving to disk, +passing the output of the `orders request` command directly to be the input of the `orders create` +command: + +```sh +planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Item Order' \ +20220605_124027_64_242b,20220605_124025_34_242b | planet orders create - +``` + +The Planet CLI is designed to work well with piping, as it aims at small commands that can be +combined in powerful ways, so you’ll see it used in a number of the examples. + +### Download an order + +To download all files in an order you use the `download` command: + +```sh +planet orders download 65df4eb0-e416-4243-a4d2-38afcf382c30 +``` + +Note this only works when the order is ready for download. To do that you can +keep running `orders get` until the `state` is `success`. Or for a better +way see the next example. + +### Wait then download an order + +The `wait` command is a small, dedicated command that polls the server to +see if an order is ready for downloading, showing the status. It’s not +so useful by itself, but can be combined with the `download` command to +only start the download once the order is ready: + +```sh +planet orders wait 65df4eb0-e416-4243-a4d2-38afcf382c30 \ +&& planet orders download 65df4eb0-e416-4243-a4d2-38afcf382c30 +``` + +This uses the logical AND operator (`&&`) to say "don't run the second command +until the first is done". + +### Save order ID + +You can also use a unix variable to store the order id of your most recently placed order, +and then use that for the wait and download commands: + +```sh +orderid=$(planet orders list --limit 1 | jq -r .id) +planet orders wait $orderid +planet orders download $orderid +``` + +This can be nicer than copying and pasting it in. + +You could also save the id right when you place the order: + +```sh +orderid=`planet orders create request-1.json | jq -r .id` +``` + +To check the current value of `orderid` just run `echo $orderid`. + +### Create an order and download when ready + +You can then combine these all into one call, to create the order and +download it when it’s available: + +```sh +id=`planet orders create request-1.json | jq -r '.id'` && \ + planet orders wait $id && planet orders download $id +``` + +### Download to a different directory + +You can use the `--directory` flag to save the output to a specific directory. This +call saves it to a directory called `psscene`, at whatever location you are at +currently: + +```sh +mkdir psscene +planet orders download 782b414e-4e34-4f31-86f4-5b757bd062d7 --directory psscene +``` + +You can also specify absolute directories (in this case to my desktop): + +```sh +planet orders download \ + 782b414e-4e34-4f31-86f4-5b757bd062d7 \ + --directory /Users/cholmes/Desktop/ +``` + +### Verify checksum + +The `--checksum` command will do an extra step to make sure the file you got +wasn't corrupted along the way (during download, etc). It checks that the bytes +downloaded are the same as the ones on the server. By default it doesn't show +anything if the checksums match. + +```sh +planet orders download 782b414e-4e34-4f31-86f4-5b757bd062d7 --checksum MD5 +``` + +This command isn't often necessary in single download commands, but is quite +useful if you are downloading thousands of files with a script, as the likelihood +of at least one being corrupted in creases + +## Tools with orders + +Now we’ll dive into the variety of ways to customize your order. These can all be +combined with all the commands listed above. + +### Clipping + +The most used tool is the `clip` operation, which lets you pass a geometry to the +Orders API and it creates new images that only have pixels within the geometry you +gave it. The file given with the `--clip` option should contain valid [GeoJSON](https://geojson.org/). +It can be a Polygon geometry, a Feature, or a FeatureClass. If it is a FeatureClass, +only the first Feature is used for the clip geometry. + +Example: `geometry.geojson` +``` +{ + "geometry": + { + "type": "Polygon", + "coordinates": + [ + [ + [ + -48.4974827, + -1.4967008 + ], + [ + -48.4225714, + -1.4702869 + ], + [ + -48.3998028, + -1.4756259 + ], + [ + -48.4146752, + -1.49898376 + ], + [ + -48.4737304, + -1.5277508 + ], + [ + -48.4974827, + -1.4967008 + ] + ] + ] + } +} +``` + +We’ll work with a geojson that is already saved. You should download the +[geometry](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/geometry.geojson) +(and you can see it [on github](https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/request-json/geometry.geojson) +or it is also stored in the repo in the [request-json/](request-json/) directory. + +You can move that geometry to your current directory and use the following command, or +tweak the geometry.geojson to refer to where you downloaded it. + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --clip geometry.geojson \ + --name clipped-geom \ + 20220605_124027_64_242b \ + | planet orders create - +``` + +### Additional Tools + +Since clip is so heavily used it has its own dedicated command in the CLI. All +the other tools use the `--tools` option, that points to a file. The file should +contain JSON that follows the format for a toolchain, the "tools" section of an order. +The toolchain options and format are given in +[Creating Toolchains](https://developers.planet.com/apis/orders/tools/#creating-toolchains). + +Example: `tools.json` +``` +[ + { + "toar": { + "scale_factor": 10000 + } + }, + { + "reproject": { + "projection": "WGS84", + "kernel": "cubic" + } + }, + { + "tile": { + "tile_size": 1232, + "origin_x": -180, + "origin_y": -90, + "pixel_size": 2.7056277056e-05, + "name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}" + } + } +] +``` + +!!!note Note + Future of the versions of the CLI will likely add `tools` convenience methods, + so composite, harmonize and other tools work like `--clip`. You can follow issue + [#601](https://github.com/planetlabs/planet-client-python/issues/601): + comment there if you'd like to see it prioritized + +### Compositing + +Ordering two scenes is easy, just add another id: + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'Two Scenes' \ + 20220605_124027_64_242b,20220605_124025_34_242b \ + | planet orders create - +``` + +And then you can composite them together, using the 'tools' json. You can +use this, just save it into a file called [tools-composite.json](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-composite.json). + +```json +[ + { + "composite": { + } + } +] +``` + +Once you’ve got it saved you call the `--tools` flag to refer to the JSON file, and you +can pipe that to `orders create`. + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'Two Scenes Composited' \ + 20220605_124027_64_242b,20220605_124025_34_242b \ + --no-stac \ + --tools tools-composite.json \ + | planet orders create - +``` + +Note that we add the `--no-stac` option as [STAC Metadata](#stac-metadata) is not yet supported by the composite +operation, but STAC metadata is requested by default with the CLI. + +### Output as COG + +If you'd like to ensure the above order is a Cloud-Optimized Geotiff then you can request it +as COG in the file format tool. + +```json +[ + { + "file_format": { + "format": "COG" + } + } +] +``` + +The following command just shows the output with [tools-cog.json](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-cog.json): + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'COG Order' \ + 20220605_124027_64_242b,20220605_124025_34_242b \ + --tools tools-cog.json +``` + +As shown above you can also pipe that output directly in to `orders create`. + +### Clip & Composite + +To clip and composite you need to specify the clip in the tools (instead of `--clip`), as you can +not use `--clip` and `--tools` in the same call. There is not yet CLI calls to generate the `tools.json`, +so you can just use the [following json](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-clip-composite.json): + +```json +[ + { + "composite": {} + }, + { + "clip": { + "aoi": { + "type": "Polygon", + "coordinates": [ + [ + [ + -48.492541, + -1.404126 + ], + [ + -48.512879, + -1.504392 + ], + [ + -48.398017, + -1.52127 + ], + [ + -48.380419, + -1.423805 + ], + [ + -48.492541, + -1.404126 + ] + ] + ] + } + } + } +] +``` + +```sh +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --no-stac \ + --name 'Two Scenes Clipped and Composited' \ + 20220605_124027_64_242b,20220605_124025_34_242b \ + --tools tools-clip-composite.json \ + | planet orders create - +``` + +One cool little trick is that you can even stream in the JSON directly with `curl`, piping it into the request: + +```sh +curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-clip-composite.json \ + | planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'Streaming Clip & Composite' \ + --no-stac \ + 20220605_124027_64_242b,20220605_124025_34_242b \ + --tools - \ + | planet orders create - +``` + +### Harmonize + +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-harmonize.json`](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-harmonize.json) with `--tools`. + +```sh +planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Harmonized data' 20200925_161029_69_2223 --tools tools-harmonize.json +``` + +## More options + +### STAC Metadata + +A relatively recent addition to Planet’s orders delivery is the inclusion of [SpatioTemporal Asset Catalog](https://stacspec.org/en) +(STAC) metadata in Orders. STAC metadata provides a more standard set of JSON fields that work with +many GIS and geospatial [STAC-enabled tools](https://stacindex.org/ecosystem). The CLI `orders request` command currently requests +STAC metadata by default, as the STAC files are small and often more useful than the default JSON metadata. +You can easily turn off STAC output request with the `--no-stac` command: + +```sh +planet orders request \ + --item-type PSScene \ + --bundle visual \ + --name 'No STAC' \ + --no-stac \ + 20220605_124027_64_242b +``` + +Currently this needs to be done for any 'composite' operation, as STAC output from composites is not yet +supported (but is coming). You can explicitly add `--stac`, but it is the default, so does not need to +be included. For more information about Planet’s STAC output see the [Orders API documentation](https://developers.planet.com/apis/orders/delivery/#stac-metadata). + +### Cloud Delivery + +Another option is to delivery your orders directly to a cloud bucket, like AWS S3 or Google Cloud Storage. +The file given with the `--cloudconfig` option should contain JSON that follows +the options and format given in +[Delivery to Cloud Storage](https://developers.planet.com/docs/orders/delivery/#delivery-to-cloud-storage). + +An example would be: + +Example: `cloudconfig.json` + +```json +{ + "amazon_s3": { + "aws_access_key_id": "aws_access_key_id", + "aws_secret_access_key": "aws_secret_access_key", + "bucket": "bucket", + "aws_region": "aws_region" + }, + "archive_type": "zip" +} +``` + +### Using Orders output as input + +One useful thing to note is that the order JSON that reports status and location is a valid Orders API request. +It reports all the parameters that were used to make the previous order, but you can also use it directly as a +request. So the following call is a quick way to exactly redo a previous order request: + +```sh +planet orders get | planet orders create - +``` + +Realistically you'd more likely want to get a previous order and then change it in some way (new id’s, different +tools, etc.). You can remove the 'extra' JSON fields that report on status if you'd like, but the Orders +API will just ignore them if they are included in a request. + +There is planned functionality to make it easy to 'update' an existing order, so you can easily grab a past order +and use the CLI to customize it. + +### Basemaps Orders + +One of the newer features in Planet’s Orders API is the ability to [order basemaps](https://developers.planet.com/apis/orders/basemaps/). +The CLI does not yet support a 'convenience' method to easily create the JSON - you unfortunately +can't yet use `planet orders request` to help form an orders request. But all the other CLI functionality +supports ordering basemaps through the Orders API. + +You’ll need to use a full orders request JSON. + +```json +{ + "name": "basemap order with geometry", + "source_type": "basemaps", + "order_type":"partial", + "products": [ + { + "mosaic_name": "global_monthly_2022_01_mosaic", + "geometry":{ + "type": "Polygon", + "coordinates":[ + [ + [4.607406, 52.353994], + [4.680005, 52.353994], + [4.680005, 52.395523], + [4.607406, 52.395523], + [4.607406, 52.353994] + ] + ] + } + } + ], + "tools": [ + {"merge": {}}, + {"clip": {}} + ] +} +``` + +Once you’ve got the JSON, the other commands are all the same. Use create to submit it to the API: + +```sh +planet orders create basemap-order.json +``` + +See the status of the order you just submitted: + +```sh +planet orders list --limit 1 +``` + +Extract the ID: + +```sh +planet orders list --limit 1 | jq -r .id +``` + +Use that ID to wait and download when it’s ready: + +```sh +orderid=605b5472-de61-4563-88ae-d43417d3ed96 +planet orders wait $orderid +planet orders download $orderid +``` + +You can also list only the orders you submitted that are for basemaps, using `jq` to filter client side: + +```sh +planet orders list | jq -s '.[] | select(.source_type == "basemaps")' +``` + +#### Bringing it all together + +The cool thing is you can combine the data and order commands, to make calls +like ordering the most recent skysat image that was published: + +```sh +latest_id=$(planet data filter \ + | planet data search SkySatCollect \ + --sort 'acquired desc' \ + --limit 1 \ + --filter - \ + | jq -r .id) + +planet orders request \ + --item-type SkySatCollect \ + --bundle analytic \ + --name 'SkySat Latest' \ + $latest_id \ + | planet orders create - +``` + +Or get the 5 latest cloud free images in an area and create an order that clips to that area, using +[geometry.geojson](data/geometry.geojson) from above: + +```sh +ids=$(planet data filter --geom geometry.geojson --range clear_percent gt 90 \ + | planet data search PSScene --limit 5 --filter - \ + | jq -r .id \ + | tr '\n' ',' \ + | sed 's/.$//' +) +planet orders request \ + --item-type PSScene \ + --bundle analytic_sr_udm2 \ + --name 'Clipped Scenes' \ + $ids \ + --clip geometry.geojson \ + | planet orders create - +``` + +This one uses some advanced unix capabilities like `sed` and `tr`, along with unix variables, so more +properly belongs in the [CLI Tips & Tricks](cli-tips-tricks.md), but we’ll leave it here to give a taste of what’s possible. From b627ce772e9e10098fc6f15cd1aa62b8264d0a9d Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:45:20 -0700 Subject: [PATCH 5/7] New Subscriptions API docs structure, based on CLI. --- docs/python/sdk-subscriptions.md | 445 +++++++++++++++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 docs/python/sdk-subscriptions.md diff --git a/docs/python/sdk-subscriptions.md b/docs/python/sdk-subscriptions.md new file mode 100644 index 00000000..9f563079 --- /dev/null +++ b/docs/python/sdk-subscriptions.md @@ -0,0 +1,445 @@ +--- +title: Python SDK for Subscriptions API Tutorial +--- + +TODO: Update narrative and snippets to be SDK instead of CLI. + +## Introduction + +The `SubscriptionsClient` enables interaction with the +[Subscriptions API](https://developers.planet.com/apis/subscriptions/) +that make it possible to set up a recurring search criteria. Using the subscriptions api +you can automatically process and deliver new imagery to a cloud bucket. It also +has a powerful 'backfill' capability to bulk order historical imagery to your area of interest. +This tutorial takes you through the main commands available for subscriptions in the SDK + +## Core Workflows + +### Create a Subscription + +Since there is no UI to easily create subscriptions we’ll start with making a new one. + +```json +{ + "name": "First Subscription", + "source": { + "type": "catalog", + "parameters": { + "asset_types": [ + "ortho_analytic_8b" + ], + "end_time": "2023-11-01T00:00:00Z", + "geometry": { + "coordinates": [ + [ + [ + 139.5648193359375, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.42374884923695 + ] + ] + ], + "type": "Polygon" + }, + "item_types": [ + "PSScene" + ], + "start_time": "2023-03-17T04:08:00.0Z" + } + }, + "tools": [ + { + "type": "clip", + "parameters": { + "aoi": { + "coordinates": [ + [ + [ + 139.5648193359375, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.42374884923695 + ] + ] + ], + "type": "Polygon" + } + } + } + ], + "delivery": { + "type": "google_cloud_storage", + "parameters": { + "bucket": "pl-sub-bucket", + "credentials": "" + } + } +} +``` + +This is a full subscriptions JSON request, with the credentials redacted, so you’ll have +to replace your own for it to work. Below we’ll show the convenience methods that will +help create a custom one more easily. If you'd like to get things working for now then +just replace the 'delivery' section with your cloud credentials, see the +[core subscriptions delivery docs](https://developers.planet.com/docs/subscriptions/delivery/) +for more information. + +To create a new subscription with the CLI, use the `create_subscription` method and the json file you just created: + +TODO: Python snippet here: +```sh +planet subscriptions create my-subscription.json +``` + +!!!note "Note" + The above command assumes that you’ve saved the subscriptions JSON as `my-subscription.json` and that you’ve replaced the delivery information with your own bucket and credentials. + +### List Subscriptions + +Now that you’ve got a subscription working you can make use of the other commands. + +TODO: Python snippet here, should probably have it print too: +```sh +planet subscriptions list +``` + +outputs the JSON for your first 100 subscriptions. If you'd like more you can set the `--limit` +parameter higher, or you can set it to 0 and there will be no limit. + +TODO: Update narrative here, maybe example? How do we get python to print json nicely? Or does it do it by default? + +You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet +CLI’s. + +The `list_subscriptions` method also supports filtering by the status of the subscription: + + +TODO: Python snippet here: +```sh +planet subscriptions list --status running +``` + +gives you just the currently active subscriptions. The other available statuses are: +`cancelled`, `preparing`, `pending`, `completed`, `suspended`, and `failed`. + +### Get Subscription + +To get the full details on a single subscription you can take the id from your list and use the +`get_subscription` method: + +TODO: Python snippet here: +```sh +planet subscriptions get cb817760-1f07-4ee7-bba6-bcac5346343f +``` + +### Subscription Results + +To see what items have been delivered to your cloud bucket you can use the `get_results` method: + +TODO: Python snippet here: +```sh +planet subscriptions results cb817760-1f07-4ee7-bba6-bcac5346343f +``` + +By default this displays the first 100 results. As with other commands, you can use the `--limit` param to +set a higher limit, or set it to 0 to see all results (this can be quite large with subscriptions results). + +You can also filter by status: + +TODO: Python snippet here: +```sh +planet subscriptions results --status processing +``` + +The available statuses are `created`, `queued`, `processing`, `failed`, and `success`. + +### Update Subscription + +You can update a subscription that is running, for example to change the 'tools' it’s using or to alter +its geometry. To do this you must submit the full subscription creation JSON, so the easiest way is to +get it with `get_subscription` and then alter the values. + +TODO: Python snippet here - is there a way to programmatically update the resulting json? Could be nice to show that +like change the asset type from 8 band to 4 band + +```sh +planet subscriptions update cb817760-1f07-4ee7-bba6-bcac5346343f \ + my-updated-subscriptions.json +``` + +### Cancel a subscription + +Cancelling a subscription is simple with the SDK: + +TODO: Python snippet here: +```sh +planet subscriptions cancel cb817760-1f07-4ee7-bba6-bcac5346343f +``` + +That will stop the subscription from producing any more results, but it will stay in the system so you can +continue to list and get it. + +## Subscription Request Conveniences + +There are a couple of commands that can assist in creating the subscription JSON, used for creation and updates. +A subscription request is a pretty complicated command, consisting of a search, a cloud delivery, as well as +tools to process the data plus notifications on the status. + +### Catalog Source + +The first place to start is the `catalog-source` command, which generates all the JSON for the +[catalog source](https://developers.planet.com/docs/subscriptions/source/#catalog-source-type) block. The core +of this is quite similar to a Data API search request, though with more required fields. The minimal +required commands would be a request like: + +TODO: Python snippet here: +```sh +planet subscriptions request-catalog \ + --item-types PSScene \ + --asset-types ortho_analytic_8b \ + --geometry geometry.geojson \ + --start-time 2023-03-17T04:08:00.0Z +``` + +You request which item types you want to deliver, and the asset types for it. Note that the `asset-types` are a bit +different than the `--bundle` command in Orders, a bundle is a set of asset-types. You can see the list of asset types +for [PSScene](https://developers.planet.com/docs/data/psscene/#available-asset-types), [SkySatCollect](https://developers.planet.com/docs/data/skysatcollect/), +and [SkySatScene](https://developers.planet.com/docs/data/skysatscene/#available-asset-types). The other item-types +also have similar listings of their asset types. For the required `start-time` and optional `end-time` you must +use dates formatted as RFC 3339 or ISO 8601 formats. A nice time converter is available at [time.lol](https://time.lol/). +Just select 'ISO 8601' (third one on the list), or 'RFC 3339' (8th on the list). + +#### Geometry + +In this case we are using a locally saved `geometry.geojson`, which would look like the following if you wanted +it to match the subscription creation request at the top of this documentation page: + +```json +{ + "coordinates": + [ + [ + [ + 139.5648193359375, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.42374884923695 + ], + [ + 140.1031494140625, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.77102915686019 + ], + [ + 139.5648193359375, + 35.42374884923695 + ] + ] + ], + "type": "Polygon" +} +``` + +Note this is just the coordinates of either a polygon or multipolygon - the operation +is not flexible to input like the orders command. + +#### RRule + +RRule lets you specify a subscription that repeats at various time intervals: + +TODO: Python snippet here: +```sh +planet subscriptions request-catalog \ + --item-types PSScene \ + --asset-types ortho_analytic_8b \ + --geometry geometry.geojson \ + --start-time 2023-03-17T04:08:00.0Z \ + --rrule 'FREQ=MONTHLY;BYMONTH=3,4,5,6,7,8,9,10' +``` + +For more information on the `rrule` parameter see the [recurrence rules](https://developers.planet.com/docs/subscriptions/source/#rrules-recurrence-rules) +documentation. + +#### Filter + +You can pass in a filter from the data API: + +TODO: Python snippet here: +```sh +planet data filter --range clear_percent gt 90 > filter.json +planet subscriptions request-catalog \ + --item-types PSScene \ + --asset-types ortho_analytic_8b \ + --geometry geometry.geojson \ + --start-time 2022-08-24T00:00:00-07:00 \ + --filter filter.json +``` + +Do not bother with geometry or date filters, as they will be ignored in favor of the `--start-time` and `--geometry` values that are required. + +#### Saving the output + +You may want to save the output of your `catalog-source` to disk, so that you can use it in the future to construct the complete subscription +request. + +TODO: Python snippet here: +```sh +planet data filter --range clear_percent gt 90 > filter.json +planet subscriptions request-catalog \ + --item-types PSScene \ + --asset-types ortho_analytic_8b \ + --geometry geometry.geojson \ + --start-time 2022-08-24T00:00:00-07:00 \ + --filter filter.json > request-catalog.json +``` + +### Subscription Tools + +Now we’ll dive into some of the tools options for subscriptions. These are quite similar to the tools for +orders, but unfortunately the syntax is subtly different, and there are less tools supported. Just like +for Orders, future of the versions of the CLI will likely add `tools` convenience methods, you can follow issue +[#601](https://github.com/planetlabs/planet-client-python/issues/601). + +#### Clipping + +The most used tool is the `clip` operation, which lets you pass a geometry to the +Subscriptions API and it creates new images that only have pixels within the geometry you +gave it. We’ll use the same geometry from [above](#geometry), as it is quite +typical to use the same subscription geometry as the clip geometry, so you don't get +any pixels outside of your area of interest (99.9% of all subscriptions use the clip +tool, so it’s strongly recommended to also use clip). + +TODO: Make the JSON just the geometry, and show python snippet for the clip tool + +The proper 'clip' tool for it +would be: + +```json +[ + { + "type": "clip", + "parameters": { + "aoi": { + "type": "Polygon", + "coordinates": [ + [ + [ + -163.828125, + -44.59046718130883 + ], + [ + 181.7578125, + -44.59046718130883 + ], + [ + 181.7578125, + 78.42019327591201 + ], + [ + -163.828125, + 78.42019327591201 + ], + [ + -163.828125, + -44.59046718130883 + ] + ] + ] + } + } + } +] +``` + +You can save this tools as `tools.json` to include in the `subscriptions request` +command. + +#### File Format Tool + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Harmonize Tool + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Reproject Tool + +TODO: Narrative on file format +TODO: Python snippet here: + +#### TOAR Tool + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Band Math Tool + +TODO: Narrative on file format +TODO: Python snippet here: + +### Delivery + +One other essential part of the request is the `delivery` - the cloud delivery. +You can find the full documentation for the delivery options in +the [Subscriptions Delivery documentation](https://developers.planet.com/docs/subscriptions/delivery/). + +#### S3 Delivery + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Azure Delivery + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Google Cloud Delivery + +TODO: Narrative on file format +TODO: Python snippet here: + +#### Oracle Cloud Delivery + +TODO: Narrative on file format +TODO: Python snippet here: + +### Subscriptions Request + +TODO: Narrative on making a request that you've built up with convenience methods +TODO: Python snippet here: \ No newline at end of file From 716aa82224faa346889b6c2d51ac56b862f3390a Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Mon, 1 May 2023 10:51:06 -0700 Subject: [PATCH 6/7] Added snippets to TODO. --- docs/python/sdk-intro.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 docs/python/sdk-intro.md diff --git a/docs/python/sdk-intro.md b/docs/python/sdk-intro.md new file mode 100644 index 00000000..971024cf --- /dev/null +++ b/docs/python/sdk-intro.md @@ -0,0 +1,17 @@ +--- +title: Python SDK Introduction +--- + +## Python & Geospatial + +- lots of libraries + +## v2 vs v1 + +## Getting going + +### Your first call + +TODO: narrative on doing auth, creating session, making a data api call +TODO: snippets for the above. No filter, just defaults, but display results in some way. + From eb388099018b5a5e529b08d0ee3117b2a082dbec Mon Sep 17 00:00:00 2001 From: Kevin Lacaille Date: Wed, 3 May 2023 13:40:53 -0700 Subject: [PATCH 7/7] Added in line hilite and dedent subsections to MD. --- mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 1e785440..d447020c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,6 +95,8 @@ markdown_extensions: - pymdownx.superfences - mkdocs-click - admonition + - pymdownx.inlinehilite - pymdownx.snippets + dedent_subsections: True - toc: permalink: True