Vector

Warning

This low-level client has been replaced with the object-oriented Tables client.


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 id, description, and access controls.

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

Parameters

  • url (str) – URL for the vector service. Only change this if you are being asked to use a non-default Descartes Labs catalog. If not set, then descarteslabs.config.get_settings().VECTOR_URL will be used.

  • auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)

  • retries (urllib3.util.retry.Retry) – A custom retry configuration used for all API requests (defaults to a reasonable amount of retries)

Attributes:

SEARCH_PAGE_SIZE

TIMEOUT

properties

Methods:

count_features(product_id)

Get the count of the features in a product.

create_feature(product_id, geometry[, …])

Add a feature to an existing vector product.

create_features(product_id, features[, …])

Add multiple features to an existing vector product.

create_product(product_id, title, description)

Add a vector product to your catalog.

create_product_from_query(new_product_id, …)

Query vector features within an existing product and create a new vector product to your catalog from the query result.

delete_features_from_query(product_id[, …])

Query an existing Vector product and delete features that match the query results.

delete_product(product_id)

Remove a vector product from the catalog.

export_product_from_query(product_id, key[, …])

Query vector features within an existing product and export the result to DescartesLabs Storage as type data using the given storage key.

get_delete_features_status(product_id)

Get the status of the job deleting features from a query.

get_export_result(product_id, export_id)

Get details about a specific export job.

get_export_results(product_id)

Get a list of the exports submitted to a vector product, and status information about each.

get_product(product_id)

Get a product’s properties.

get_product_from_query_status(product_id)

Get the status of the job creating a new product from a query.

get_upload_result(product_id, upload_id[, …])

Get details about a specific upload job.

get_upload_results(product_id[, pending])

Get a list of the uploads submitted to a vector product, and status information about each.

list_products([page_size, page])

Get all vector products that you have access using JSON API pagination.

replace_product([product_id, name, title, …])

Replace a vector product in your catalog.

search_features(product_id[, geometry, …])

Iterate over vector features within an existing product.

update_product(product_id[, name, title, …])

Update a vector product in your catalog using the given parameters.

upload_features(file_ish, product_id[, …])

Asynchonously upload a file or stream of Newline Delimited JSON features.Note that the file may not contain empty lines or lines containing anything but the feature (including e.g.a trailing comma), or such lines will cause errors..
count_features(product_id)[source]

Get the count of the features in a product.

Parameters

product_id (str) – (Required) The ID of the product to count all features for.

Return type

int

Returns

The total number of features in a product.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

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

Add a feature to an existing vector product.

Parameters

  • product_id (str) – (Required) The ID of the Vector product to which this feature will belong.

  • geometry (dict) –

    (Required) Shape associated with this vector feature. This accepts the following types of GeoJSON or Shapely geometries:

    • Points

    • MultiPoints

    • Polygons

    • MultiPolygons

    • LineStrings

    • MultiLineStrings

    • GeometryCollections

  • properties (dict) – Dictionary of arbitrary properties.

  • fix_geometry (str) – String specifying how to handle certain problem geometries, including those which do not follow counter-clockwise winding order (which is required by the GeoJSON spec but not many popular tools). Allowed values are reject (reject invalid geometries with an error), fix (correct invalid geometries if possible and use this corrected value when creating the feature), and accept (the default) which will correct the geometry for internal use but retain the original geometry in the results.

Return type

DotDict

Returns

Created Feature, as a JSON API resource collection. The keys are:

data: A "DotDict" instance with the following keys:

    id:        The ID of the feature.
    type:      "feature".
    attributes: A DotDict instance with the following keys:

        created:    Time that the task was created in
                    ISO-8601 UTC.
        properties: A DotDict instance.  The keys are
                    user provided.  Supported values
                    are strings, numbers, the value "None".
        geometry:   A DotDict instance with the following keys:

            type:        The type of the feature, one of
                         ["Polygon", "MultiPolygon",
                         "Point", "MultiPoint",
                         "LineString", "MultiLineString",
                         or "GeometryCollection"].
            coordinates: A list of coordinates; the
                         exact structure of
                         potentially nesting lists
                         depends on the given type.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

create_features(product_id, features, fix_geometry='accept')[source]

Add multiple features to an existing vector product.

Parameters

  • product_id (str) – (Required) The ID of the Vector product to which these features will belong.

  • features (list(dict)) – (Required) Each feature must be a dict with a geometry and properties field. If you provide more than 100 features, they will be batched in groups of 100, but consider using upload_features() instead.

  • fix_geometry (str) – String specifying how to handle certain problem geometries, including those which do not follow counter-clockwise winding order (which is required by the GeoJSON spec but not many popular tools). Allowed values are reject (reject invalid geometries with an error), fix (correct invalid geometries if possible and use this corrected value when creating the feature), and accept (the default) which will correct the geometry for internal use but retain the original geometry in the results.

