Vector

Note: It is recommended to use the object oriented interface at descarteslabs.vectors.

class Vector(url=None, auth=None)[source]

Client for storing and querying vector data.

The Descartes Labs Vector service allows you store vector features (points, polygons, etc.) with associated key-value properties, and query that data by geometry or by properties.

It works best at the scale of millions of features. For small amounts of vector data that easily fit in memory, working directly with a GeoJSON file or similar may be more efficient.

Concepts:

  • “Feature”: a single geometric entity and its associated metadata (equivalent to a GeoJSON Feature).
  • “Product”: a collection of related Features, with a common name, description, and access controls.

This client currently returns data as dictionaries in JSON API format.

The parent Service class implements authentication and exponential backoff/retry. Override the url parameter to use a different instance of the backing service.

create_feature(product_id, geometry, properties=None)[source]

Add a feature to an existing vector product.

Parameters:
  • product_id (str) – (Required) Product to which this feature will belong.
  • geometry (dict) – (Required) Shape associated with this vector feature. This accepts the following types of GeoJSON geometries: - Points - MultiPoints - Polygons - MultiPolygons - LineStrings - MultiLineStrings - GeometryCollections
  • properties (dict) – Dictionary of arbitrary properties.
Return type:

DotDict
Returns:

Created Feature, as a JSON API resource collection.

The new Feature’s ID is under .data[0].id, and its properties are under .data[0].attributes.
create_features(product_id, features)[source]

Add multiple features to an existing vector product.

Parameters:
  • product_id (str) – (Required) Product to which this feature will belong.
  • features (list(dict)) – (Required) Each feature must be a dict with a geometry and properties field.
Return type:

DotDict
Returns:

Created features, as a JSON API resource collection.

The new Features’ IDs are under .data[i].id, and their properties are under .data[i].attributes.
create_product(name, title, description, owners=None, readers=None, writers=None)[source]

Add a vector product to your catalog.

Parameters:
  • name (str) – (Required) A name for this product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:. Defaults to [current user, current user’s org].
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Return type:

DotDict
Returns:

Created vector product, as a JSON API resource object.

The new product’s ID is under .data.id and its properties are under .data.attributes.
delete_product(product_id)[source]

Remove a vector product from the catalog.

Parameters:product_id (str) – ID of the vector product to remove.
get_product(product_id)[source]

Get a product’s properties.

Parameters:product_id (str) – (Required) The ID of the vector product to fetch.
Return type:DotDict
Returns:Metadata for the provided product, as a JSON API resource object.

The product’s ID is under .data.id and its properties are under .data.attributes.
list_products(limit=100, page=1)[source]

Get all vector products that you have access to.

Parameters:
  • limit (int) – Maximum number of vector products to return; max is 1000
  • page (int) – Which page of results to fetch, if there are more results than limit.
Return type:

DotDict
Returns:

Available vector products and their properties, as a JSON API collection.

The list of products is under the data key; a product’s ID is under .data[i].id and its properties are under .data[i].attributes.
replace_product(product_id, name, title, description, owners=None, readers=None, writers=None)[source]

Replace a vector product in your catalog.

Parameters:
  • product_id (str) – (Required) The vector product to replace.
  • name (str) – (Required) A name for this product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:. Defaults to [current user, current user’s org].
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Return type:

DotDict
Returns:

Replaced vector product, as a JSON API resource object

The new product’s ID is under .data.id and its properties are under .data.attributes.
search_features(product_id, geometry=None, query_expr=None, limit=None, **kwargs)[source]

Iterate over vector features within an existing product.

At least one of geometry, query_expr, or properties is required.

Parameters:
  • product_id (str) – (Required) Product within which to search.
  • geometry (dict) –

    Search for Features intersecting this shape. This accepts the following types of GeoJSON geometries:

    • Points
    • MultiPoints
    • Polygons
    • MultiPolygons
    • LineStrings
    • MultiLineStrings
    • GeometryCollections
  • query_expr (descarteslabs.client.common.filtering.Expression) – A rich query expression generator that represents an arbitrary tree of boolean combinations of property comparisons. Using the properties filter factory inside descarteslabs.client.services.vector.properties as p, you can E.g query_expr=(p.temperature >= 50) & (p.hour_of_day > 18), or even more complicated expressions like query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)) This expression gets serialized and applied to the properties mapping supplied with the features in the vector product. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.
  • limit (int) – Maximum number of features to return, defaults to all.
Return type:

Iterator
Returns:

Features satisfying the query, as JSONAPI primary data objects.

The Features’ IDs are under .id, and their properties are under .attributes.
update_product(product_id, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]

Update a vector product in your catalog.

Parameters:
  • product_id (str) – (Required) The vector product to replace.
  • name (str) – Name for this product.
  • title (str) – Official product title.
  • description (str) – Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Returns:

Updated vector product, as a JSON API resource object.
Return type:

DotDict
upload_features(file_ish, product_id)[source]

Asynchonously upload a file of Newline Delimited JSON features.

:param str|:py:class:io.IOBase file_ish: an open file object, or a path to the file to upload. :param str product_id: Product to which these features will belong.

TIMEOUT = (9.5, 60)
properties = <descarteslabs.common.property_filtering.filtering.GenericProperties object>