API Modules

The @planet/client package is organized as a collection of modules that roughly follow the structure of the HTTP API. The API provides access to imagery (items) organized by type.

@planet/client/api/auth

Provides methods for authenticating with a Planet API account. Authentication is required when searching for imagery, and clients can authenticate by either providing a valid email/password pair or an API key. Use the auth.login() method with an email and password or the auth.setKey() method with an API key.

var auth = require('@planet/client/api/auth');

auth.login(email, password)

Submit credentials for authentication. Upon successful authentication, a token representing the user will be stored for subsequent API requests.

Arguments

email string

The email associated with a Planet account.
password string

The password for a Planet account.

Returns

Promise

A promise that resolves on successful login and is rejected otherwise.

auth.logout()

Clear any stored credentials.

auth.setKey(key)

Set an API key to be used for subsequent requests. This is an alternative to submitting credentials with the login method. The stored key will be used for subsequent API requests.

Arguments

key string

An API key.

@planet/client/api/errors

Includes specific Error types generated by API requests. When a request method returns a promise that is rejected, you can use instanceof to determine what type of error you have.

var errors = require('@planet/client/api/errors');

errors.ResponseError

The base class for all response errors.

Properties

message string

A message providing details about the error.
response IncomingMessage

The server response.
body Object

Any parsed response body. For "expected" errors, this will be an object representing the JSON response body.
stack string

The stack trace for the error.

errors.BadRequest

The request was bad (status 400).

Properties

message string

A message providing details about the error.
response IncomingMessage

The server response.
body Object

Any parsed response body. For "expected" errors, this will be an object representing the JSON response body.
stack string

The stack trace for the error.

errors.Unauthorized

The request requires user authentication (status 401).

Properties

message string

A message providing details about the error.
response IncomingMessage

The server response.
body Object

Any parsed response body. For "expected" errors, this will be an object representing the JSON response body.
stack string

The stack trace for the error.

errors.Forbidden

The client is forbidden from making the request (status 403).

Properties

message string

A message providing details about the error.
response IncomingMessage

The server response.
body Object

Any parsed response body. For "expected" errors, this will be an object representing the JSON response body.
stack string

The stack trace for the error.

errors.UnexpectedResponse

The API returns an unexpected response.

Properties

message string

A message providing details about the error.
response IncomingMessage

The server response.
body Object

Any parsed response body. For "expected" errors, this will be an object representing the JSON response body.
stack string

The stack trace for the error.

errors.ClientError

An error generated on the client side, before issuing a request.

@planet/client/api/filter

Convenience functions for creating search filters. These functions return objects that can be used as the filter property when searching for items with items.search() or when saving a search with searches.create().

var filter = require('@planet/client/api/filter');

filter.and(filters)

Creates a logical AndFilter.

Arguments

filters Array.<Object>

A list of filter objects.

Returns

Object

A filter that will match items that match all of the child filters.

filter.or(filters)

Creates a logical OrFilter.

Arguments

filters Array.<Object>

A list of filter objects.

Returns

Object

A filter that will match items that match any of the child filters.

filter.not(filters)

Creates a logical NotFilter.

Arguments

filters Array.<Object>

A list of filter objects.

Returns

Object

A filter that will match items that do not match any of the child filters.

filter.dates(field, range)

Creates a DateRangeFilter.

Arguments

field string

The name of the date field to use in the filter.
range Object

An object with gte, gt, lt, or lte properties with dates (for "greater than or equal to", "greater than", "less than", and "less than or equal to"). Open ended ranges are possible.

Returns

Object

A filter that will match items with dates in the range of provided dates.

filter.geometry(field, geometry)

Creates a GeometryFilter.

Arguments

field string

The name of the geometry field to use in the filter.
geometry Object

A GeoJSON geometry.

Returns

Object

A filter that will match items that intersect the provided geometry.

filter.numbers(field, values)

Creates a NumberInFilter.

Arguments

field string

The name of the numeric field to use in the filter.
values Array.<number>

A list of numbers.

Returns

Object

A filter that will match items whose field value matches any of the provided numbers.

filter.range(field, range)

Creates a RangeFilter.

Arguments

field string

The name of the numeric field to use in the filter.
range Object

An object with gte, gt, lt, or lte properties with dates (for "greater than or equal to", "greater than", "less than", and "less than or equal to"). Open ended ranges are possible.

Returns

Object

A filter that will match items with values in the range of provided numbers.

filter.strings(field, values)

Creates a StringInFilter.

