Geospatial

Note

Check https://github.com/cognitedata/geospatial-examples for some complete examples.

Feature types

Create feature types

GeospatialAPI.create_feature_types(feature_type: FeatureType | FeatureTypeWrite) → FeatureType
GeospatialAPI.create_feature_types(feature_type: Sequence[FeatureType] | Sequence[FeatureTypeWrite]) → FeatureTypeList

Creates feature types <https://developer.cognite.com/api#tag/Geospatial/operation/createFeatureTypes>

Parameters

feature_type (FeatureType | FeatureTypeWrite | Sequence[FeatureType] | Sequence[FeatureTypeWrite]) – feature type definition or list of feature type definitions to create.

Returns

Created feature type definition(s)

Return type

FeatureType | FeatureTypeList

Examples

Create new type definitions:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.geospatial import FeatureTypeWrite
>>> client = CogniteClient()
>>> feature_types = [
...     FeatureTypeWrite(external_id="wells", properties={"location": {"type": "POINT", "srid": 4326}})
...     FeatureTypeWrite(
...       external_id="cities",
...       properties={"name": {"type": "STRING", "size": 10}},
...       search_spec={"name_index": {"properties": ["name"]}}
...     )
... ]
>>> res = client.geospatial.create_feature_types(feature_types)

Delete feature types

GeospatialAPI.delete_feature_types(external_id: str | SequenceNotStr[str], recursive: bool = False) → None

Delete one or more feature type <https://developer.cognite.com/api#tag/Geospatial/operation/GeospatialDeleteFeatureTypes>

Parameters

  • external_id (str | SequenceNotStr[str]) – External ID or list of external ids

  • recursive (bool) – if true the features will also be dropped

Examples

Delete feature type definitions external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.geospatial.delete_feature_types(external_id=["wells", "cities"])

List feature types

GeospatialAPI.list_feature_types() → FeatureTypeList

List feature types <https://developer.cognite.com/api#tag/Geospatial/operation/listFeatureTypes>

Returns

List of feature types

Return type

FeatureTypeList

Examples

Iterate over feature type definitions:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for feature_type in client.geospatial.list_feature_types():
...     feature_type # do something with the feature type definition

Retrieve feature types

GeospatialAPI.retrieve_feature_types(external_id: str) → FeatureType
GeospatialAPI.retrieve_feature_types(external_id: list[str]) → FeatureTypeList

Retrieve feature types <https://developer.cognite.com/api#tag/Geospatial/operation/getFeatureTypesByIds>

Parameters

external_id (str | list[str]) – External ID

Returns

Requested Type or None if it does not exist.

Return type

FeatureType | FeatureTypeList

Examples

Get Type by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.geospatial.retrieve_feature_types(external_id="1")

Update feature types

GeospatialAPI.patch_feature_types(patch: FeatureTypePatch | Sequence[FeatureTypePatch]) → FeatureTypeList

Patch feature types <https://developer.cognite.com/api#tag/Geospatial/operation/updateFeatureTypes>

Parameters

patch (FeatureTypePatch | Sequence[FeatureTypePatch]) – the patch to apply

Returns

The patched feature types.

Return type

FeatureTypeList

Examples

Add one property to a feature type and add indexes

>>> from cognite.client.data_classes.geospatial import Patches
>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.geospatial.patch_feature_types(
...    patch=FeatureTypePatch(
...       external_id="wells",
...       property_patches=Patches(add={"altitude": {"type": "DOUBLE"}}),
...       search_spec_patches=Patches(
...         add={
...           "altitude_idx": {"properties": ["altitude"]},
...           "composite_idx": {"properties": ["location", "altitude"]}
...         }
...       )
...    )
... )

Add an additional index to an existing property

>>> from cognite.client.data_classes.geospatial import Patches
>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.geospatial.patch_feature_types(
...    patch=FeatureTypePatch(
...         external_id="wells",
...         search_spec_patches=Patches(add={"location_idx": {"properties": ["location"]}})
... ))

Features

Create features

