You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
"# Planet Tasking API Monitoring Tasking Orders\n",
23
+
"\n",
24
+
"---"
25
+
],
26
+
"cell_type": "markdown",
27
+
"metadata": {}
28
+
},
29
+
{
30
+
"source": [
31
+
"## Introduction\n",
32
+
"\n",
33
+
"---\n",
34
+
"\n",
35
+
"This tutorial is an introduction on the bulk creation of tasking orders using [Planet](https://www.planet.com)'s Tasking API. It provides code samples on how to write simple Python code to do this.\n",
36
+
"\n",
37
+
"The API reference documentation can be found at https://developers.planet.com/docs/tasking"
38
+
],
39
+
"cell_type": "markdown",
40
+
"metadata": {}
41
+
},
42
+
{
43
+
"source": [
44
+
"### Requirements\n",
45
+
"\n",
46
+
"---\n",
47
+
"\n",
48
+
"#### Software & Modules\n",
49
+
"\n",
50
+
"This tutorial assumes familiarity with the [Python](https://python.org) programming language throughout. Familiarity with basic REST API concepts and usage is also assumed.\n",
51
+
"\n",
52
+
"We'll be using a **\"Jupyter Notebook\"** (aka Python Notebook) to run through the examples.\n",
53
+
"To learn more about and get started with using Jupyter, visit: [Jupyter](https://jupyter.org/) and [IPython](https://ipython.org/). \n",
54
+
"\n",
55
+
"For the best experience, download this notebook and run it on your system, and make sure to install the modules listed below first. You can also copy the examples' code to a separate Python files an run them directly with Python on your system if you prefer.\n",
56
+
"\n",
57
+
"#### Planet API Key\n",
58
+
"\n",
59
+
"You should have an account on the Planet Platform to access the Tasking API. You may retrieve your API key from your [account page](https://www.planet.com/account/), or from the \"API Tab\" in [Planet Explorer](https://www.planet.com/explorer)."
60
+
],
61
+
"cell_type": "markdown",
62
+
"metadata": {}
63
+
},
64
+
{
65
+
"source": [
66
+
"## Overview\n",
67
+
"\n",
68
+
"---\n",
69
+
"\n",
70
+
"### The basic workflow\n",
71
+
"\n",
72
+
"1. Create a bulk tasking order\n",
73
+
"1. Check the progress of the bulk tasking order"
74
+
],
75
+
"cell_type": "markdown",
76
+
"metadata": {}
77
+
},
78
+
{
79
+
"source": [
80
+
"### API Endpoints\n",
81
+
"\n",
82
+
"This tutorial will cover the following API ***endpoint***:\n",
"Before interacting with the Planet Tasking API using Python, we will set up our environment with some useful modules and helper functions.\n",
96
+
"\n",
97
+
"* We'll configure *authentication* to the Planet Tasking API\n",
98
+
"* We'll use the `requests` Python module to make HTTP communication easier. \n",
99
+
"* We'll use the `json` Python module to help us work with JSON responses from the API.\n",
100
+
"* We'll use the `pytz` Python module to define the time frame for the order that we will be creating.\n",
101
+
"* We'll create a function called `p` that will print Python dictionaries nicely.\n",
102
+
"\n",
103
+
"Then we'll be ready to make our first call to the Planet Tasking API by hitting the base endpoint at `https://api.planet.com/tasking/v2`. \n",
104
+
"\n",
105
+
"Let's start by configuring authentication:"
106
+
],
107
+
"cell_type": "markdown",
108
+
"metadata": {}
109
+
},
110
+
{
111
+
"source": [
112
+
"### Authentication\n",
113
+
"\n",
114
+
"Authentication with the Planet Tasking API can be achieved using a valid Planet **API key**.\n",
115
+
"\n",
116
+
"You can *export* your API Key as an environment variable on your system:\n",
117
+
"\n",
118
+
"`export PL_API_KEY=\"YOUR API KEY HERE\"`\n",
119
+
"\n",
120
+
"Or add the variable to your path, etc.\n",
121
+
"\n",
122
+
"To start our Python code, we'll setup an API Key variable from an environment variable to use with our requests:"
123
+
],
124
+
"cell_type": "markdown",
125
+
"metadata": {}
126
+
},
127
+
{
128
+
"cell_type": "code",
129
+
"execution_count": null,
130
+
"metadata": {},
131
+
"outputs": [],
132
+
"source": [
133
+
"# Import the os module in order to access environment variables\n",
134
+
"import os\n",
135
+
"\n",
136
+
"#If you are running this notebook outside of the docker environment that comes with the repo, you can uncomment the next line to provide your API key\n",
137
+
"#os.environ['PL_API_KEY']=input('Please provide your API Key')\n",
138
+
"\n",
139
+
"# Setup the API Key from the `PL_API_KEY` environment variable\n",
140
+
"PLANET_API_KEY = os.getenv('PL_API_KEY')"
141
+
]
142
+
},
143
+
{
144
+
"source": [
145
+
"### Helper Modules and Functions"
146
+
],
147
+
"cell_type": "markdown",
148
+
"metadata": {}
149
+
},
150
+
{
151
+
"cell_type": "code",
152
+
"execution_count": null,
153
+
"metadata": {},
154
+
"outputs": [],
155
+
"source": [
156
+
"# Import helper modules\n",
157
+
"import json\n",
158
+
"import requests\n",
159
+
"import pytz\n",
160
+
"from time import sleep\n",
161
+
"from datetime import datetime, timedelta"
162
+
]
163
+
},
164
+
{
165
+
"cell_type": "code",
166
+
"execution_count": null,
167
+
"metadata": {},
168
+
"outputs": [],
169
+
"source": [
170
+
"# Helper function to printformatted JSON using the json module\n",
"A bulk tasking order is an asynchronous way to create many tasking orders with a single call. Once the initial POST request has been made it is then possible to make subsequent calls to be informed of the status of the request and the various orders that comprised the payload that are to be created. A bulk tasking order can be comprised of up to 1000 tasking orders of any kind that are supported by the Tasking service. \n",
199
+
"\n",
200
+
"For the purpose of this notebook we will create a handful of standard, flexible tasking orders that can then be submitted collectively viat the bulk endpoint. To make things easier we will default the start and end time of each order to start tomorrow and end 7 days from now. Of course feel free to change this to suit your needs but if you do take note that all times should be in UTC format. The start and end times are optional,but we include them in this tutorial to provide a better picture of what can be done."
201
+
],
202
+
"cell_type": "markdown",
203
+
"metadata": {}
204
+
},
205
+
{
206
+
"source": [
207
+
"\n",
208
+
"orders=[]\n",
209
+
"\n",
210
+
"for x in range[5]\n",
211
+
" # Define the name and coordinates for the order\n",
212
+
" name=input(\"Give the order a name\")\n",
213
+
" latitude=float(input(\"Provide the latitude\"))\n",
214
+
" longitude=float(input(\"Provide the longitude\"))\n",
215
+
"\n",
216
+
" # Because the geometry is GeoJSON, the coordinates must be longitude,latitude. \n",
217
+
" # It is also necessary to set the scheduling_type to \"MONITORING\"\n",
218
+
" order = {\n",
219
+
" 'name': name,\n",
220
+
" 'geometry': {\n",
221
+
" 'type': 'Point',\n",
222
+
" 'coordinates': [\n",
223
+
" longitude,\n",
224
+
" latitude\n",
225
+
" ]\n",
226
+
" }\n",
227
+
" }\n",
228
+
"\n",
229
+
" # Set a start and end time, giving the order a week to complete\n",
"We then create the bulk tasking order payload using the list of orders we just defined. The bulk payload can take a pre-defined UUID as the ```id``` of the bulk tasking order, but this is optional. If it is left out then an id will be set by the system and returned as part of the ```location``` field in the response header, which we will look at later."
251
+
],
252
+
"cell_type": "markdown",
253
+
"metadata": {}
254
+
},
255
+
{
256
+
"cell_type": "code",
257
+
"execution_count": null,
258
+
"metadata": {},
259
+
"outputs": [],
260
+
"source": [
261
+
"bulk_tasking_order = {\n",
262
+
" 'order_payloads': orders\n",
263
+
"}"
264
+
]
265
+
},
266
+
{
267
+
"cell_type": "code",
268
+
"execution_count": null,
269
+
"metadata": {},
270
+
"outputs": [],
271
+
"source": [
272
+
"#View the payload before posting\n",
273
+
"p(bulk_tasking_order)"
274
+
]
275
+
},
276
+
{
277
+
"cell_type": "code",
278
+
"execution_count": null,
279
+
"metadata": {},
280
+
"outputs": [],
281
+
"source": [
282
+
"# The creation of an order is a POST request to the /orders endpoint\n",
" print('Your PLANET_API_KEY is valid, but you are not authorized.')\n",
287
+
"elif res.status_code == 401:\n",
288
+
" print('Your PLANET_API_KEY is incorrect')\n",
289
+
"elif res.status_code == 201:\n",
290
+
" print('Your order was created successfully')\n",
291
+
"else:\n",
292
+
" print(f'Received status code {res.status_code} from the API. Please contact support.')\n",
293
+
"\n",
294
+
"# View the location header in the response\n",
295
+
"print(res.headers['location'])"
296
+
]
297
+
},
298
+
{
299
+
"source": [
300
+
"## 2 | Check the progress of the bulk tasking order\n",
301
+
"\n",
302
+
"As mentioned, a bulk tasking order is an asynchronous request so once made the builk endopint can then be polled to check the progress of the bulk tasking order as the Tasking service works its way through the orders that were provided in the payload.\n",
303
+
"\n",
304
+
"The quickest way to do this is to retrieve the URL that is in the ```location``` header that is part of the response of the intial bulk POST request. This URL includes an ID which, when part of a GET request, will return the current status of the bulk request in the system:"
305
+
],
306
+
"cell_type": "markdown",
307
+
"metadata": {}
308
+
},
309
+
{
310
+
"cell_type": "code",
311
+
"execution_count": null,
312
+
"metadata": {},
313
+
"outputs": [],
314
+
"source": [
315
+
"location = res.headers['location']\n",
316
+
"\n",
317
+
"# The url is the entire path minus the domain\n",
" print('Your PLANET_API_KEY is valid, but you are not authorized.')\n",
322
+
"elif res.status_code == 401:\n",
323
+
" print('Your PLANET_API_KEY is incorrect')\n",
324
+
"elif res.status_code == 201:\n",
325
+
" print('Your order was created successfully')\n",
326
+
"else:\n",
327
+
" print(f'Received status code {res.status_code} from the API. Please contact support.')\n",
328
+
"\n",
329
+
"p(res.json())"
330
+
]
331
+
},
332
+
{
333
+
"source": [
334
+
"The response to this request will show a summary of the progress that Tasking service has made in processing the bulk tasking order request. It will show the total size of the original payload: ```payload_count```, the number of tasking orders currently still being processed, the number of successfully processed tasking orders and the number of tasking orders that for one reason or another failed, these fields being ```processing_payload_count```, ```successful_payload_count``` and ```failed_payload_count``` respectively.\n",
335
+
"\n",
336
+
"But what if we want to see those tasking orders that are still being processed or, more importantly, any tasking orders that failed and why they failed? This is easily done by appending \"/payloads\" to the end of the url that we just used in the previous GET request:"
337
+
],
338
+
"cell_type": "markdown",
339
+
"metadata": {}
340
+
},
341
+
{
342
+
"cell_type": "code",
343
+
"execution_count": null,
344
+
"metadata": {},
345
+
"outputs": [],
346
+
"source": [
347
+
"# The url is the entire path minus the domain\n",
" print('Your PLANET_API_KEY is valid, but you are not authorized.')\n",
352
+
"elif res.status_code == 401:\n",
353
+
" print('Your PLANET_API_KEY is incorrect')\n",
354
+
"elif res.status_code == 201:\n",
355
+
" print('Your order was created successfully')\n",
356
+
"else:\n",
357
+
" print(f'Received status code {res.status_code} from the API. Please contact support.')\n",
358
+
"\n",
359
+
"p(res.json())"
360
+
]
361
+
},
362
+
{
363
+
"source": [
364
+
"# Conclusion\n",
365
+
"\n",
366
+
"As you can see, creating tasking orders in bulk is a relatively straightforward operation. It is also possible to use the ```/bulk``` endpoint to **edit** or even **cancel** multiple tasking orders at the same time. More information on how to do this can be found at https://developers.planet.com/docs/tasking/examples/bulk"
0 commit comments