Arguments

field string

The name of the string field to use in the filter.
values Array.<string>

A list of strings.

Returns

Object

A filter that will match items whose field value matches any of the provided strings.

filter.permissions(values)

Creates a PermissionFilter.

Arguments

values Array.<string>

A list of permissions.

Returns

Object

A filter that will match items that have all of the provided permissions.

@planet/client/api/items

Provides methods to get imagery (or item) metadata. Individual images are identified by an item type and id. To access metadata for a single image, use items.get(). To search for metadata about multiple items, use items.search().

var items = require('@planet/client/api/items');

items.get(type, id, options)

Get metadata for a single item.

Arguments

type string

An item type identifier.
id string

An item identifier.
options Object

Options.
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Object>

A promise that resolves to item metadata or is rejected with any error. See the errors module for a list of the possible error types.

items.search(options)

Get metadata for multiple items.

Arguments

options Object

Options.
options.types Array.<string>

A list of item type identifiers.
options.filter Object

A filter object for the search.
options.id string

A saved search identifier. This can be provided as an alternative to types and filter to get items from a previously saved search.
options.query Object

An object with optional _page_size and _sort parameters.
options.limit number

Limit the result set to this size (by default, no limit is applied).
options.each function

A function that is called once for each page of data. The each callback takes 3 arguments. The first is an array of features. The second is a boolean representing whether there are more results, the third is a function that gets the next page of results. If each returns false, it prevents automatic paging. If the each callback is absent, all data will be concatenated and provided when the promise resolves.
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Array>

A promise that resolves when all data is finished loading or is rejected with any error. If an each callback is not provided, the promise will resolve with all data concatenated. See the errors module for a list of the possible error types.

@planet/client/api/searches

Provides methods for working with saved searches.

var searches = require('@planet/client/api/searches');

searches.get(id, options)

Get metadata for a single search.

Arguments

id string

A search identifier.
options Object

Options.
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Object>

A promise that resolves to search metadata or is rejected with any error. See the errors module for a list of the possible error types.

searches.search(options)

Get metadata for multiple searches.

Arguments

options Object

Options.
options.query Object

A query object. By default search_type is set to 'saved', so only saved searches will be returned. To get metadata on saved and quick searches, set query: {search_type: 'all'}.
options.each function

A function that is called once for each page of data. If the each callback is absent, all data will be concatenated and provided when the promise resolves.
options.limit number

Limit the result set to this size (by default, no limit is applied).
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Array>

A promise that resolves when all data is finished loading or is rejected with any error. If an each callback is not provided, the promise will resolve with all data concatenated. See the errors module for a list of the possible error types.

searches.create(options)

Create a new saved search.

Arguments

options Object

Options.
options.name string

Search name (required).
options.types Array.<string>

A list of item type identifiers (required).
options.filter Object

A filter object for the search (required).
options.notification boolean

Send email notification when new imagery matches search criteria (false by default).

Returns

Promise.<Object>

A promise that resolves to the new search or is rejected with any error. See the errors module for a list of the possible error types.

searches.update(id, options)

Update a saved search.

Arguments

id string

Search identifier.
options Object

Options.
options.name string

Search name.
options.types Array.<string>

A list of item type identifiers.
options.filter Object

A filter object for the search.
options.notification boolean

Send email notification when new imagery matches search criteria.

Returns

Promise.<Object>

A promise that resolves to the updated search or is rejected with any error. See the errors module for a list of the possible error types.

searches.remove(id)

Remove a saved search.

Arguments

id string

Search identifier.

Returns

Promise

A promise that resolves if the search was removed or is rejected with any error. See the errors module for a list of the possible error types.

@planet/client/api/types

Provides methods to get information on the available item types.

var types = require('@planet/client/api/types');

types.get(id, options)

Get metadata for a single item type.

Arguments

id string

An item type identifier.
options Object

Options.
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Object>

A promise that resolves to item type metadata or is rejected with any error. See the errors module for a list of the possible error types.

types.search(options)

Get metadata for multiple item types.

Arguments

options Object

Options.
options.query Object

A query object.
options.each function

A function that is called once for each page of data. If the each callback is absent, all data will be concatenated and provided when the promise resolves.
options.terminator function

A function that is called with a function that can be called back to terminate the request.

Returns

Promise.<Array>

A promise that resolves when all data is finished loading or is rejected with any error. If an each callback is not provided, the promise will resolve with all data concatenated. See the errors module for a list of the possible error types.