GeospatialAPI.create_features(feature_type_external_id: str, feature: Feature | FeatureWrite, allow_crs_transformation: bool = False, chunk_size: int | None = None) → Feature
GeospatialAPI.create_features(feature_type_external_id: str, feature: Sequence[Feature] | Sequence[FeatureWrite] | FeatureList | FeatureWriteList, allow_crs_transformation: bool = False, chunk_size: int | None = None) → FeatureList

Creates features <https://developer.cognite.com/api#tag/Geospatial/operation/createFeatures>

Parameters

  • feature_type_external_id (str) – Feature type definition for the features to create.

  • feature (Feature | FeatureWrite | Sequence[Feature] | Sequence[FeatureWrite] | FeatureList | FeatureWriteList) – one feature or a list of features to create or a FeatureList object

  • allow_crs_transformation (bool) – If true, then input geometries will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.

  • chunk_size (int | None) – maximum number of items in a single request to the api

Returns

Created features

Return type

Feature | FeatureList

Examples

Create a new feature type and corresponding feature:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.geospatial import FeatureTypeWrite, FeatureWrite
>>> client = CogniteClient()
>>> feature_types = [
...     FeatureTypeWrite(
...         external_id="my_feature_type",
...         properties={
...             "location": {"type": "POINT", "srid": 4326},
...             "temperature": {"type": "DOUBLE"}
...         }
...     )
... ]
>>> res = client.geospatial.create_feature_types(feature_types)
>>> res = client.geospatial.create_features(
...     feature_type_external_id="my_feature_type",
...     feature=FeatureWrite(
...         external_id="my_feature",
...         location={"wkt": "POINT(1 1)"},
...         temperature=12.4
...     )
... )

Delete features

GeospatialAPI.delete_features(feature_type_external_id: str, external_id: str | SequenceNotStr[str] | None = None) → None

Delete one or more feature <https://developer.cognite.com/api#tag/Geospatial/operation/deleteFeatures>

Parameters

  • feature_type_external_id (str) – No description.

  • external_id (str | SequenceNotStr[str] | None) – External ID or list of external ids

Examples

Delete feature type definitions external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.geospatial.delete_features(
...     feature_type_external_id="my_feature_type",
...     external_id=my_feature
... )

Retrieve features

GeospatialAPI.retrieve_features(feature_type_external_id: str, external_id: str, properties: dict[str, Any] | None = None) → Feature
GeospatialAPI.retrieve_features(feature_type_external_id: str, external_id: list[str], properties: dict[str, Any] | None = None) → FeatureList

Retrieve features <https://developer.cognite.com/api#tag/Geospatial/operation/getFeaturesByIds>

Parameters

  • feature_type_external_id (str) – No description.

  • external_id (str | list[str]) – External ID or list of external ids

  • properties (dict[str, Any] | None) – the output property selection

Returns

Requested features or None if it does not exist.

Return type

FeatureList | Feature

Examples

Retrieve one feature by its external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.geospatial.retrieve_features(
...     feature_type_external_id="my_feature_type",
...     external_id="my_feature"
... )

Update features

GeospatialAPI.update_features(feature_type_external_id: str, feature: Feature | Sequence[Feature], allow_crs_transformation: bool = False, chunk_size: int | None = None) → FeatureList

Update features <https://developer.cognite.com/api#tag/Geospatial/operation/updateFeatures>

Parameters

  • feature_type_external_id (str) – No description.

  • feature (Feature | Sequence[Feature]) – feature or list of features.

  • allow_crs_transformation (bool) – If true, then input geometries will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.

  • chunk_size (int | None) – maximum number of items in a single request to the api

Returns

Updated features

Return type

FeatureList

Examples

Update one feature:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id="my_feature_type",
...     feature=Feature(external_id="my_feature", temperature=12.4)
... )
>>> my_updated_feature = client.geospatial.update_features(
...     feature_type_external_id="my_feature_type",
...     feature=Feature(external_id="my_feature", temperature=6.237)
... )

List features

GeospatialAPI.list_features(feature_type_external_id: str, filter: dict[str, Any] | None = None, properties: dict[str, Any] | None = None, limit: int | None = 25, allow_crs_transformation: bool = False) → FeatureList

List features <https://developer.cognite.com/api#tag/Geospatial/operation/listFeatures>

This method allows to filter all features.