Return type

DotDict

Returns

The features as a JSON API resource object. The keys are:

data: A list of "DotDict" instances with the following keys:

    id:        The ID of the feature.
    type:      "feature".
    attributes: A DotDict instance with the following keys:

        created:    Time that the task was created in
                    ISO-8601 UTC.
        properties: A DotDict instance.  The keys are
                    user provided.  Supported values
                    are strings, numbers, the value "None".
        geometry:   A DotDict instance with the following keys:

            type:        The type of the feature, one of
                         ["Polygon", "MultiPolygon",
                         "Point", "MultiPoint",
                         "LineString", "MultiLineString",
                         or "GeometryCollection"].
            coordinates: A list of coordinates; the
                         exact structure of
                         potentially nesting lists
                         depends on the given type.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • BadRequestError – Raised when the request is malformed. May also indicate that too many features were included. If more than 100 features were provided, some of these features may have been successfuly inserted while others may not have been inserted.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

create_product(product_id, title, description, owners=None, readers=None, writers=None)[source]

Add a vector product to your catalog.

Parameters

  • product_id (str) – (Required) A unique name for this Vector product. In the created product a namespace consisting of your user id (e.g. ae60fc891312ggadc94ade8062213b0063335a3c:) or your organization id (e.g., yourcompany:) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique.

  • title (str) – (Required) Official product title.

  • description (str) – (Required) Information about the product, why it exists, and what it provides.

  • owners (list(str)) – 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].

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

  • writers (list(str)) – 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. For a list of keys, please see get_product().

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the supplied product id is already in use.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

create_product_from_query(new_product_id, title, description, product_id, owners=None, readers=None, writers=None, geometry=None, query_expr=None, query_limit=None)[source]

Query vector features within an existing product and create a new vector product to your catalog from the query result.

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

Parameters

  • new_product_id (str) – (Required) A unique name for this product. In the created product a namespace consisting of your user id (e.g. ae60fc891312ggadc94ade8062213b0063335a3c:) or your organization id (e.g., yourcompany:) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique.

  • title (str) – (Required) Official product title.

  • description (str) – (Required) Information about the product, why it exists, and what it provides.

  • product_id (str) – (Required) The ID of the product within which to search.

  • owners (list(str)) – 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].

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

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

  • geometry (dict) –

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

    • Points

    • MultiPoints

    • Polygons

    • MultiPolygons

    • LineStrings

    • MultiLineStrings

    • GeometryCollections

  • query_expr (Expression) – Expression used to filter features by their properties, built from dl.properties. You can construct filter expression using the ==, !=, <, >, <= and >= operators as well as the like() and in_() methods. You cannot use the boolean keywords and and or because of Python language limitations; instead you can combine filter expressions with & (boolean “and”) and | (boolean “or”). Example (assuming from descarteslabs import properties as p): query_expr=(p.temperature >= 50) & (p.hour_of_day > 18). More complex example: query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)). If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.

  • query_limit (int) – Maximum number of features to return for this query, defaults to all.

Return type

DotDict

Returns

Created vector product, as a JSON API resource object. For a description of the keys, please see get_product().

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the supplied new product id is already in use.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

delete_features_from_query(product_id, geometry=None, query_expr=None, **kwargs)[source]

Query an existing Vector product and delete features that match the query results.

One of geometry or query_expr is required.

Parameters

  • product_id (str) – (Required) The ID of the product within which to search for features to delete.

  • geometry (dict) –

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

    • Points

    • MultiPoints

    • Polygons

    • MultiPolygons

    • LineStrings

    • MultiLineStrings

    • GeometryCollections

  • query_expr (Expression) – Expression used to filter features by their properties, built from dl.properties. You can construct filter expression using the ==, !=, <, >, <= and >= operators as well as the like() and in_() methods. You cannot use the boolean keywords and and or because of Python language limitations; instead you can combine filter expressions with & (boolean “and”) and | (boolean “or”). Example (assuming from descarteslabs import properties as p): query_expr=(p.temperature >= 50) & (p.hour_of_day > 18). More complex example: query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)). If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.

Return type

DotDict

Returns

Vector product from which the features were deleted, as a JSON API resource object. For a list of keys, please see get_product().

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

delete_product(product_id)[source]

Remove a vector product from the catalog.

Parameters

product_id (str) – (Required) The ID of the Vector product to remove.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

