Geospatial
Note
Check https://github.com/cognitedata/geospatial-examples for some complete examples.
Feature types
Create feature types
- GeospatialAPI.create_feature_types(feature_type: cognite.client.data_classes.geospatial.FeatureType | cognite.client.data_classes.geospatial.FeatureTypeWrite) FeatureType
- GeospatialAPI.create_feature_types(feature_type: collections.abc.Sequence[cognite.client.data_classes.geospatial.FeatureType] | collections.abc.Sequence[cognite.client.data_classes.geospatial.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
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: Union[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
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
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: cognite.client.data_classes.geospatial.FeatureTypePatch | collections.abc.Sequence[cognite.client.data_classes.geospatial.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
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: cognite.client.data_classes.geospatial.Feature | cognite.client.data_classes.geospatial.FeatureWrite, allow_crs_transformation: bool = False, chunk_size: int | None = None) Feature
- GeospatialAPI.create_features(feature_type_external_id: str, feature: collections.abc.Sequence[cognite.client.data_classes.geospatial.Feature] | collections.abc.Sequence[cognite.client.data_classes.geospatial.FeatureWrite] | cognite.client.data_classes.geospatial.FeatureList | cognite.client.data_classes.geospatial.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
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: Optional[Union[str, SequenceNotStr[str]]] = 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
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: cognite.client.data_classes.geospatial.Feature | collections.abc.Sequence[cognite.client.data_classes.geospatial.Feature], allow_crs_transformation: bool = False, chunk_size: Optional[int] = 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
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: Optional[dict[str, Any]] = None, properties: Optional[dict[str, Any]] = 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
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: Optional[dict[str, Any]] = None, properties: Optional[dict[str, Any]] = None, limit: int = 25, order_by: Optional[Sequence[OrderSpec]] = 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
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: Optional[dict[str, Any]] = None, properties: Optional[dict[str, Any]] = 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: Optional[dict[str, Any]] = None, group_by: Optional[SequenceNotStr[str]] = None, order_by: Optional[Sequence[OrderSpec]] = None, output: Optional[dict[str, Any]] = 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
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 | collections.abc.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
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
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: cognite.client.data_classes.geospatial.CoordinateReferenceSystem | cognite.client.data_classes.geospatial.CoordinateReferenceSystemWrite | collections.abc.Sequence[cognite.client.data_classes.geospatial.CoordinateReferenceSystem] | collections.abc.Sequence[cognite.client.data_classes.geospatial.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
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: Optional[float] = None, raster_scale_y: Optional[float] = 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
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: Optional[dict[str, Any]] = None, raster_srid: Optional[int] = None, raster_scale_x: Optional[float] = None, raster_scale_y: Optional[float] = 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, cognite.client.data_classes.geospatial.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
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
srid (int | None) – EPSG code, e.g., 4326. Only valid for geometry types. See https://en.wikipedia.org/wiki/Spatial_reference_system
wkt (str | None) – Well-known text of the geometry, see https://docs.geotools.org/stable/javadocs/org/opengis/referencing/doc-files/WKT.html
proj_string (str | None) – The projection specification string as described in https://proj.org/usage/quickstart.html
cognite_client (CogniteClient | None) – The client to associate with this object.
- as_write() CoordinateReferenceSystemWrite
Returns a write version of this coordinate reference system.
- class cognite.client.data_classes.geospatial.CoordinateReferenceSystemCore(srid: Optional[int] = None, wkt: Optional[str] = None, proj_string: Optional[str] = None)
Bases:
WriteableCogniteResource
[CoordinateReferenceSystemWrite
],ABC
A representation of a feature in the geospatial API.
- Parameters
srid (int | None) – EPSG code, e.g., 4326. Only valid for geometry types. See https://en.wikipedia.org/wiki/Spatial_reference_system
wkt (str | None) – Well-known text of the geometry, see https://docs.geotools.org/stable/javadocs/org/opengis/referencing/doc-files/WKT.html
proj_string (str | None) – The projection specification string as described in https://proj.org/usage/quickstart.html
- class cognite.client.data_classes.geospatial.CoordinateReferenceSystemList(resources: Iterable[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
srid (int) – EPSG code, e.g., 4326. Only valid for geometry types. See https://en.wikipedia.org/wiki/Spatial_reference_system
wkt (str) – Well-known text of the geometry, see https://docs.geotools.org/stable/javadocs/org/opengis/referencing/doc-files/WKT.html
proj_string (str) – The projection specification string as described in https://proj.org/usage/quickstart.html
- as_write() CoordinateReferenceSystemWrite
Returns this CoordinateReferenceSystemWrite instance.
- class cognite.client.data_classes.geospatial.CoordinateReferenceSystemWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)
- 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: Iterable[Any], cognite_client: CogniteClient | None = None)
Bases:
CogniteResourceList
[FeatureAggregate
]
- class cognite.client.data_classes.geospatial.FeatureCore(external_id: Optional[str] = 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: Iterable[Any], cognite_client: CogniteClient | None = None)
Bases:
FeatureListCore
[Feature
]
- class cognite.client.data_classes.geospatial.FeatureListCore(resources: Iterable[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
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: Optional[str] = None, data_set_id: Optional[int] = None, properties: Optional[dict[str, Any]] = None, search_spec: Optional[dict[str, Any]] = 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: Iterable[Any], cognite_client: CogniteClient | None = None)
Bases:
WriteableCogniteResourceList
[FeatureTypeWrite
,FeatureType
],ExternalIDTransformerMixin
- 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: Optional[int] = None, search_spec: Optional[dict[str, Any]] = 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: Iterable[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: Iterable[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: Iterable[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: Optional[Union[dict[str, Any], list[str]]] = None, search_spec: Optional[Union[dict[str, Any], list[str]]] = 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.