Parameters

  • feature_type_external_id (str) – the feature type to list features for

  • filter (dict[str, Any] | None) – the list filter

  • properties (dict[str, Any] | None) – the output property selection

  • limit (int | None) – Maximum number of features to return. Defaults to 25. Set to -1, float(“inf”) or None to return all features.

  • allow_crs_transformation (bool) – If true, then input geometries if existing in the filter will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.

Returns

The filtered features

Return type

FeatureList

Examples

List features:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature_type = client.geospatial.retrieve_feature_types(
...     external_id="my_feature_type"
... )
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id=my_feature_type,
...     feature=Feature(
...         external_id="my_feature",
...         temperature=12.4,
...         location={"wkt": "POINT(0 1)"}
...     )
... )
>>> res = client.geospatial.list_features(
...     feature_type_external_id="my_feature_type",
...     filter={"range": {"property": "temperature", "gt": 12.0}}
... )
>>> for f in res:
...     # do something with the features

Search for features and select output properties:

>>> res = client.geospatial.list_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     properties={"temperature": {}, "pressure": {}}
... )

Search for features with spatial filters:

>>> res = client.geospatial.list_features(
...     feature_type_external_id=my_feature_type,
...     filter={"stWithin": {
...         "property": "location",
...         "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"}
...     }}
... )

Search features

GeospatialAPI.search_features(feature_type_external_id: str, filter: dict[str, Any] | None = None, properties: dict[str, Any] | None = None, limit: int = 25, order_by: Sequence[OrderSpec] | None = None, allow_crs_transformation: bool = False, allow_dimensionality_mismatch: bool = False) → FeatureList

Search for features <https://developer.cognite.com/api#tag/Geospatial/operation/searchFeatures>

This method allows to order the result by one or more of the properties of the feature type. However, the number of items returned is limited to 1000 and there is no support for cursors yet. If you need to return more than 1000 items, use the stream_features(…) method instead.

Parameters

  • feature_type_external_id (str) – The feature type to search for

  • filter (dict[str, Any] | None) – The search filter

  • properties (dict[str, Any] | None) – The output property selection

  • limit (int) – Maximum number of results

  • order_by (Sequence[OrderSpec] | None) – The order specification

  • allow_crs_transformation (bool) – If true, then input geometries will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.

  • allow_dimensionality_mismatch (bool) – Indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. Defaults to False.

Returns

the filtered features

Return type

FeatureList

Examples

Search for features:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature_type = client.geospatial.retrieve_feature_types(
...     external_id="my_feature_type"
... )
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id=my_feature_type,
...     feature=Feature(
...         external_id="my_feature",
...         temperature=12.4,
...         location={"wkt": "POINT(0 1)"}
...     )
... )
>>> res = client.geospatial.search_features(
...     feature_type_external_id="my_feature_type",
...     filter={"range": {"property": "temperature", "gt": 12.0}}
... )
>>> for f in res:
...     # do something with the features

Search for features and select output properties:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     properties={"temperature": {}, "pressure": {}}
... )

Search for features and do CRS conversion on an output property:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     properties={"location": {"srid": 3995}}
... )

Search for features and order results:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={},
...     order_by=[
...         OrderSpec("temperature", "ASC"),
...         OrderSpec("pressure", "DESC")]
... )

Search for features with spatial filters:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={"stWithin": {
...         "property": "location",
...         "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"}
...     }}
... )

Combining multiple filters:

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={"and": [
...         {"range": {"property": "temperature", "gt": 12.0}},
...         {"stWithin": {
...             "property": "location",
...             "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"}
...         }}
...     ]}
... )

>>> res = client.geospatial.search_features(
...     feature_type_external_id=my_feature_type,
...     filter={"or": [
...         {"range": {"property": "temperature", "gt": 12.0}},
...         {"stWithin": {
...             "property": "location",
...             "value": {"wkt": "POLYGON((0 0, 0 1, 1 1, 0 0))"}
...         }}
...     ]}
... )

Stream features

GeospatialAPI.stream_features(feature_type_external_id: str, filter: dict[str, Any] | None = None, properties: dict[str, Any] | None = None, allow_crs_transformation: bool = False, allow_dimensionality_mismatch: bool = False) → Iterator[Feature]

