Demystifying Planet’s Command Line Tool
In conversation with Sara Safavi, Software Engineer at Planet
Over the last two years, Planet has come a long way in increasing the total square kilometers of data that it downloads and ingests into its pipeline (also called the firehose). It now allows the Earth to take a selfie every day and while we may be busy flipping through vines and four seconds videos, the Application Programming Interfaces (or APIs) are making our lives just a little bit easier. APIs are everywhere from almost every service you use on your Google Maps to every time you log into our beautiful Planet Explorer to zoom into the most updated version of Earth.
Command line Interface tools (CLIs), and Graphical User Interfaces (GUIs) that look beautiful require just an internet connection, are probably making requests to servers through and getting your data. Everything from Netflix to Spotify to Planet imagery is designed around these knobs of requests we make and tools often help you avoid the need to dismantle the inner workings and yet enjoy the fruits of those who build such tools.
Today we will have a conversation with Sara Safavi, who is a developer for the Planet Python Client and also a contributor and maintainer in its current form.
Sara, welcome, can you tell me a little about what is a command line interface and tool for a novice?
A CLI, or Command Line Interface, is an application or type of program that you run from the command line. So if you are familiar with the shell, or terminal, or command prompt: that’s what we’re talking about when we say “command line,” and that’s where you’re running these tools or applications. Instead of being a graphical interface like your internet browser or a video game, it’s just text-based interaction that runs in that terminal or command line.
Planet has a beautiful GUI in terms of the Planet Explorer, why choose one versus the other?
There is a speed benefit that you get out the door by using the CLI compared to the GUI, where you don’t have to individually select images and create an order, but can still search for and download hundreds of images without waiting for orders to complete. Also, something really nice about using a tool like our CLI is that you can automate some work and string different processes together in batches. So if you have a lot of different type of searches you want to do, you can build that incrementally and make that easy as part of your overall workflow. This becomes much easier to do using the CLI than using something like Planet Explorer.
I guess our next question would be: If I don’t know any Python or the language in which the Command line tool is written can I still use the tool? Are there any limitations to this approach?
Planet does have a Python client for interacting with our APIs (Application Programming Interface), which is great if you’re a Python developer who wants to write code that includes references to Planet’s APIs. But if you just want to use our command line interface without writing code, then we also have the CLI. That tool is part of Planet’s Python toolset, but you don’t need to know any Python just to use the CLI. You can install it and interact with it without writing a single line of Python code.
To use the command line tool, how do I get started? Is there any documentation on what needs to be installed on my system and then how to install CLI itself?
To use the command line tool, all you need is Python. Any version of Python from 2.7 to latest should work great, and most modern operating systems are going to already have that installed. So there’s a 99% chance you don’t need to install anything before installing the CLI.
(ed. note: if you are a Windows, Mac, or Linux user who does not have Python installed, learn how to install Python 3 here)
It’s important to note that while you can install the CLI without Planet credentials, you have to have a Planet account before you can use it to search for or download any data.There is documentation: if you go to our GitHub site where we host the open-source software that is our Python toolset, you’ll see a README document here that tells you how to install the CLI.
Where do I pose questions or request a new feature from this tool?
I mentioned earlier that this CLI tool is hosted on GitHub as free and open source software. For anyone not familiar, that means it’s free, and we also make the source code available to anyone who wants to edit it or modify it. At the Github page, you can also create an issue. Creating issues are a great place to start reporting errors, bugs and problems you might see with the tool, as well as any behavior that is unexpected or a feature that you would like. If you feel like you want to make any changes you can fork the repository and make the changes and submit a pull request. Once these changes or features are approved they’ll be added to the tool as it currently exists. So the next release will have your contributions in the tool based on the changes you made.
If you want to ask a more general question or get help, you could also go to our Planet Community page at planet.com/community. There you can interact with other Planet users and Planeteers (people who work at Planet): you can post questions about tools you use, read about what other users are doing, post examples, get help, and more.
Can people vote on a feature?
So there is actually a feature request section within Planet Community (link) where users can create a feature request and other users can upvote it, and where you can vote on feature requests made by other users.
Thinking about the future there may be some new things coming, changes in API, and imagery. How does the CLI keep up with all of this and what are some of the new tools and features that might be evolving?
One of the main things happening right now at Planet is that we have a couple of public APIs and some added functionality that is going to be released this year. As those APIs are released and that functionality is made available to users, then the Planet CLI tool will also be updated.
As far as types of improvements and features coming to the CLI: quota check functionality is coming to the tool pretty soon, that will allow users to quickly check their quota consumption and get stats from the CLI. We are also improving our support for Windows users, and finally, we are also improving our Python 3 support for the most recent Python 3.7 release.
Maybe you want to find stats for all imagery that intersect your geometry over different time intervals, try the planet data stats featureIs there any changelog we can follow to see how the tool evolves?
On GitHub, you can click through to the release notes for every version of the tool that has been released. There you can see what changes were made with each release, and that essentially serves as our changelog.
So I know that Python 2 will no longer be supported in 2020: do I need to install Python 3 before installing the CLI?
For now, there are no plans to stop supporting Python 2.7 for the Planet CLI, so as long as you have Python 2.7 or greater the CLI will work for you. However as a new user who might be installing Python, I’d say yes go ahead and install Python 3 because there are likely to be many tools that you’ll be interacting with outside the Planet CLI, most of which already support Python 3, and many of those might drop Python 2 support in the near future.
Thank you, Sara, for your time today.
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
“Tips, Tricks and Cheat codes to Planet CLI”
To Initialize the Planet CLI (You only have to do this once)
planet initInitializes the planet client (you need your email address and password for your planet account)
Search Image Only
This tool allows you to search for availability of images the example here searches for all images in 2018 however since that is a large number the — limit allows you to limit how many images you want to look at. If you remove the — limit flag in the current setup the tool will print all images of the type PSScene4Band analytic in 2018 that intersects with your geometry and has cloud cover less than 20%)
planet data search --item-type "PSScene4Band" --asset-type "analytic" --date acquired gt "2018–01–01" --date acquired lt "2018–12–31" --range cloud_cover lt "0.2" --geom "full path to geometry.geojson" --limit "Maximum number of images to search for"Batch Download Images
This tool activates and downloads Planet data. In this example, the tool searches for all images in January 2018 and downloads it to a destination folder. If you remove the — dest flag in the current setup the tool will download all images of the type PSScene4Band analytic in January 2018 that intersects with your geometry and has cloud cover less than 20% to the current folder you are in your command line)
planet data download --item-type "PSScene4Band" --asset-type "analytic" --date acquired gt "2018–01–01" --date acquired lt "2018–12–31" --range cloud_cover lt "0.2" --geom "full path to geometry.geojson" --dest "full path to folder where you want to download all images"Quick tip: replace asset-type analytic with analytic_xml in the download and you get metadata. You can get a reference to all items and assets here
Download Image Footprints with Metadata
This allows you to download the image footprints along with the metadata for each image as a GeoJSON file. You can open this GeoJSON file in geojson.io and export it as a shapefile, or KML or whatever you want to work with. This is useful when you want the metadata and footprints to make some estimates about the final data you may be interested in download without using up your Quota. For example, the current setup downloads all image footprints of type PSScene4Band analytic from Jan 1 to Jan 10 with cloud cover less than 20 %. Again you can specify a limit or the maximum number of images to look for or remove it to get all images.
planet data search --item-type "PSScene4Band" --asset-type "analytic" --date acquired gt "2018–01–01" --date acquired lt "2018–10–01" --range cloud_cover lt "0.2" --geom "full path to geometry.geojson" --limit "Maximum number of images to search for" >>"full path to footprint.geojson"Pro tip: Do not give it a large date range or a large geometry, the GeoJSON file will get large quickly and the process may fail.
Search and Download a Single Image using ID
You can do this easily using a string filter, look for a specific image id, for example, if you have downloaded a single image and you want the exact metadata file associated with it, you can use this to search and download that single image or metadata as needed.
To search (Image and metadata for a Single Image)
planet data search --string-in id 20180912_133342_0f3b --item-type PSScene4Band --asset-type analytic
To download (Image and metadata for a Single Image)
planet data download --string-in id 20180912_133342_0f3b --item-type PSScene4Band --asset-type analytic --dest "full path where you want to download image"planet data download --string-in id 20180912_133342_0f3b --item-type PSScene4Band --asset-type analytic_xml --dest "full path where you want to download image metadata"
Image Frequency and Stats
You can generate image statistics of the count of images that intersect your geometry. An example setup would be
planet data stats --interval month --geom "path to geometry.geojson" --item-type "PSScene4Band" --asset-type "analytic"
These are some of the most used capabilities of the CLI and feel free to add more in the comments below.
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
Sara Safavi is a software engineer working to bring daily earth imagery to the world at Planet. With a background in geoscience and a decade of industry experience, Sara specializes in the intersection of software development and all things geospatial.
Samapriya Roy is a remote sensing and geospatial developer and analyst. At Planet Sam’s role and responsibility of customer and researcher engagement allows him to work closely with both roles and develop engagement and utilization strategies for users with Planet’s data.
