Upload and Validate 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 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/v0/ogc/my/collections

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

Collection limits¶

• A user may create up to 200 collections
• title property is limited to 50 characters
• description property is limited to 255 characters

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/v0/ogc/my/collections/{collection-id}/permission

To unshare a Feature Collection make a DELETE request to:

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

The updated collection will contain metadata to include its current permissions

permissions: {
    can_write: true,
    shared_with_my_org: true
}

Add features to a feature collection¶

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

• Polygon
• MultiPolygon

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.

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

Limits:

• Up to 5,000 features per collection
• Feature may have no more than 1500 verticies
• Only WGS84 (EPSG:4326) projection is supported

Example:

POST https://api.planet.com/features/v0/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/v0/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/v0/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/v0/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.

Example:

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

Example Response:

{
    "type": "FeatureCollection",
    "features": [
        {
            "properties": {
                "technique": "Bounding box"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [...]
            }
        },
        {
            "properties": {
                "technique": "Simplified to ~0.5m"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [...]
            }
        }
    ]
}

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/v0/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/v0/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/v0/ogc/my/collections/{collection-id}/items/{item-id}/map