Stream features <https://developer.cognite.com/api#tag/Geospatial/operation/searchFeaturesStreaming>

This method allows to return any number of items until the underlying api calls times out. The order of the result items is not deterministic. If you need to order the results, use the search_features(…) method instead.

Parameters

  • feature_type_external_id (str) – the feature type to search for

  • filter (dict[str, Any] | None) – the search filter

  • properties (dict[str, Any] | None) – the output property selection

  • allow_crs_transformation (bool) – If true, then input geometries will be transformed into the Coordinate Reference System defined in the feature type specification. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in CogniteAPIError exception.

  • allow_dimensionality_mismatch (bool) – Indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. Defaults to False.

Yields

Feature – a generator for the filtered features

Examples

Stream features:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id="my_feature_type",
...     feature=Feature(external_id="my_feature", temperature=12.4)
... )
>>> features = client.geospatial.stream_features(
...     feature_type_external_id="my_feature_type",
...     filter={"range": {"property": "temperature", "gt": 12.0}}
... )
>>> for f in features:
...     # do something with the features

Stream features and select output properties:

>>> features = client.geospatial.stream_features(
...     feature_type_external_id="my_feature_type",
...     filter={},
...     properties={"temperature": {}, "pressure": {}}
... )
>>> for f in features:
...     # do something with the features

Aggregate features

GeospatialAPI.aggregate_features(feature_type_external_id: str, filter: dict[str, Any] | None = None, group_by: SequenceNotStr[str] | None = None, order_by: Sequence[OrderSpec] | None = None, output: dict[str, Any] | None = None) → FeatureAggregateList

Aggregate filtered features <https://developer.cognite.com/api#tag/Geospatial/operation/aggregateFeatures>

Parameters

  • feature_type_external_id (str) – the feature type to filter features from

  • filter (dict[str, Any] | None) – the search filter

  • group_by (SequenceNotStr[str] | None) – list of properties to group by with

  • order_by (Sequence[OrderSpec] | None) – the order specification

  • output (dict[str, Any] | None) – the aggregate output

Returns

the filtered features

Return type

FeatureAggregateList

Examples

Aggregate property of features:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature = client.geospatial.create_features(
...     feature_type_external_id="my_feature_type",
...     feature=Feature(external_id="my_feature", temperature=12.4)
... )
>>> res = client.geospatial.aggregate_features(
...     feature_type_external_id="my_feature_type",
...     filter={"range": {"property": "temperature", "gt": 12.0}},
...     group_by=["category"],
...     order_by=[OrderSpec("category", "ASC")],
...     output={"min_temperature": {"min": {"property": "temperature"}},
...         "max_volume": {"max": {"property": "volume"}}
...     }
... )
>>> for a in res:
...     # loop over aggregates in different groups

Reference systems

Get coordinate reference systems

GeospatialAPI.get_coordinate_reference_systems(srids: int | Sequence[int]) → CoordinateReferenceSystemList

Get Coordinate Reference Systems <https://developer.cognite.com/api#tag/Geospatial/operation/getCoordinateReferenceSystem>

Parameters

srids (int | Sequence[int]) – (Union[int, Sequence[int]]): SRID or list of SRIDs

Returns

Requested CRSs.

Return type

CoordinateReferenceSystemList

Examples

Get two CRS definitions:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> crs = client.geospatial.get_coordinate_reference_systems(srids=[4326, 4327])

List coordinate reference systems

GeospatialAPI.list_coordinate_reference_systems(only_custom: bool = False) → CoordinateReferenceSystemList

List Coordinate Reference Systems <https://developer.cognite.com/api#tag/Geospatial/operation/listGeospatialCoordinateReferenceSystems>

Parameters

only_custom (bool) – list only custom CRSs or not

Returns

list of CRSs.

Return type

CoordinateReferenceSystemList

Examples

Fetch all custom CRSs:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> crs = client.geospatial.list_coordinate_reference_systems(only_custom=True)

Create coordinate reference systems

