Planet has a range of APIs for discovering imagery, ordering bundles of imagery and analytic products, setting up subscriptions, and delivering that data to your preferred cloud.
To start working with Planet's APIs, you first register and obtain an API key from your account. This key grants you access to a variety of APIs, such as the Data API for searching Planet's data catalog, Orders API for creating analysis-ready data, and Subscriptions API for subscribing and monitoring continuous cloud delivery of imagery and metadata collections. Remember, you first need to activate an imagery first, then monitor its status until it's ready for download or delivery to the cloud.
The authentication process for using Planet APIs is Basic HTTP Authentication. For the service to transmit data to you, it requires some credentials, a key, before you can access this data. So, to use any Planet API, you need an API key. API keys are available to all registered users with active Planet accounts.
Find your API Key¶
Once you're signed up, log in to your account at planet.com/account to get your API key. Find the API key field under your account information, as seen here:
Planet's API Ecosystem¶
Planet's platform is made up of a collection of APIs. These include:
- Data API - allows you to search Planet's complete catalog of data
- Orders API - raster tools for creating analysis-ready data with Planet's imagery archive
- Subscriptions API - allows you to subscribe to continuous cloud delivery of imagery, metadata, and Planetary Variables collections
- Analytics API - gives you access to derived analytic products like Planet Analytic Feeds
- Basemaps API - give you access to Planet's mosaiced basemap services
- Tile Services - XYZ and WMTS tile map services for use in your favorite GIS or mapping client
- Tasking API - API for creating and managing your SkySat point collection orders
- Reports API - API which systematically reports download usage for internal processing and analysis
You can read more about each API and find complete docs and API reference guides here.
Accessing the Planet catalog¶
With the Data API, you can download individual scenes, one at a time. You can also do a quick search or a saved search and filter those results, get stats on those images and preview them as thumbnails.
When you're ready to go beyond searching and downloading an individual scene, use the Orders API to order bundles of assets for download, send bundles to your cloud account, and manipulate results with tools to prepare them for analysis before downloading.
Finally, when you want to connect your catalog sources to a data processing pipeline, use the Subscriptions API to monitor for change and run tools on new data when it is available.
Quickstart: Search & Download Imagery¶
If you're new to Planet's APIs and just want to search for and download an image, then start with the Data API.
A Python-based Jupyter Notebook is available here if you'd like to interactively try out searching & downloading with the Data API (recommended).
Otherwise, if you prefer to do it from scratch, keep reading for a step-by-step walk through of the entire process.
Conducting an image search¶
Searching for imagery in an Area of Interest while specifying our desired Item and Asset types
- Define an Area of Interest (AOI) and save it as a GeoJSON file
- Create search filters to specify the type of data you want to see
- Use the Data API to conduct a 'quick search' of the Planet catalog
- Extract the item ID of the image you would like to download from the quick search response body
- Use that Item ID to list available assets for this item (more details on Items & Assets can be found in the docs)
Activating & downloading the image¶
The Data API does not pre-generate assets, so they are not always immediately availiable to download. In order to download an asset, we first have to activate it. Once an asset has been activated, a temporary download link will become available.
- Call the
"activate"link for your desired asset to begin the activation process
- Poll the
"_self"link for the asset to check the
statusvalue: an asset will change from
activewhen it's ready for download.
- The payload of the
"_self"link you used above will now include a
locationvalue: make a GET request against that URL to begin downloading the image
Data API Alternatives¶
- Want a simpler download process with more delivery options? How about applying raster processing to your data. Meet Orders.
- Want continuous cloud delivery with a single API Call? Meet Subscriptions.
Rate this guide: