Uploading and Validating Features

Creating a Feature Collection

To upload an AOI Feature you must first create a Feature Collection. To create a Feature Collection make a POST request to the /collections endpoint providing a title (required) and a description (optional).

The title will be used to create a "slug" that will be part of the collection's id.

A Collection identifier is a combination of a user-supplied title and a hash ID. For example, if you create a Collection with the title set to "My Great Places", the URL path identifier used to reference the Collection will be my-great-places-{hash} (where hash might be 4wr3wrz, for example). The Collection may also be referenced using only the hash - this way the user may change the title of their Collection if needed.

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chicago",
    "description": "AOI of the city of Chicago"
  }'

Feature Collection Options

The create feature collection endpoint accepts additional options that allow you to control the display of features within Features Manager:

• title_property: individual features will take their title from the feature property with this name. For example, if your collection's features all have a property "name" that you want to use for each feature's title, set title_property to "name" when creating the collection.
• description_property: individual features will use the property defined here for their descriptions.

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Boroughs",
    "description": "Boroughs of New York City",
    "title_property": "borough_name",
    "description_property": "borough_description"
  }'

Sharing a Feature Collection

By default, Feature Collection is private (only you can see and access your Feature Collection and its Features). You can share a Feature Collection with your organization. Sharing a Feature Collection enables others in your organization to read the Collection and its Features, which might be helpful if they’d like to copy the Feature Reference IDs to make requests for data in those AOIs. The other users in your organization will not be able to make changes to the collection, or the features within it.

To share a Feature Collection make a POST request to:

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/permission \
  -u "$PL_API_KEY:"

To unshare a Feature Collection make a DELETE request to:

CURL

curl -X DELETE https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/permission \
  -u "$PL_API_KEY:"

warning

If a Feature Collection is unshared, any new attempts by other users in the organization it was shared with to reference a Feature ID will fail. However, if a Feature Reference ID was already in use, for example in an active Subscription, the Subscription will continue to work.

Add Features to a Feature Collection

After your Collection is created, Features (AOIs) can be added as either a GeoJSON Feature or FeatureCollection.

To add Features, make a POSTrequest to the /items endpoint of the collection to which you want to add features to including your GeoJSON as the body.

Rules for Creating a Feature

Features API accepts valid GeoJSON Features or FeatureCollections, with a few additional rules:

Rule
Format	Geojson
Projection	WGS84 (EPSG:4326)
Dimension	2D
Type	Polygon, MultiPolygon
Vertices Limit	No more than 1500 vertices
Features Limit	Up to 1 million Features per user

Optional Feature Properties

A Feature may contain any properties you wish to include. If you supply an id it will be used as the feature id for lookup, if not provided and automatically generated id will be provided. Accepts any string with a max of 255 characters

Example:

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Feature",
    "id": "your-custom-id",
    "properties": {
      "title": "City in Chicago",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor",
      "neighborhood": "Pilsen",
      "county": "Cook",
      "zipcode": 60608,
    },
    "geometry": {
      "coordinates": [
        [
          [-87.66620995848702, 41.86556787445056],
          [-87.66620995848702, 41.85131091539469],
          [-87.64716626253474, 41.85131091539469],
          [-87.64716626253474, 41.86556787445056],
          [-87.66620995848702, 41.86556787445056]
        ]
      ],
      "type": "Polygon"
    }
  }'

Validating a Feature

Feature geometries can be invalid for a few reasons. One common reason is that they don’t adhere to Planet’s vertex limit (1,500 vertices).

The Features API enables you to check if your Feature geometry is valid for use in the Planet Platform before uploading it to your Feature Collection. The /validate endpoint provides more details as to why a geometry is invalid, such as not meeting the vertex limit. The validation endpoint only supports validating Features. For example, you cannot validate a Feature Collection.

To validate a feature make a POST request to /collections/validate with the feature to validate as the body.

Example:

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections/validate \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Feature",
    "id": "your-custom-id",
    "geometry": {
      "coordinates": [
        [
          [-87.74931842451377, 42.001834785634145],
          [-87.74931842451377, 41.805592428606616],
          [-87.56392413740424, 41.805592428606616],
          [-87.56392413740424, 42.001834785634145],
          [-87.74931842451377, 42.001834785634145]
        ]
      ],
      "type": "Polygon"
    }
  }'

Alternate Valid Geometries

If a feature is flagged as invalid you can make a request to the /alternates endpoint which provides recommendations and details about the technique used to alter the provided geometry so that it meets Planet's validity requirements.

The result of /alternates endpoint is sorted in ascending order based on which alternatives have the smallest change in area.

note

The original geometry provided may not have valid alternatives. The result of /alternates only contains valid alternatives.

Alternate Methods

Method		Details
Make Valid		Attempts to convert the input into a valid geometry without losing the input vertices. Polygons might become a MultiPolygon
Simplify		Simplifies the polygon with an adaptive tolerance adjustment (from 1 to 10 meters). Reduces the number of vertices and preserves the overall shape of the original geometry
Buffer and Simplify		Buffers the polygon by ~1m and then simplifies the geometry. Reduces the number of vertices and preserves the overall shape of the original geometry with a slight area increase
Concave Hull		A boundary that tightly wraps a set of points, including inward curves for a closer fit to the shape. Usually reduces the number of vertices but may show increased area
Convex Hull		The smallest convex polygon that contains all the points in the geometry. Usually reduces the number of vertices but may show increased area
Bounding Box		Bounding box of the geometry. Reduces the number of vertices to 4 but increases the area

Example:

CURL

curl -X POST https://api.planet.com/features/v1/ogc/my/collections/alternates \
  -u "$PL_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Feature",
    "id": "your-custom-id",
    "geometry": {
      "coordinates": [
        [
          [-87.74931842451377, 42.001834785634145],
          [-87.74931842451377, 41.805592428606616],
          [-87.56392413740424, 41.805592428606616],
          [-87.56392413740424, 42.001834785634145],
          [-87.74931842451377, 42.001834785634145]
        ]
      ],
      "type": "Polygon"
    }
  }'

note

The Features API checks validation rules also apply to Planet’s delivery APIs like the Orders and Subscriptions API. If your Feature is valid in the Features API it should work as a reference in the Orders and Subscription APIs.

Accessing your Features

List collections

The /collections endpoint supports listing collections that you have created or that have been shared with you.

Example:

CURL

curl https://api.planet.com/features/v1/ogc/my/collections \
  -u "$PL_API_KEY:"

List all Features

After your Features are saved you can access them via the /items endpoint.

Example:

CURL

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items \
  -u "$PL_API_KEY:"

Retrieve a Feature

To view a single feature, include its ID as a path parameter.

The Feature Reference ID can be accessed for an individual feature via pl:ref in the properties. Learn more about feature references here.

Example:

CURL

curl https://api.planet.com/features/v1/ogc/my/collections/${COLLECTION_ID}/items/${FEATURE_ID} \
  -u "$PL_API_KEY:"

Optional Parameters

The list and retrieve features endpoints accept the following optional query parameters to control the format of the responses:

• _view=basic: the geometry of listed features will be a rectangular bounding box instead of the feature's full geometry.
• _view=refs: return only feature references.
• _geom=wkb64: the geometry will be represented using a base64 encoded WKB (well-known bytes) string.

Viewing Features using Features Manager

Collections and features uploaded using the Features API will be available in Features Manager.

tip

Feature Collections are useful organizational tools. If you are working with many AOIs but they are all related to the same application or workflow, we recommend organizing them all in the same Feature Collection for easier retrieval on the platform.