Features API SDK demo notebook #404
Conversation
sbueche
changed the title
tbarsballe
left a comment
tbarsballe
left a comment
There was a problem hiding this comment.
I've added a bunch of suggestions - mostly typos and wording improvements, though there's a couple code suggestions in there too.
Some of them are more up to personal preference and are optional - feel free to keep as-is if you think the current way is better.
| "\n", | ||
| "Full feature rules may be found [here](https://docs.planet.com/develop/apis/features/uploading-and-validating-features/#rules-for-creating-a-feature). \n", | ||
| "<br> <br>\n", | ||
| "Below we have defined a FeatureCollection of two areas in Cairo, Egypt. You may use this FeatureCollection to follow along with the tutorial, define your own, or import one from a filepath of something like a geojson." |
There was a problem hiding this comment.
Nitpick: We strictly support only valid GeoJSON. Rather than "from a filepath of something like a geojson" I'd say "from a path to a geojson file"
| "metadata": {}, | ||
| "source": [ | ||
| "You have a few options to define features to post to your Collections:\n", | ||
| "- The most simple option is to use a predefined FeatureCollection, so that the Features API can separate each feature into individual items for you.\n", |
There was a problem hiding this comment.
Nitpick/grammer: "The most simple option" -> "The simplest option"
| "You have a few options to define features to post to your Collections:\n", | ||
| "- The most simple option is to use a predefined FeatureCollection, so that the Features API can separate each feature into individual items for you.\n", | ||
| "- You may alternatively pass in just the geometries from feature collections. \n", | ||
| " - There is a free tool [geojson.io](https://geojson.io/) that will allow you to create geoetries and FeatureCollections by hand. You can also draw and download custom AOI geojson's from [Planet Explorer](https://www.planet.com/explorer/)." |
There was a problem hiding this comment.
Spelling: "geoetries" -> "geometries"
| "source": [ | ||
| "Features can have properties and keys beyond just the `geometry` and the `id`. If a feature is uploaded without specifying the `property_id`, all properties of the feature are maintained in the item.\n", | ||
| "\n", | ||
| "You can manually have your Feature's `id` be set with an 'id' key. You may also give you feature a display name in the Feature Manager web interface with a 'title' key in the features property. **Note** that when you upload a feature, it is not required to have a title. Your feature will still display without a 'Feature Name' in the [Features Manager](https://www.planet.com/features/) GUI, and is usable and accessible via its `id`. \n" |
There was a problem hiding this comment.
You could mention that it will specifically be displayed as Untitled feature
| "id": "ab8ef406", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "Features can have properties and keys beyond just the `geometry` and the `id`. If a feature is uploaded without specifying the `property_id`, all properties of the feature are maintained in the item.\n", |
There was a problem hiding this comment.
The start of this is a bit confusing/misleading - properties are a built-in part of geojson, so expecting support for them is normal. Users CANNOT add non-properties keys and expect them to be preserved, so that part is inaccurate. I'd suggest removing the first sentence entirely
I'd also suggest mentioning what happens if you do specify property_id - the current wording implies all properties won't be maintained if you do this.
Also, this might just be personal preference, but I think "retained" is more accurate than "maintained" here.
| "}\n", | ||
| "```\n", | ||
| "\n", | ||
| "Provided below is consolidated code to use the SDK to get a `pl:ref` id from the features API, and then input that id into an order request. If you are unfamiliar with the mechanics of the `order_request` functions of the SDK, there is a full notebook, `planet_sdk_orders_demo.ipynb` located in `api_guids/orders_api/` that will walk you through how to use the Planet Python SDK to create and submit Orders." |
There was a problem hiding this comment.
features API should be Features API
You should probably note that the ref is specifically being used for just the clip tool of the order.
You should just link to the notebook directly, i.e. [Planet SDK Orders Notebook](../orders_api/planet_sdk_orders_demo.ipynb) (also, you misspelled guides, but if you rewrite it this way that'll be unnecessary anyways)
| "collection_id = collections_list[0]['id']\n", | ||
| "\n", | ||
| "collection_items = list(pl.features.list_items(collection_id))\n", | ||
| "feature_ref = collection_items[1]['properties']['pl:ref']\n", |
There was a problem hiding this comment.
Any reason you're using the second feature in the collection? This should maybe be mentioned in the description above.
And since it is the second feature, this is going to frequently fail if they use or have created a different collection
| "source": [ | ||
| "# This example item_id can be used to order using the example FeatureCollection given.\n", | ||
| "# You will get an error if you tried to order this item with a different feature.\n", | ||
| "item_ids = ['20220501_074038_04_2420']\n", |
There was a problem hiding this comment.
Is it worth adding in an example of search via feature ref so you don't have to hardcode item id and can have a more versatile example? Would probably just be a couple lines...
| "\n", | ||
| "collection_items = list(pl.features.list_items(collection_id))\n", | ||
| "feature_ref = collection_items[1]['properties']['pl:ref']\n", | ||
| "geometry = {'type': 'ref', 'content': feature_ref}\n", |
There was a problem hiding this comment.
planet.geojson has a utility function that can do this conversion for you:
from planet.geojson import as_ref
geometry = as_ref(feature_ref)
(You can probably move the actual import to your import block)
| "name = 'geometry_ref_order'\n", | ||
| "products = [prod]\n", | ||
| "\n", | ||
| "order_made = planet.order_request.build_request(name, products, tools=tools)" |
There was a problem hiding this comment.
Perhaps rename the order_made variable (e.g. to order_dict)? The name seems a little ambiguous since the order hasn't been submitted yet.
2 participants
PR creates a new notebook,
planet_sdk_features_demofor demoing how to use the features endpoints of the Planet python SDK. Walks user through creating feature collections, adding items to them, deleting items and collections, as well as using a feature ref for an order.The order section at the end is very brief and is meant to be more of a template to use for using features in orders. It also directs the user to the orders sdk notebook for more details.