Reference

The public and stable API functions, classes and exceptions are all provided by the planet.api namespace.

The Client Object

The Client class is the supported way to access the API.

Unless specific functionality is needed, the correct way to instantiate a Client is with zero arguments.

The Client will resolve the API_KEY from the operating system environment using the PL_API_KEY value.

client = api.ClientV1()
class planet.api.ClientV1

ClientV1 provides basic low-level access to Planet’s API. Only one ClientV1 should be in existence for an application. The Client is thread safe and takes care to avoid API throttling and also retry any throttled requests. Most functions take JSON-like dict representations of API request bodies. Return values are usually a subclass of planet.api.models.Body. Any exceptional http responses are handled by translation to one of the planet.api.exceptions classes.

activate(asset)

Request activation of the specified asset representation.

Asset representations are obtained from get_assets().

Parameters

dict (request) – An asset representation from the API.

Returns

planet.api.models.Body with no response content

Raises

planet.api.exceptions.APIException – On API error.

check_analytics_connection()

Validate that we can use the Analytics API. Useful to test connectivity to test environments. :returns: planet.api.models.JSON

Create a new saved search from the specified request. The request must contain a name property.

Parameters

request – see Client Search Requests

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

download(asset, callback=None)

Download the specified asset. If provided, the callback will be invoked asynchronously. Otherwise it is up to the caller to handle the response Body.

Parameters
  • dict (asset) – An asset representation from the API

  • callback – An optional function to aysnchronsously handle the download. See planet.api.write_to_file()

Returns

planet.api.models.Response containing a planet.api.models.Body of the asset.

Raises

planet.api.exceptions.APIException – On API error.

download_quad(quad, callback=None)

Download the specified mosaic quad. If provided, the callback will be invoked asynchronously. Otherwise it is up to the caller to handle the response Body.

Parameters
  • dict (asset) – A mosaic quad representation from the API

  • callback – An optional function to aysnchronsously handle the download. See planet.api.write_to_file()

Returns

planet.api.models.Response containing a planet.api.models.Body of the asset.

Raises

planet.api.exceptions.APIException – On API error.

get_assets(item)

Get the assets for the provided item representations.

Item representations are obtained from search requests.

Parameters

dict (request) – An item representation from the API.

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

get_assets_by_id(item_type, id)

Get an item’s asset response for the given item_type and id

Parameters
  • str (id) – A valid item-type

  • str – The id of the item

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

get_associated_resource_for_analytic_feature(subscription_id, feature_id, resource_type)

Get resource associated with some feature in an analytic subscription. Response might be JSON or a TIF, depending on requested resource. :param subscription_id str: ID of subscription :param feature_id str: ID of feature :param resource_type str: Type of resource to request. :raises planet.api.exceptions.APIException: On API error or resource type unavailable. :returns: planet.api.models.JSON for resource type source-image-info, but can also return planet.api.models.Response containing a planet.api.models.Body of the resource.

get_collection_info(subscription_id)

Get the information describing a specific collection. :param subscription_id: :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.JSON

get_feed_info(feed_id)

Get the information describing a specific collection. :param subscription_id: :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.JSON

get_item(item_type, id)

Get the an item response for the given item_type and id

Parameters
  • str (id) – A valid item-type

  • str – The id of the item

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

get_mosaic_by_name(name)

Get the API representation of a mosaic by name.

Parameters

str (name) – The name of the mosaic

Returns

planet.api.models.Mosaics

Raises

planet.api.exceptions.APIException – On API error.

get_mosaic_series(series_id)

Get information pertaining to a mosaics series :returns: planet.api.models.JSON

get_mosaics(name_contains=None)

Get information for all mosaics accessible by the current user.

Returns

planet.api.models.Mosaics

get_mosaics_for_series(series_id)

Get list of mosaics available for a series :returns: planet.api.models.Mosaics

get_quad_by_id(mosaic, quad_id)

Get a quad response for a specific mosaic and quad.

Parameters
  • dict (mosaic) – A mosaic representation from the API

  • str (quad_id) – A quad id (typically <xcoord>-<ycoord>)

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

get_quad_contributions(quad)

Get information about which scenes contributed to a quad.

Parameters

dict (quad) – A quad representation from the API

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

