Upload and Validate Features

last updated: October 02, 2024

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 hashid. For example, if a user creates a Collection with the title set to "My Great Places", the URL path identifier used to reference the Collection will be my-great-places-HASHID (where HASHID might be 4wr3wrz, for example). The Collection may also be referenced using only the HASHID - this way the user may change the title of their Collection if needed.

Example: 

POST https://api.planet.com/features/v1/ogc/my/collections

{
    "title": "Chicago",
    "description": "AOI of the city of Chicago"
}

Sharing a feature collection

By default, Feature Collection is private (i.e, 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:

POST https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/permission

To unshare a Feature Collection make a DELETE request to: 

DELETE https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/permission

The updated collection will contain metadata to include its current permissions

permissions: {
    can_write: true,
    shared: true,
    is_owner: true,
}

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

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

Add Features by making 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
Verticies Limit No more than 1500 vertices
Features Limit Up to 1 million Features per user

Optional Feature Properties

A Feature may contain the following optional properties, all other properties will be ignored.

  • id - 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
  • title - maximum of 255 characters
  • description - maximum of 255 characters

Example: 

POST https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/items

Note: replace {collection-id} with the id for your collection (e.g. chicago-3vNEPZd). 

{
    "type": "Feature",
    "id": "your-custom-id",
    "properties": {
        "title": "City in Chicago",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor" 
    },
    "geometry": {
        "coordinates": [
            [
                [
                    -87.74931842451377,
                    42.001834785634145
                ],
                [
                    -87.74931842451377,
                    41.805592428606616
                ],
                [
                    -87.56392413740424,
                    41.805592428606616
                ],
                [
                    -87.56392413740424,
                    42.001834785634145
                ],
                [
                    -87.74931842451377,
                    42.001834785634145
                ]
            ]
        ],
        "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 Planet's 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, i.e., 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:

POST https://api.planet.com/features/v1/ogc/my/collections/validate

Example Responses:

Invalid Vertex Count

{
    "errors": [
        {
            "code": "too-many-coordinates",
            "description": "Geometry has more than 1500 points."
        }
    ],
    "description": "To see valid version of the geometry, post to the alternates_url",
    "alternates_url": "https://api.planet.com/features/v1/ogc/my/collections/alternates"
}

Self Intersection

{
    "errors": [
        {
            "code": "invalid-geometry",
            "description": "Geometry is invalid: Self-intersection[1 1]"
        }
    ],
    "description": "To see valid version of the geometry, post to the alternates_url",
    "alternates_url": "https://api.planet.com/features/v1/ogc/my/collections/alternates"
}

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.

Alternative Techqniues

Techniques Details
Make Valid img Attempts to convert the input into a valid geometry without losing the input vertices. Polygons might become a MultiPolygon
Simplify img 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 img 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
Convex Hull img The smallest polygon that contains all the points in the geometry.
Usually reduces the number of vertices but may show increased area
Bounding Box img Bounding box of the geometry. Reduces the number of vertices to 4 but increases the area

Example: 

POST https://api.planet.com/features/v1/ogc/my/collections/alternates

Example Response: 

{
    "type": "FeatureCollection",
    "features": [
        {
            "properties": {
                "technique": "Buffered by 1m and simplified"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [...]
            }
        },
        {
            "properties": {
                "technique": "Bounding box"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [...]
            }
        }
    ]
}

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 all features

Once your Features are saved you can access them via the /items endpoint. See the Pagination documentation on how to obtain all items if there are more than 100 items.

Example: 

GET https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/items

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 and its use here.

Example:

GET  https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/items/{item-id}

Viewing features on a map

The Features API provides a /map endpoint at the collection and item level that will display a slippy map for the requested item.

Example: 

GET https://api.planet.com/features/v1/ogc/my/collections/{collection-id}/items/{item-id}/map

Pro Tip

Feature Collections are useful organizational tools. If you’re working with many AOIs but they are all related to the same application or workflow, it may be best to organize them all in the same Feature Collection for easier retrieval on the platform.


We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback