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.

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.

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_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_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.

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.

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 value str that in ISO-8601 format or a value that has a isoformat callable that returns an ISO-8601 str.

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.

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
await()

Await completion of this request.

Returns Body:A Body object containing the response.
cancel()

Cancel any request.

get_body()

Get the response Body

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, **kw)

Create a Downloader with the provided client.

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