GeospatialAPI.create_coordinate_reference_systems(crs: CoordinateReferenceSystem | CoordinateReferenceSystemWrite | Sequence[CoordinateReferenceSystem] | Sequence[CoordinateReferenceSystemWrite]) → CoordinateReferenceSystemList

Create Coordinate Reference System <https://developer.cognite.com/api#tag/Geospatial/operation/createGeospatialCoordinateReferenceSystems>

Parameters

crs (CoordinateReferenceSystem | CoordinateReferenceSystemWrite | Sequence[CoordinateReferenceSystem] | Sequence[CoordinateReferenceSystemWrite]) – a CoordinateReferenceSystem or a list of CoordinateReferenceSystem

Returns

list of CRSs.

Return type

CoordinateReferenceSystemList

Examples

Create a custom CRS:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import CoordinateReferenceSystemWrite
>>> client = CogniteClient()
>>> custom_crs = CoordinateReferenceSystemWrite(
...     srid = 121111,
...     wkt=(
...          'PROJCS["NTF (Paris) / Lambert zone II",'
...          ' GEOGCS["NTF (Paris)",'
...          '  DATUM["Nouvelle_Triangulation_Francaise_Paris",'
...          '   SPHEROID["Clarke 1880 (IGN)",6378249.2,293.4660212936265,'
...          '    AUTHORITY["EPSG","7011"]],'
...          '   TOWGS84[-168,-60,320,0,0,0,0],'
...          '   AUTHORITY["EPSG","6807"]],'
...          '  PRIMEM["Paris",2.33722917,'
...          '   AUTHORITY["EPSG","8903"]],'
...          '  UNIT["grad",0.01570796326794897,'
...          '   AUTHORITY["EPSG","9105"]], '
...          '  AUTHORITY["EPSG","4807"]],'
...          ' PROJECTION["Lambert_Conformal_Conic_1SP"],'
...          ' PARAMETER["latitude_of_origin",52],'
...          ' PARAMETER["central_meridian",0],'
...          ' PARAMETER["scale_factor",0.99987742],'
...          ' PARAMETER["false_easting",600000],'
...          ' PARAMETER["false_northing",2200000],'
...          ' UNIT["metre",1,'
...          '  AUTHORITY["EPSG","9001"]],'
...          ' AXIS["X",EAST],'
...          ' AXIS["Y",NORTH],'
...          ' AUTHORITY["EPSG","27572"]]'
...     ),
...     proj_string=(
...          '+proj=lcc +lat_1=46.8 +lat_0=46.8 +lon_0=0 +k_0=0.99987742 '
...          '+x_0=600000 +y_0=2200000 +a=6378249.2 +b=6356515 '
...          '+towgs84=-168,-60,320,0,0,0,0 +pm=paris +units=m +no_defs'
...     )
... )
>>> crs = client.geospatial.create_coordinate_reference_systems(custom_crs)

Raster data

Put raster data

GeospatialAPI.put_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str, raster_format: str, raster_srid: int, file: str, allow_crs_transformation: bool = False, raster_scale_x: float | None = None, raster_scale_y: float | None = None) → RasterMetadata

Put raster <https://developer.cognite.com/api#tag/Geospatial/operation/putRaster>

Parameters

  • feature_type_external_id (str) – No description.

  • feature_external_id (str) – one feature or a list of features to create

  • raster_property_name (str) – the raster property name

  • raster_format (str) – the raster input format

  • raster_srid (int) – the associated SRID for the raster

  • file (str) – the path to the file of the raster

  • allow_crs_transformation (bool) – When the parameter is false, requests with rasters in Coordinate Reference System different from the one defined in the feature type will result in bad request response code.

  • raster_scale_x (float | None) – the X component of the pixel width in units of coordinate reference system

  • raster_scale_y (float | None) – the Y component of the pixel height in units of coordinate reference system

Returns

the raster metadata if it was ingested successfully

Return type

RasterMetadata

Examples

Put a raster in a feature raster property:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> metadata = client.geospatial.put_raster(feature_type.external_id, feature.external_id,
...         raster_property_name, "XYZ", 3857, file)

Delete raster data

GeospatialAPI.delete_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str) → None

Delete raster <https://developer.cognite.com/api#tag/Geospatial/operation/deleteRaster>