get_quads(mosaic, bbox=None)

Search for quads from a mosaic that are inside the specified bounding box. Will yield all quads if no bounding box is specified.

Parameters
  • dict (mosaic) – A mosaic representation from the API

  • tuple (bbox) – A lon_min, lat_min, lon_max, lat_max area to search

Returns

planet.api.models.MosaicQuads

Raises

planet.api.exceptions.APIException – On API error.

get_searches(quick=False, saved=True)

Get searches listing.

Parameters
  • bool (quick) – Include quick searches (default False)

  • saved (quick) – Include saved searches (default True)

Returns

planet.api.models.Searches

Raises

planet.api.exceptions.APIException – On API error.

get_subscription_info(subscription_id)

Get the information describing a specific subscription. :param subscription_id: :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.JSON

list_analytic_collections()

Get collections that the authenticated user has access to :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.WFS3Collections

list_analytic_feeds(stats)

Get collections that the authenticated user has access to :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.Feeds

list_analytic_subscriptions(feed_id)

Get subscriptions that the authenticated user has access to :param feed_id str: Return subscriptions associated with a particular feed only. :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.Subscriptions

list_collection_features(subscription_id, bbox, time_range)

List features for an analytic subscription. :param subscription_id: :param time_range str: ISO format datetime interval. :param bbox tuple: A lon_min, lat_min, lon_max, lat_max area to search :raises planet.api.exceptions.APIException: On API error. :returns: planet.api.models.WFS3Features

Execute a quick search with the specified request.

Parameters
Returns

planet.api.models.Items

Raises

planet.api.exceptions.APIException – On API error.

Options

  • page_size (int): Size of response pages

  • sort (string): Sorting order in the form field (asc|desc)

Execute a saved search by search id.

Parameters

string (sid) – The id of the search

Returns

planet.api.models.Items

Raises

planet.api.exceptions.APIException – On API error.

Options

  • page_size (int): Size of response pages

  • sort (string): Sorting order in the form field (asc|desc)

stats(request)

Get stats for the provided request.

Parameters

dict (request) – A search request that also contains the ‘interval’ property.

Returns

planet.api.models.JSON

Raises

planet.api.exceptions.APIException – On API error.

wfs_conformance()

Details about WFS3 conformance :returns: planet.api.models.JSON

Client Search Requests

The general search request form is a Python dict, for example.

{
  "item_types": ['PSScene3Band'],
  "filter": {
    "type": "AndFilter",
    "config": [
      "type": "RangeFilter",
      "field_name": "cloud_cover",
      "config": {
        "lte": 0.5
      }
    ]
  }
}

The stats function requires an additional interval property in the request body.

When creating a saved search, the name property in the request body will be used to give the new search a name.

Note

Request and Filter logic is not validated on the client.

Filters

The filters module provides a small convenience layer for building filters and requests.

planet.api.filters.and_filter(*predicates)

Build an and filter from the provided predicate filters.

>>> filt = and_filter(
...   range_filter('cloud_cover', gt=0.1),
...   range_filter('cloud_cover', lt=0.2)
... )
>>> filt['type']
'AndFilter'
>>> filt['config'][0] ==     {'config': {'gt': 0.1}, 'field_name': 'cloud_cover', 'type': 'RangeFilter'}
True
>>> filt['config'][1] ==     {'config': {'lt': 0.2}, 'field_name': 'cloud_cover', 'type': 'RangeFilter'}
True
planet.api.filters.build_search_request(filter_like, item_types, name=None, interval=None)

Build a data-api search request body for the specified item_types. If ‘filter_like’ is a request, item_types will be merged and, if name or interval is provided, will replace any existing values.

Parameters
  • filter_like (dict) – a filter or request with a filter

  • item_types (sequence(str)) – item-types to specify in the request

  • name (str) – optional name

  • interval (str) – optional interval [year, month, week, day]

planet.api.filters.date_range(field_name, **kwargs)

Build a DateRangeFilter.

Predicate arguments accept a str that is ISO-8601 format or a value that has an isoformat callable that returns an ISO-8601 compliant str.

If no timezone is provided, UTC is assumed for RFC 3339 compatability.

Raises

ValueError if predicate value does not parse

