{ "info": { "author": "Samapriya Roy", "author_email": "samapriya.roy@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Intended Audience :: Science/Research", "License :: OSI Approved :: Apache Software License", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Topic :: Scientific/Engineering :: GIS" ], "description": "# porder: Simple CLI for Planet ordersV2 API [](https://twitter.com/intent/tweet?text=Use%20porder%20CLI%20with%20@planetlabs%20new%20ordersv2%20API&url=https://github.com/tyson-swetnam/porder)\n\n[](https://doi.org/10.5281/zenodo.5079783)\n[](https://badge.fury.io/py/porder)\n[](https://pepy.tech/project/porder/month)\n[](https://opensource.org/licenses/Apache-2.0)\n\n\n\n\n**Disclaimer: This is an unofficial tool. Is not licensed or endorsed by Planet Labs. It was created by Samapriya Roy and is owned and maintained by Tyson Swetnam**\n\n[Orders v2](https://developers.planet.com/docs/orders/) is the next iteration of Planet's API for getting Analysis Ready Data (ARD) delivered to you. Orders v2 has the capability to submit any number of images in a batch order and perform operations such as: top of atmospheric (TOA) reflectance, compression, coregistration, and supports enhanced notifications such as email and webhooks. Based on your personal license access you can use the `porder` to place orders, download orders, or chain together a sequence of operations from the Orders v2 API. The `porder` tool runs on the command line interface only. For exporting to cloud storage `porder` uses a configuration folder with `config.yml` structures.\n\nIf you use this tool to download data and find it useful please star us on GitHub (top right corner of this page).\n\nIf you publish research which used this tool, please use this citation:\n\n```\nSamapriya Roy, Tyson L. Swetnam, Isabella (Izzi) Hinks, Ryan Avery, David Shean, Anthony Lukach, & Scott Henderson. (2021, July 7).\ntyson-swetnam/porder: porder: Simple CLI for Planet ordersV2 API (Version 0.8.3). Zenodo. http://doi.org/10.5281/zenodo.5079783\n```\n\n### **[Read the Guided Docs here](https://tyson-swetnam.github.io/porder/)**\n## Table of contents\n* [Prerequisites](#prerequisites)\n* [Installing porder](#installing-porder)\n* [Windows Setup](#windows-setup)\n* [Getting started](#getting-started)\n* [porder Simple CLI for Planet ordersv2 API](#porder-simple-cli-for-planet-ordersv2-api)\n * [porder readme](#porder-readme)\n * [porder quota](#porder-quota)\n * [base64](#base64)\n * [convert to geojson](#convert-to-geojson)\n * [simplify](#simplify)\n * [idlist](#idlist)\n * [difflist](#difflist)\n * [idsplit](#idsplit)\n * [idcheck](#idcheck)\n * [bundles](#bundles)\n * [order](#order)\n * [reorder](#reorder)\n * [cancel](#cancel)\n * [orderstate list](#orderstate-list)\n * [ordersize](#ordersize)\n * [stats](#stats)\n * [download](#download)\n * [multipart download](#multipart-download)\n * [multiprocessing download](#multiprocessing-download)\n\n## Prerequisites\n\nYou must have native python & pip installed. You can test this by going to the terminal (or windows command prompt) and trying.\n\n```python --version``` and then ```pip list```\n\nIf you have no errors and you have Python `3.6+` or higher you should be good to go.\n\nWe also recommend installation within virtual environment. If you use [Conda](https://docs.conda.io/en/latest/)\n\n```\n$ conda create -n planet_orders python\n$ conda activate planet_orders\n```\n\n**The `porder` tool is dependent on `shapely` and `fiona` which depend on GDAL**\n\n[QGIS](https://qgis.org/en/site/) is a useful open-source GIS platform which includes all of the major required dependencies for running `porder`. Installation of QGIS will ensure all `porder` requirements are met.\n\n### Linux\n\nInstalling Python GDAL in Ubuntu\n\n```\n$ sudo add-apt-repository ppa:ubuntugis/ppa && sudo apt-get update\n$ sudo apt-get install gdal-bin libcurl4-openssl-dev libssl-dev python3-gdal\n```\n\n### Windows\n\nWe also recommend using [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) and following the linux instructions.\n\nFor Windows this [guide](https://webcache.googleusercontent.com/search?q=cache:UZWc-pnCgwsJ:https://sandbox.idre.ucla.edu/sandbox/tutorials/installing-gdal-for-windows+&cd=4&hl=en&ct=clnk&gl=us) from UCLA is useful.\n\n\n### MacOS X\n\n[KyngChaos](https://www.kyngchaos.com/software/frameworks/) maintains a MacOS X installation for GDAL\n\nInstall GDAL using [brew]\n\nInstall brew:\n\n```\n/usr/bin/ruby -e \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\"\n```\n\nInstall GDAL:\n```\n% brew install gdal --HEAD\n% brew install gdal\n% gdal-config --version\n```\n\nInstall GDAL Python binding:\n\n```\n% pip3 install \u00e2\u20ac\u201d-upgrade pip\n% pip3 install numpy\n% python3 -c \u00e2\u20ac\u02dcimport gdal; print(gdal.VersionInfo())\u00e2\u20ac\u2122\n```\n\n### Docker\n\nYou can also run `porder` with [Docker](https://hub.docker.com/r/tswetnam/porder)\n\n```\n$ docker pull tswetnam/porder:latest\n```\n\nIf you haven't run `planet init` to create your token, do so first. Make sure to run docker with the volume flag mounted back to your home `${HOME}` or current working directory `${PWD}`:\n\n```\n$ docker run -it --rm -v ${HOME}:/root tswetnam/porder:latest planet init\n```\n\ncheck if you now have a private `.planet.json` file in your home or current working directory.\n\nRun `porder` as a test:\n\n```\n$ docker run -it --rm -v ${HOME}:/root tswetnam/porder:latest porder quota\n```\n\nThis should return your user information and the remaining available km of data:\n\n```\nSubscription ID: XXXXX\nPlan ID: XXXXX\nAllocation Name: your@email.address\nAllocation active from: YEAR-MM-DD\nQuota Enabled: True\nTotal Quota in SqKm: 10000\nTotal Quota used: 0.0\nRemaining Quota in SqKm: 10000.0\n```\n\n## Installing porder\n\nOnce you have the dependency libraries configured you're ready to install\n\nFrom `pip`:\n\n```pip install porder```\n\nFor linux it might help to specify the pip type and use `--user`\n\n```\npip3 install porder --user\n```\n\nFrom GitHub `source`:\n\n```\ngit clone https://github.com/tyson-swetnam/porder.git\ncd porder\npython setup.py install\n```\n\nType `porder -h` to view the help\n\n## Windows Setup\n\nShapely and a few other libraries are notoriously difficult to install on windows machines so follow the steps mentioned here **before installing porder**. You can download and install shapely and other libraries from the [Unofficial Wheel files from here](https://www.lfd.uci.edu/~gohlke/pythonlibs) download depending on the python version you have. **Do this only once you have install GDAL**. I would recommend the steps mentioned above to get the GDAL properly installed. However I am including instructions to using a precompiled version of GDAL similar to the other libraries on windows. You can test to see if you have gdal by simply running\n\n```gdalinfo```\n\nin your command prompt. If you get a read out and not an error message you are good to go. If you don't have gdal try Option 1,2 or 3 in that order and that will install gdal along with the other libraries\n\n#### Option 1:\nStarting from porder v0.4.5 onwards:\n\nSimply run ```porder -h``` after installation. This should go fetch the extra libraries you need and install them. Once installation is complete, the porder help page will show up. This should save you from the few steps below.\n\n#### Option 2:\nIf this does not work or you get an unexpected error try the following commands. You can also use these commands if you simply want to update these libraries.\n\n```\npipwin refresh\npipwin install gdal\npipwin install pyproj\npipwin install shapely\npipwin install fiona\npipwin install geopandas\n```\n\n#### Option 3\n\nFor windows first thing you need to figure out is your Python version and whether it is 32 bit or 64 bit. You can do this by going to your command prompt and typing python.\n\n\n\nFor my windows machine, I have both 32-bit python 2.7.16 and 64-bit Python 3.6.6. You can get the python version at the beginning of the highlighted lines and the 32 or 64 bit within the Intel or AMD64 within the square brackets. Your default python is the one you get by just typing python in the command line. Then download the following packages based on the information we collect about our python type in the earlier step. We use unofficial binaries to install these. This step is only needed if you are on a windows machine if you are using a setup manager like anaconda you **might** be able to avoid this setup completely\n\nAt this stage **if you were unable to install gdal then download the gdal binaries first**, install that before everything else\n\ngdal: [https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal](https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal)\n\nThen follow along the following libraries\n* pyproj: [https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyproj](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyproj)\n* shapely: [https://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely](https://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely)\n* fiona: [https://www.lfd.uci.edu/~gohlke/pythonlibs/#fiona](https://www.lfd.uci.edu/~gohlke/pythonlibs/#fiona)\n* geopandas: [https://www.lfd.uci.edu/~gohlke/pythonlibs/#geopandas](https://www.lfd.uci.edu/~gohlke/pythonlibs/#geopandas)\n\nTo choose the version that is correct for you use the python information you collected earlier\nFor example for my python 3.6.6 and AMD 64 if I was installing shapely I would choose the following, here 36 means python 3.6 and amd64 refers to the 64bit we were talking about.\n\n```Shapely\u00e2\u20ac\u20181.6.4.post2\u00e2\u20ac\u2018cp36\u00e2\u20ac\u2018cp36m\u00e2\u20ac\u2018win_amd64.whl```\n\nYou will get a wheel file or a file ending with .whl. You can now simply browse to the folder or migrate to it in your command prompt. Once there if I am installing for my python 3.6 the command was. At this point we will make use of our trusted package installer that comes with python called pip. Note the choice of pip or pip3 depends on your python version usually you can get the pip to use with your python by typing\n\n\n```pip3 -V```\n\nyou get a readout like this\n\n```pip 18.1 from c:\\python3\\lib\\site-packages\\pip (python 3.6)```\n\nif you have pip just replace that with ```pip -V```\n\nThen simply install the wheel files you downloaded using the following setup\n\n```\npip3 install full path to Shapely\u00e2\u20ac\u20181.6.4.post2\u00e2\u20ac\u2018cp36\u00e2\u20ac\u2018cp36m\u00e2\u20ac\u2018win_amd64.whl\n\nin my case that would be\n\npip3 install \"C:\\Users\\samapriya\\Downloads\\Shapely\u00e2\u20ac\u20181.6.4.post2\u00e2\u20ac\u2018cp36\u00e2\u20ac\u2018cp36m\u00e2\u20ac\u2018win_amd64.whl\"\n```\n\nOr you can use [anaconda to install](https://conda-forge.github.io/). Again, both of these options are mentioned on [Shapely\u00e2\u20ac\u2122s Official PyPI page](https://pypi.org/project/Shapely/).\n\n## Getting started\n\nMake sure you initialized planet client by typing ```planet init```. As usual, to print help:\n\n\n\nTo obtain help for a specific functionality, simply call it with _help_ switch, e.g.: `porder idlist -h`. If you didn't install porder, then you can run it just by going to *porder* directory and running `python porder.py [arguments go here]`\n\n## porder Simple CLI for Planet ordersv2 API\nThe tool is designed to simplify using the ordersv2 API and allows the user to chain together tools and operations for multiple item and asset types and perform these operations and download the assets locally.\n\n### porder readme\nNow open the readme webpage in your browser using\n\n```\nporder readme\n```\n\n### porder quota\nJust a simple tool to print your planet subscription quota quickly.\n\n\n\n### base64\nThis does exactly as it sounds, it encodes your credential files to base64 for use with gcs.\n\n\n\n### convert to geojson\nThis tool allows you to convert from a folder with multiple shapefiles or kml files to a folder with geojson that can then be used with the tool. It makes use of geopandas and reprojects your shapefile to make it compatible while passing onto the API for search and download. KML conversions are handled seperately.\n\n\n\n### simplify\nThis reduces the number of vertices for a multi vertex and complex GeoJSON. Extremely high vertex count (over 500) seem to fail and hence this tool allows you to export a new geojson with reduced vertices. It uses an implementation of the Visvalingam-Wyatt line simplification algorithm. This tool does work with and without Fiona, but Fiona installation is recommended.\n\n\n\n### idlist\nCreate an idlist for your geometry based on some basic filters,including geometry, start and end date and cloud cover. If no cloud cover is specified everything form 0 to 100% cloud cover is included. For now the tool can handle geojson,json and kml files. The output is a csv file with ids. The tool also allows you to make sure you get percentage overlap, when selecting image, for clip operations adjust it accordingly (usally --ovp 1 for orders not to fail during clip). The tool now also prints estimated area in Square kilometes for the download and estimated area if you clipped your area with the geometry you are searching (just estimates). You can now pass multiple assetswith the idlist tool pass assets as analytic_sr,udm2 for example to get items with both these assets ``` --asset analytic_sr,udm2.\n\n**I have changed the setup to now do the following two things**\n\n* The number option is optional, so it can look for all images in the time range, but be careful if the area is too large, _use at own risk_. A better option is to supply the number.\n\n* It is possible to often forget about the different asset types, so you can now not pass an item and the script will return every possible type of asset for each item type depending on the bundle.\n\n\n\nA simple setup would be\n\n\nTo run an experiment to add additional filter, you can now pass an additional string or range filter or both flag for string and range filters, a setup would be. The additional filters are optional\n\n```\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters range:clear_percent:55:100 --number 20\n\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters string:satellite_id:\"1003,1006,1012,1020,1038\" --number 20\n\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters string:satellite_id:\"1003,1006,1012,1020,1038\" range:clear_percent:55:100 --number 20\n```\n\nThe idlist tool can now use a multipolygon and iteratively look for scenes.\n\n# Getting an idlist\n\nCreate an idlist for your geometry based on some basic filters,including geometry, start and end date and cloud cover. If no cloud cover is specified everything form 0 to 100% cloud cover is included. For now the tool can handle geojson,json and kml files. The output is a csv file with ids. The tool also allows you to make sure you get percentage overlap, when selecting image, for clip operations adjust it accordingly (usally --ovp 1 for orders not to fail during clip). The tool now also prints estimated area in Square kilometes for the download and estimated area if you clipped your area with the geometry you are searching (just estimates).\n\n**I have changed the setup to now do the following two things**\n\n* The number option is optional, so it can look for all images in the time range, but be careful if the area is too large, _use at own risk_. A better option is to supply the number.\n\n* It is possible to often forget about the different asset types, so you can now not pass an item and the script will return every possible type of asset for each item type depending on the bundle.\n\n\n\nA simple setup would be\n\n\nTo run an experiment to add additional filter, you can now pass an additional string or range filter or both flag for string and range filters, a setup would be. The additional filters are optional\n\n\n\n```\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters range:clear_percent:55:100 --number 20\n\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters string:satellite_id:\"1003,1006,1012,1020,1038\" --number 20\n\nporder idlist --input \"Path to geojson file\" --start \"YYYY-MM-DD\" --end \"YYYY-MM-DD\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters string:satellite_id:\"1003,1006,1012,1020,1038\" range:clear_percent:55:100 --number 20\n```\n\n\n\nThe search tool now allows the user to pass Hours , Minutes and seconds and utilizes the local timezone on the users computer to search. This including the format HH:MM:SS seperated from yyyy-mm-dd by T. An example would be the following, while noting that passing time is purely optional and you can still search by simply passing YYYY-MM-DD.\n\n```\nporder idlist --input \"Path to geojson file\" --start \"yyyy-mm-ddTHH:MM:SS\" --end \"yyyy-mm-ddTHH:MM:SS\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --filters range:clear_percent:55:100 --number 20\n\nporder idlist --input \"Path to geojson file\" --start \"2021-01-01T14:12:10\" --end \"2021-03-01T16:20:20\" --item \"PSScene4Band\" --asset \"analytic\" --outfile \"Path to idlist.csv\" --number 20\n```\n\nThe idlist tool can now use a multipolygon and iteratively look for scenes.\n\n\n### difflist\nIt is possible you already downloaded some images or metadata files, and your you want a difference idlist to create orders for only assets and item types you do not have. It takes in your local folder path, type image or metadata and some basic filters,including geometry, start and end date and cloud cover. If no cloud cover is specified everything form 0 to 100% cloud cover is included. For now the tool can handle geojson,json and kml files. The output is a csv file with ids.\n\n\n\nA simple setup would be\n\n\nor without the cloud filter\n\n\n\n### idsplit\nThis allows you to split your idlist into small csv files incase you wanted to created batches of orders.\n\n\n\nA simple setup would be\n\n\n### idcheck\nIt is possible for you to modify the idlist, add or remove ids. Once done, this tool allows you to estimate the total area of images and area that intersect with your geometry or area if clipped.\n\n\n\nA simple setup would be\n\n\n### bundles\nOrdering using ordersv2 uses the concept of bundles. A bundle is a combination of multiple assets for an item that come together and are delivered as part of the overall fulfillment of the order. For example an analytic asset for PSScene4Band is a single tif file, however the analytic bundle for PSScene4Band includes analytic tiff file, the analytic_xml metadata and the udm data mask file as part of the bundle. You can find more information about [bundles here](https://developers.planet.com/docs/orders/product-bundles-reference/). Thus the concept of bundles bring together single function to order and download multiple related assets. Since the list of bundles is long, this tool simply allows you to get every bundle type based on item type. The setup is simple\n\n\n\nA simple setup would be\n\n```\nporder bundles --item \"PSScene4Band\"\n```\n\n### order\nThis tool allows you to actually place the order using the idlist that you created earlier. the ```--op``` argument allows you to take operations, delivery and notifications in a sequence for example ```--op toar clip email``` performs Top of Atmospheric reflectance, followed by clipping to your geometry and send you an email notification once the order has completed, failed or had any any change of status. An important changes is the concept of passing bundles instead of using assets. Bundles are predefined meaning all assets in a bundle are not available for an item your attempt at downloading that attempt will fail.\n\nFor example if an item id '20181227_125554_0f4c' does not have surface reflectance asset type. So if you try to download this using bundle type analytic_sr_udm2 it will not work, similary if you order an item where a specific operation cannot be performed for example if you order visual and then try to do bandmath with four bands. These examples and more are where **fallback bundles** come in handy. Think of this as providing a list of bundles to keep trying if one bundle type fails. The priority goes left to right. You can provide comma seperated fallback bundles for example as\n\n```analytic_sr_udm2,analytic``` instead of ```analytic_sr_udm2``` to avoid certain items from failing to download.\n\nThe list of operations for the ```--op``` are below and ** the order of these operations is important**\n\n\n