Parameters

  • feature_type_external_id (str) – No description.

  • feature_external_id (str) – one feature or a list of features to create

  • raster_property_name (str) – the raster property name

Examples

Delete a raster in a feature raster property:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> client.geospatial.delete_raster(feature_type.external_id, feature.external_id, raster_property_name)

Get raster data

GeospatialAPI.get_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str, raster_format: str, raster_options: dict[str, Any] | None = None, raster_srid: int | None = None, raster_scale_x: float | None = None, raster_scale_y: float | None = None, allow_crs_transformation: bool = False) → bytes

Get raster <https://developer.cognite.com/api#tag/Geospatial/operation/getRaster>

Parameters

  • feature_type_external_id (str) – Feature type definition for the features to create.

  • feature_external_id (str) – one feature or a list of features to create

  • raster_property_name (str) – the raster property name

  • raster_format (str) – the raster output format

  • raster_options (dict[str, Any] | None) – GDAL raster creation key-value options

  • raster_srid (int | None) – the SRID for the output raster

  • raster_scale_x (float | None) – the X component of the output pixel width in units of coordinate reference system

  • raster_scale_y (float | None) – the Y component of the output pixel height in units of coordinate reference system

  • allow_crs_transformation (bool) – When the parameter is false, requests with output rasters in Coordinate Reference System different from the one defined in the feature type will result in bad request response code.

Returns

the raster data

Return type

bytes

Examples

Get a raster from a feature raster property:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> raster_data = client.geospatial.get_raster(feature_type.external_id, feature.external_id,
...    raster_property_name, "XYZ", {"SIGNIFICANT_DIGITS": "4"})

Compute

GeospatialAPI.compute(output: dict[str, GeospatialComputeFunction]) → GeospatialComputedResponse

Compute <https://developer.cognite.com/api#tag/Geospatial/operation/compute>

Parameters

output (dict[str, GeospatialComputeFunction]) – No description.

Returns

Mapping of keys to computed items.

Return type

GeospatialComputedResponse

Examples

Compute the transformation of an ewkt geometry from one SRID to another:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.geospatial import GeospatialGeometryTransformComputeFunction, GeospatialGeometryValueComputeFunction
>>> client = CogniteClient()
>>> compute_function = GeospatialGeometryTransformComputeFunction(GeospatialGeometryValueComputeFunction("SRID=4326;POLYGON((0 0,10 0,10 10,0 10,0 0))"), srid=23031)
>>> compute_result = client.geospatial.compute(output = {"output": compute_function})

Geospatial Data classes

class cognite.client.data_classes.geospatial.CoordinateReferenceSystem(srid: int | None = None, wkt: str | None = None, proj_string: str | None = None, cognite_client: CogniteClient | None = None)

Bases: CoordinateReferenceSystemCore

A representation of a feature in the geospatial API. This is the reading version of the CoordinateReferenceSystem class, it is used when retrieving from the CDF.

Parameters
as_write() → CoordinateReferenceSystemWrite

Returns a write version of this coordinate reference system.

class cognite.client.data_classes.geospatial.CoordinateReferenceSystemCore(srid: int | None = None, wkt: str | None = None, proj_string: str | None = None)

Bases: WriteableCogniteResource[CoordinateReferenceSystemWrite], ABC

A representation of a feature in the geospatial API.

Parameters
class cognite.client.data_classes.geospatial.CoordinateReferenceSystemList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[CoordinateReferenceSystemWrite, CoordinateReferenceSystem]

class cognite.client.data_classes.geospatial.CoordinateReferenceSystemWrite(srid: int, wkt: str, proj_string: str)

Bases: CoordinateReferenceSystemCore

A representation of a feature in the geospatial API.

Parameters
as_write() → CoordinateReferenceSystemWrite

Returns this CoordinateReferenceSystemWrite instance.

class cognite.client.data_classes.geospatial.CoordinateReferenceSystemWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[CoordinateReferenceSystemWrite]

class cognite.client.data_classes.geospatial.Feature(external_id: str | None = None, cognite_client: CogniteClient | None = None, **properties: Any)

Bases: FeatureCore

A representation of a feature in the geospatial API. This is the reading version of the Feature class, it is used when retrieving features from the api.