export_product_from_query(product_id, key, geometry=None, query_expr=None, query_limit=None)[source]

Query vector features within an existing product and export the result to DescartesLabs Storage as type data using the given storage key.

If none of the geometry, query_expr, or query_limit are given, the full product is exported.

Note that the export is happening asynchronously and can take a while depending on the size of the product or query. You can request the status using get_export_result() or get_export_results().

Once the export is complete, you can download the file from Descartes Labs Storage using descarteslabs.client.services.storage.Storage.get_file() with the given key and a local filename.

Parameters

  • product_id (str) – (Required) The ID of the product within which to search or which to copy.

  • key (str) – (Required) The name under which the export will be available in the Storage service. The storage_type will be data. Note that this will overwrite any existing data if the key already exists.

  • geometry (dict) –

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

    • Points

    • MultiPoints

    • Polygons

    • MultiPolygons

    • LineStrings

    • MultiLineStrings

    • GeometryCollections

  • query_expr (Expression) – Expression used to filter features by their properties, built from dl.properties. You can construct filter expression using the ==, !=, <, >, <= and >= operators as well as the like() and and in_() methods. You cannot use the boolean keywords and and or because of Python language limitations; instead you can combine filter expressions with & (boolean “and”) and | (boolean “or”). Example (assuming from descarteslabs import properties as p): query_expr=(p.temperature >= 50) & (p.hour_of_day > 18). More complex example: query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)). If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.

  • query_limit (int) – Maximum number of features to return for this query, defaults to all.

Return type

str

Returns

The export id.

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_delete_features_status(product_id)[source]

Get the status of the job deleting features from a query.

Parameters

product_id (str) – (Required) The ID of the product to get delete status for. the previously initiated deletion using create_product() or create_product_from_query().

Rtype DotDict

Returns

A dictionary with information about the status. For a description of the keys, please see get_product_from_query_status(). Note that the type will be delete_job.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_export_result(product_id, export_id)[source]

Get details about a specific export job. Included information about processing error streams, which can help debug failed uploads. Note that this information is available once the job completed (either successfully or unsuccessfully).

Parameters

  • product_id (str) – (Required) The ID of the product for which to return the result.

  • export_id (str) – (Required) The export ID for which to return the result, as previously returned by export_product_from_query().

Return type

DotDict

Returns

The information about the export task once the task has completed. The keys are:

data: A single "DotDict" instance with the following keys:

    id:         The id of the task.
    type:       export.
    attributes: A DotDict instance with the following keys:

        created:           Time that the task was created in
                           ISO-8601 UTC.
        exception_name:    The type of exception, if there
                           is one, "None" otherwise.
        failure_type:      "executable_failure" if resource
                           limits are reached, or "exception"
                           if an exception was thrown,
                           "None" otherwise.
        peak_memory_usage: The amount of memory used by
                           the task in bytes.
        runtime:           The number of CPU seconds used
                           by the task.
        status:            "SUCCESS" or "FAILURE".
        labels:            A list of string labels.  The
                           last value is the key.

Raises

  • NotFoundError – When the task is either not found or the task is pending or running but has not completed yet.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_export_results(product_id)[source]

Get a list of the exports submitted to a vector product, and status information about each. Note that only completed tasks are shown; any tasks that are pending or running will not be listed.

Parameters

product_id (str) – (Required) The ID of the product to get results for.

Return type

Iterator of DotDict instances

Returns

An iterator returning DotDict instances containing information about each completed export task created by export_product_from_query(). See get_export_result() under data for an explanation of the information returned.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

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

The vector product, as a JSON API resource object. The keys are:

data: A single "DotDict" instance with the following keys:

    id:   The ID of the Vector product.
    type: "product".
    meta: A single DotDict instance with the following keys:

        created: Time that the task was created in
                 ISO-8601 UTC.

    attributes: A single DotDict instance with the
                following keys:

        description: The description given to this
                     product.
        owners:      The owners of this product
                     (at a minimum the organization
                     and the user who created this
                     product).
        readers:     The users, groups, or
                     organizations that can read
                     this product.
        title:       The title given to this product.
        writers:     The users, groups, or
                     organizations that can write
                     into this product.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_product_from_query_status(product_id)[source]

Get the status of the job creating a new product from a query.

Parameters

product_id (str) – (Required) The ID of the product for which to to check the status. This ID must have been created by a call to create_product_from_query().

Return type

DotDict

Returns

A dictionary with information about the status. The keys are