>>> date_range('acquired', gt='2017') ==     {'config': {'gt': '2017-01-01T00:00:00Z'},     'field_name': 'acquired', 'type': 'DateRangeFilter'}
True
planet.api.filters.geom_filter(geom, field_name=None)

Build a GeometryFilter from the provided geosjon geom dict.

Parameters
  • geom (geojson) – the geojson geom dict

  • field_name (str) – optional field name, default is ‘geometry’

planet.api.filters.is_filter_like(filter_like)

Check if the provided dict looks like a search request or filter.

planet.api.filters.num_filter(field_name, *vals)

Build a NumberInFilter.

>>> num_filter('value', 50, 100) ==     {'config': (50, 100), 'field_name': 'value', 'type': 'NumberInFilter'}
True
planet.api.filters.or_filter(*predicates)

Build an or filter from the provided predicate filters.

>>> import datetime
>>> n = datetime.datetime(year=2017, month=2, day=14)
>>> filt = or_filter(
...   date_range('acquired', gt=n),
...   range_filter('cloud_cover', gt=0.1),
... )
>>> filt['type']
'OrFilter'
>>> filt['config'][0] ==     {'config': {'gt': '2017-02-14T00:00:00Z'}, 'field_name': 'acquired',     'type': 'DateRangeFilter'}
True
>>> filt['config'][1] ==     {'config': {'gt': 0.1}, 'field_name': 'cloud_cover', 'type': 'RangeFilter'}
True
planet.api.filters.permission_filter(*perms)

Build a PermissionFilter with the specified permissions.

>>> permission_filter('assets:download') ==     {'type': 'PermissionFilter', 'config': ('assets:download',)}
True
planet.api.filters.range_filter(field_name, **kwargs)

Build a RangeFilter.

>>> range_filter('cloud_cover', gt=0.1) ==     {'config': {'gt': 0.1}, 'field_name': 'cloud_cover', 'type': 'RangeFilter'}
True
planet.api.filters.string_filter(field_name, *vals)

Build a StringInFilter.

>>> string_filter('id', 'id1', 'id2', 'id3') ==     {'config': ('id1', 'id2', 'id3'), 'field_name': 'id',     'type': 'StringInFilter'}
True

Client Return Values

Most Client methods return a Body subclass that provides access to the HTTP response body in addition to the HTTP request and response details.

For many responses, it is sufficient to use the get method to obtain the HTTP response as JSON.

For paginated responses, the Paged provides convenience functions to explicitly page through results as well as an iterator to the underlying items in each response.

Download functions return a Response object that handles some aspects of asynchronous execution. Namely, streaming chunks to a handler to prevent memory issues and awaiting completion of the task.

The basic Body methods include:

class planet.api.models.Body

A Body is a representation of a resource from the API.

get_raw()

Get the decoded text content from the response

last_modified()

Read the last-modified header as a datetime, if present.

property name

The name of this resource. The default is to use the content-disposition header value from the response.

write(file=None, callback=None)

Write the contents of the body to the optionally provided file and providing progress to the optional callback. The callback will be invoked 3 different ways:

  • First as callback(start=self)

  • For each chunk of data written as callback(wrote=chunk_size_in_bytes, total=all_byte_cnt)

  • Upon completion as callback(finish=self)

Parameters
  • file – file name or file-like object

  • callback – optional progress callback

The Response class returned by download functions has two methods:

class planet.api.models.Response
cancel()

Cancel any request.

get_body()

Get the response Body

Returns Body

A Body object containing the response.

wait()

Await completion of this request.

Returns Body

A Body object containing the response.

Most responses are more specific than a body. The JSON body provides the contents as JSON.

class planet.api.models.JSON

A Body that contains JSON

get()

Get the response as a JSON dict

Paginated responses provide a paging iterator as well as an iterator of each pages contents.

The Paged.items_iter() method provides iteration over the contents of each page response.

For examples, an Items response page contains a FeatureCollection of zero or more Item objects. Each Item is a record represented as a GeoJSON feature with properties describing it’s metadata. When using the iterator from the Paged.items_iter() method, only Item Feature objects will be returned.

To handle assembling the items from each page into a collection again and streaming them as JSON, use the Paged.json_encode() method.

class planet.api.models.Paged
items_iter(limit)