Parameters

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

  • **properties (Any) – The properties of the feature.

as_write() → FeatureWrite

Returns a write version of this feature.

class cognite.client.data_classes.geospatial.FeatureAggregate(cognite_client: CogniteClient | None = None)

Bases: CogniteResource

A result of aggregating features in geospatial API.

class cognite.client.data_classes.geospatial.FeatureAggregateList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[FeatureAggregate]

class cognite.client.data_classes.geospatial.FeatureCore(external_id: str | None = None, **properties: Any)

Bases: WriteableCogniteResource[FeatureWrite], ABC

A representation of a feature in the geospatial API.

Parameters

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • **properties (Any) – The properties of the feature.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.geospatial.FeatureList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: FeatureListCore[Feature]

class cognite.client.data_classes.geospatial.FeatureListCore(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[FeatureWrite, T_Feature], ExternalIDTransformerMixin

static from_geopandas(feature_type: FeatureType, geodataframe: geopandas.GeoDataFrame, external_id_column: str = 'externalId', property_column_mapping: dict[str, str] | None = None, data_set_id_column: str = 'dataSetId') → FeatureList

Convert a GeoDataFrame instance into a FeatureList.

Parameters

  • feature_type (FeatureType) – The feature type the features will conform to

  • geodataframe (geopandas.GeoDataFrame) – the geodataframe instance to convert into features

  • external_id_column (str) – the geodataframe column to use for the feature external id

  • property_column_mapping (dict[str, str] | None) – provides a mapping from featuretype property names to geodataframe columns

  • data_set_id_column (str) – the geodataframe column to use for the feature dataSet id

Returns

The list of features converted from the geodataframe rows.

Return type

FeatureList

Examples

Create features from a geopandas dataframe:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_feature_type = ... # some feature type with 'position' and 'temperature' properties
>>> my_geodataframe = ...  # some geodataframe with 'center_xy', 'temp' and 'id' columns
>>> feature_list = FeatureList.from_geopandas(feature_type=my_feature_type, geodataframe=my_geodataframe,
>>>     external_id_column="id", data_set_id_column="dataSetId",
>>>     property_column_mapping={'position': 'center_xy', 'temperature': 'temp'})
>>> created_features = client.geospatial.create_features(my_feature_type.external_id, feature_list)
to_geopandas(geometry: str, camel_case: bool = False) → geopandas.GeoDataFrame

Convert the instance into a GeoPandas GeoDataFrame.

Parameters

  • geometry (str) – The name of the feature type geometry property to use in the GeoDataFrame

  • camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)

Returns

The GeoPandas GeoDataFrame.

Return type

geopandas.GeoDataFrame

Examples

Convert a FeatureList into a GeoPandas GeoDataFrame:

>>> from cognite.client.data_classes.geospatial import PropertyAndSearchSpec
>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> features = client.geospatial.search_features(...)
>>> gdf = features.to_geopandas(
...     geometry="position",
...     camel_case=False
... )
>>> gdf.head()
class cognite.client.data_classes.geospatial.FeatureType(external_id: str | None = None, data_set_id: int | None = None, created_time: int | None = None, last_updated_time: int | None = None, properties: dict[str, Any] | None = None, search_spec: dict[str, Any] | None = None, cognite_client: CogniteClient | None = None)

Bases: FeatureTypeCore

A representation of a feature type in the geospatial API. This is the reading version of the FeatureType class, it is used when retrieving feature types from the api.

Parameters

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • data_set_id (int | None) – The ID of the dataset this feature type belongs to.

  • created_time (int | None) – The created time of the feature type.

  • last_updated_time (int | None) – The last updated time of the feature type.

  • properties (dict[str, Any] | None) – The properties of the feature type.

  • search_spec (dict[str, Any] | None) – The search spec of the feature type.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() → FeatureTypeWrite

Returns a write version of this feature type.

class cognite.client.data_classes.geospatial.FeatureTypeCore(external_id: str | None = None, data_set_id: int | None = None, properties: dict[str, Any] | None = None, search_spec: dict[str, Any] | None = None)

Bases: WriteableCogniteResource[FeatureTypeWrite], ABC