data: A "DotDict" instance with the following keys:

    id:         The internal ID for this job.
    type:       "copy_job".
    attributes: A DotDict instance with the following keys:

        created: Time that the task was created in
                 ISO-8601 UTC.
        ended:   Time that the task completed in
                 ISO-8601 UTC (when available).
        started: Time that the start stared in
                 ISO-8601 UTC (when available).
        state:   "PENDING", "RUNNING", or "DONE".

Raises

  • NotFoundError – Raised if the product or status cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_upload_result(product_id, upload_id, pending=False)[source]

Get details about a specific upload job. Included is information about processing error streams, which can help debug failed uploads.

Note that the upload happens in 2 stages: the initial Upload Task which preprocesses the data, and the final Upload Job which does the actual upload. The information about the final Upload Job can be found in the load key of the upload result.

Parameters

  • product_id (str) – (Required) The ID of the product which to retrieve the upload result.

  • upload_id (str) – (Required) An id pertaining to this requested upload, either returned by get_upload_results() or upload_features().

  • pending (bool) – If True, include pending upload jobs in the result. Defaults to False.

Rtype DotDict

Returns

The result as a JSON API resource object. The keys are:

data: A DotDict instance with the following keys.  Not
      all keys will available depending on the status
      of the upload job.  Specifically, the "load" key will
      be available once the "status" is "SUCCESS" and the
      "result" key will be available once the "status" is
      "SUCCESS" or "FAILURE".  Also be aware that the upload
      job is not complete until the "load.state" is "DONE".

    id:         The ID of the upload task (which is not the
                upload ID, but you can use it instead of
                the upload ID).
    type:       "upload".
    attributes: A DotDict instance with the following keys:

        created:           Time that the task was created
                           in ISO-8601 UTC.
        exception_name:    The type of exception, if there
                           is one, "None" otherwise.
        failure_type:      "executable_failure" if resource
                           limits are reached, or
                           "exception" if an exception was
                           thrown, "None" otherwise.
        peak_memory_usage: The amount of memory used by the
                           task in bytes.
        runtime:           The number of CPU seconds used by
                           the task.
        status:            The status of the initial Upload
                           Task.  "PENDING", "RUNNING",
                           "SUCCESS" or "FAILURE".
        labels:            A list of string labels.  The
                           last value is the upload ID.
        load:              A DotDict instance describing the
                           actual result of the final Upload
                           Job which continues
                           asynchronously after the initial
                           Upload Task has completed.  The
                           upload is complete once
                           "load.state" is "DONE" or
                           "SKIPPED".  This key is only
                           available once "status" is
                           "SUCCESS":

            errors:      How many errors the load caused.
            output_rows: The number of actual rows created
                         during the load (which may differ
                         from the number of rows given in
                         the upload file).
            state:       The status of the final Upload Job.
                         "SKIPPED", "PENDING", "RUNNING", or
                         "DONE".

        result:            A DotDict instance describing the
                           result of the initial Upload Task
                           (which pre-processes the data
                           before it's loaded).  This key is
                           only available once "status" is
                           "SUCCESS" or "FAILURE".

            errors:         A list of errors, potentially
                            empty.
            input_features: The number of valid rows in the
                            upload file.
            input_rows:     The number of rows that will be
                            loaded (unless there are errors,
                            this should be identical to
                            "output_rows" above).
            job_id:         The internal job ID.

Raises

  • NotFoundError – Raised if the product or upload cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

get_upload_results(product_id, pending=False)[source]

Get a list of the uploads submitted to a vector product, and status information about each.

Parameters

  • product_id (str) – (Required) The ID of the Vector product for which to retrieve the upload results

  • pending (bool) – If True, include pending upload jobs in the result. Defaults to False.

Return type

Iterator of DotDict instances

Returns

An iterator over all upload results created with upload_features(), returning DotDict instances with the following keys:

id:         The ID of the upload task (which is not the upload
            ID, but you can use it instead of the upload ID).
type:       "upload".
attributes: A "DotDict" instance with the following keys
            (note that this contains less information then the
            information returned by get_upload_result):

    created:           Time that the task was created in ISO-8601 UTC.
    exception_name:    The type of exception, if there is one,
                       "None" otherwise.
    failure_type:      "executable_failure" if resource limits are
                       reached, or "exception" if an exception was
                       thrown, "None" otherwise.
    peak_memory_usage: The amount of memory used by the task in bytes.
    runtime:           The number of CPU seconds used by the task.
    status:            "RUNNING", "SUCCESS" or "FAILURE".
    labels:            A list of string labels.  The last value is
                       the upload ID.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

list_products(page_size=100, page=1)[source]

Get all vector products that you have access using JSON API pagination. The first page (1) will always succeed but may be empty. Subsequent pages may throw NotFoundError.

Parameters

  • page_size (int) – Maximum number of vector products to return per page; default is 100.

  • page (int) – Which page of results to fetch, if there are more results than page_size.

Return type

DotDict

Returns

Available vector products and their properties, as a JSON API collection. This dictionary contains the following keys:

data:  A list of DotDict instances with the following keys:

    id:   The ID of the Vector product.
    type: "product".
    meta: A single DotDict instance with the following keys:

        created: Time that the task was created in ISO-8601 UTC.

    attributes: A single DotDict instance with the following keys:

        description: The description given to this product.
        owners:      The owners of this product (at a minimum
                     the organization and the user who created
                     this product).
        readers:     The users, groups, or organizations that
                     can read this product.
        title:       The title given to this product.
        writers:     The users, groups, or organizations that
                     can write into this product.

links: (Optional) A single DotDict instance with the
       following keys if there is more than one page of products:

    next: (Optional) A link to the next page of products
          if available.
    prev: (Optional) A link to the previous page of products
          if available.

Raises

  • NotFoundError – Raised if subsequent pages cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

replace_product(product_id=None, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]

Replace a vector product in your catalog.

Parameters

  • product_id (str) – (Required) The ID of the Vector product to update.

  • title (str) – (Required) Official product title.

  • description (str) – (Required) Information about the product, why it exists, and what it provides.

  • owners (list(str)) – 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].

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

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

  • name (str) – (Deprecated) Will be removed completely in future versions.