Get an iterator of the ‘items’ in each page. Instead of a feature collection from each page, the iterator yields the features.

Parameters

limit (int) – The number of ‘items’ to limit to.

Returns

iter of items in page

iter(pages=None)

Get an iterator of pages.

Parameters

pages (int) – optional limit to number of pages

Returns

iter of this and subsequent pages

json_encode(out, limit=None, sort_keys=False, indent=None)

Encode the results of this paged response as JSON writing to the provided file-like out object. This function will iteratively read as many pages as present, streaming the contents out as JSON.

Parameters
  • out (file-like) – an object with a write function

  • limit (int) – optional maximum number of items to write

  • sort_keys (bool) – if True, output keys sorted, default is False

  • indent (bool) – if True, indent output, default is False

class planet.api.models.Items

Items is a Body that contains a FeatureCollection so when using items_iter, it will yield Feature GeoJSON objects.

class planet.api.models.Searches

Searches is a Body that contains an array of searches, so when using items_iter, it will yield Search JSON objects.

Utilities

planet.api.write_to_file(directory=None, callback=None, overwrite=True)

Create a callback handler for asynchronous Body handling.

If provided, the callback will be invoked as described in planet.api.models.Body.write(). In addition, if the download is skipped because the destination exists, the callback will be invoked with callback(skip=body).

The name of the file written to will be determined from the Body.name property.

Parameters
  • str (directory) – The optional directory to write to.

  • func (callback) – An optional callback to receive notification of write progress.

  • bool (overwrite) – Overwrite any existing files. Defaults to True.

Activating and Downloading Many Assets

A common use case is to activate and download the results of a search. While the Client provides the lower-level functionality for this, the Downloader class provides convenience for managing this process for a large number of items and assets.

Create a downloader using:

planet.api.downloader.create(client, mosaic=False, **kw)

Create a Downloader with the provided client.

Parameters

bool (mosaic) – If True, the Downloader will fetch mosaic quads.

Returns

planet.api.downloader.Downloader

class planet.api.downloader.Downloader

A Downloader manages activation and download of Item Assets from the Data API. A Downloader should only be processing one request to either activate or download at a time. These functions are synchronous and will return on completion. Completion of activation or download events can be tracked by changing the on_complete method of the Downloader while the stats function allows for polling of internal state.

activate(items, asset_types)

Request activation of specified asset_types for the sequence of items.

Parameters
  • items – a sequence of Item representations.

  • list (asset_types) – list of asset-type (str)

download(items, asset_types, dest)

Request activation and download of specified asset_types for the sequence of items.

Parameters
  • items – a sequence of Item representations.

  • list (asset_types) – list of asset-type (str)

  • str (dest) – Download destination directory, must exist.

on_complete(item, asset, path=None)

Notification of processing an item’s asset, invoked on completion of activate or download.

Parameters
  • item – The API representation of the item

  • asset – The API representation of the asset

  • path – If downloaded, the location of the downloaded asset, otherwise None

shutdown()

Halt execution.

stats()

Retrieve internal state of the Downloader.

Returns a dict of state:

  • paging: bool indicating that search results are being processed

  • activating: int number of items in the inactive or activating state

  • downloading: int number of items actively downloading

  • downloaded: string representation of MB transferred

  • complete: int number of completed downloads

  • pending: int number of items awaiting download

Client Exceptions

In addition to other exceptions, expected or otherwise, each HTTP operation has the potential to raise one of the following exceptions:

exception planet.api.exceptions.APIException

General unexpected response

exception planet.api.exceptions.BadQuery

Invalid inputs, HTTP 400

exception planet.api.exceptions.InvalidAPIKey

Invalid key, HTTP 401

exception planet.api.exceptions.InvalidIdentity

Raised when logging in with invalid credentials

exception planet.api.exceptions.MissingResource

Request for non existing resource, HTTP 404

exception planet.api.exceptions.NoPermission

Insufficient permissions, HTTP 403

exception planet.api.exceptions.OverQuota

Quota exceeded, HTTP 429

exception planet.api.exceptions.RequestCancelled

Internal exception when a request is cancelled

exception planet.api.exceptions.ServerError

Unexpected internal server error, HTTP 500

exception planet.api.exceptions.TooManyRequests

Too many requests, HTTP 429