A representation of a feature type in the geospatial API.

Parameters

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • data_set_id (int | None) – The ID of the dataset this feature type belongs to.

  • properties (dict[str, Any] | None) – The properties of the feature type.

  • search_spec (dict[str, Any] | None) – The search spec of the feature type.

class cognite.client.data_classes.geospatial.FeatureTypeList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[FeatureTypeWrite, FeatureType]

class cognite.client.data_classes.geospatial.FeatureTypePatch(external_id: 'str | None' = None, property_patches: 'Patches | None' = None, search_spec_patches: 'Patches | None' = None)

Bases: CogniteObject

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.geospatial.FeatureTypeWrite(external_id: str, properties: dict[str, Any], data_set_id: int | None = None, search_spec: dict[str, Any] | None = None)

Bases: FeatureTypeCore

A representation of a feature type in the geospatial API. This is the writing version of the FeatureType class, it is used when creating feature types in the api.

Parameters

  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

  • properties (dict[str, Any]) – The properties of the feature type.

  • data_set_id (int | None) – The ID of the dataset this feature type belongs to.

  • search_spec (dict[str, Any] | None) – The search spec of the feature type.

as_write() → FeatureTypeWrite

Returns this FeatureTypeWrite instance.

class cognite.client.data_classes.geospatial.FeatureTypeWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[FeatureTypeWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.geospatial.FeatureWrite(external_id: str, **properties: Any)

Bases: FeatureCore

A representation of a feature in the geospatial API. This is the writing version of the Feature class, it is used when creating features in the api.

Parameters

  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

  • **properties (Any) – The properties of the feature.

as_write() → FeatureWrite

Returns this FeatureWrite instance.

class cognite.client.data_classes.geospatial.FeatureWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: FeatureListCore[FeatureWrite]

class cognite.client.data_classes.geospatial.GeospatialComputeFunction

Bases: ABC

A geospatial compute function

abstract to_json_payload() → dict

Convert function to json for request payload

class cognite.client.data_classes.geospatial.GeospatialComputedItem(resource: dict[str, Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResource

A representation of an item computed from geospatial.

class cognite.client.data_classes.geospatial.GeospatialComputedItemList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[GeospatialComputedItem]

A list of items computed from geospatial.

class cognite.client.data_classes.geospatial.GeospatialComputedResponse(computed_item_list: GeospatialComputedItemList, cognite_client: CogniteClient | None = None)

Bases: CogniteResource

The geospatial compute response.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.geospatial.GeospatialGeometryComputeFunction

Bases: GeospatialComputeFunction, ABC

A geospatial geometry compute function

class cognite.client.data_classes.geospatial.GeospatialGeometryTransformComputeFunction(geospatial_geometry_compute_function: GeospatialComputeFunction, srid: int)

Bases: GeospatialComputeFunction

A stTransform geospatial compute function

to_json_payload() → dict

Convert function to json for request payload

class cognite.client.data_classes.geospatial.GeospatialGeometryValueComputeFunction(ewkt: str)

Bases: GeospatialGeometryComputeFunction

A geospatial geometry value compute function. Accepts a well-known text of the geometry prefixed with a spatial reference identifier, see https://docs.geotools.org/stable/javadocs/org/opengis/referencing/doc-files/WKT.html :param ewkt: No description. :type ewkt: str

to_json_payload() → dict

Convert function to json for request payload

class cognite.client.data_classes.geospatial.OrderSpec(property: str, direction: str)

Bases: object

An order specification with respect to an property.

class cognite.client.data_classes.geospatial.Patches(add: 'dict[str, Any] | None' = None, remove: 'list[str] | None' = None)

Bases: CogniteObject

class cognite.client.data_classes.geospatial.PropertyAndSearchSpec(properties: dict[str, Any] | list[str] | None = None, search_spec: dict[str, Any] | list[str] | None = None)

Bases: CogniteObject

A representation of a feature type property and search spec.

class cognite.client.data_classes.geospatial.RasterMetadata(**properties: Any)

Bases: object

Raster metadata

cognite.client.data_classes.geospatial.nan_to_none(column_value: Any) → Any

Convert NaN value to None.