Return type

DotDict

Returns

Replaced vector product, as a JSON API resource object. For a description of the keys, please see get_product().

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

search_features(product_id, geometry=None, query_expr=None, query_limit=None, **kwargs)[source]

Iterate over vector features within an existing product.

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

The returned iterator has a length that indicates the size of the query.

Parameters

  • product_id (str) – (Required) The ID of the product within which to search.

  • geometry (dict) –

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

    • Points

    • MultiPoints

    • Polygons

    • MultiPolygons

    • LineStrings

    • MultiLineStrings

    • GeometryCollections

  • query_expr (Expression) – Expression used to filter features by their properties, built from dl.properties. You can construct filter expression using the ==, !=, <, >, <= and >= operators as well as the like() and in_() methods. You cannot use the boolean keywords and and or because of Python language limitations; instead you can combine filter expressions with & (boolean “and”) and | (boolean “or”). Example (assuming from descarteslabs import properties as p): query_expr=(p.temperature >= 50) & (p.hour_of_day > 18). More complex example: query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)). If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.

  • query_limit (int) – Maximum number of features to return for this query, defaults to all.

Return type

Iterator of DotDict instances

Returns

Features satisfying the query, as JSONAPI primary data objects. For a description of the keys, please refer to create_feature() under the data key.

len() can be used on the returned iterator to determine the query size.

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

update_product(product_id, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]

Update a vector product in your catalog using the given parameters. If a parameter is not provided, it will not change. You cannot change the product_id.

Parameters

  • product_id (str) – (Required) The ID of the Vector product to update.

  • name (str) – (Deprecated) Will be removed completely in future versions.

  • title (str) – Official product title.

  • description (str) – Information about the product, why it exists, and what it provides.

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

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

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

Return type

DotDict

Returns

Updated vector product, as a JSON API resource object. For a description of the keys please see get_product().

Raises

  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

upload_features(file_ish, product_id, max_errors=0, fix_geometry='accept')[source]

Asynchonously upload a file or stream of Newline Delimited JSON features. Note that the file may not contain empty lines or lines containing anything but the feature (including e.g. a trailing comma), or such lines will cause errors.

It is recommended that the IOBase object is a byte-oriented (not text-oriented) object, although Python 3 allows io.StringIO to be used.

This is an asynchronous operation and you can query for the status using get_upload_result() with the upload_id returned by this method.

Parameters

  • file_ish (str or io.IOBase) – an open io.IOBase object, or a path to the file to upload.

  • product_id (str) – (Required) The ID of the Vector product to which these features will belong.

  • max_errors (int) – The maximum number of errors permitted before declaring failure.

  • fix_geometry (str) – String specifying how to handle certain problem geometries, including those which do not follow counter-clockwise winding order (which is required by the GeoJSON spec but not many popular tools). Allowed values are reject (reject invalid geometries with an error), fix (correct invalid geometries if possible and use this corrected value when creating the feature), and accept (the default) which will correct the geometry for internal use but retain the original geometry in the results.

Return type

str

Returns

The upload id.

Raises

  • NotFoundError – Raised if the product cannot be found.

  • RateLimitError – Raised when too many requests have been made within a given time period.

  • ServerError – Raised when a unknown error occurred on the server.

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