Search and stream features

POST

geospatial

featuretypes

{featureTypeExternalId}

features

search-streaming

JavaScript SDK

const params = {
 filter: {
   and: [
     { range:{ property: 'temperature', gt:4.54 } },
     { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }
  ]
 },
 limit: 100,
 output: { jsonStreamFormat: 'NEW_LINE_DELIMITED' as const }
};

const featureStreamString = await client.geospatial.feature.searchStream('ocean_temperature', params);

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "and": [
      {
        "range": {
          "property": "temperature",
          "gt": 4.54
        }
      },
      {
        "stWithin": {
          "property": "location",
          "value": {
            "wkt": "POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))"
          }
        }
      }
    ]
  },
  "limit": 100,
  "output": {
    "jsonStreamFormat": "NEW_LINE_DELIMITED"
  }
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming"

payload = {
    "filter": { "and": [{ "range": {
                    "property": "temperature",
                    "gt": 4.54
                } }, { "stWithin": {
                    "property": "location",
                    "value": { "wkt": "POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))" }
                } }] },
    "limit": 100,
    "output": { "jsonStreamFormat": "NEW_LINE_DELIMITED" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => [
        'and' => [
                [
                                'range' => [
                                                                'property' => 'temperature',
                                                                'gt' => 4.54
                                ]
                ],
                [
                                'stWithin' => [
                                                                'property' => 'location',
                                                                'value' => [
                                                                                                                                'wkt' => 'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))'
                                                                ]
                                ]
                ]
        ]
    ],
    'limit' => 100,
    'output' => [
        'jsonStreamFormat' => 'NEW_LINE_DELIMITED'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming"

	payload := strings.NewReader("{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "externalId": "my.known.id",
  "createdTime": 1730204346000,
  "lastUpdatedTime": 1730204346000
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ],
    "invalid": [
      {}
    ],
    "dependencies": [
      {}
    ]
  }
}

Authorizations

Authorization

string

header

required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Scopes

https://{cluster}.cognitedata.com/.default

oidc-token

https://{cluster}.cognitedata.com/.default

oauth2-client-credentials

https://api.cognitedata.com/.default

oauth2-open-industrial-data

https://{cluster}.cognitedata.com/.default

oauth2-auth-code

Path Parameters

featureTypeExternalId

string

required

External Id of the feature type provided by client. Must be unique among all feature type external ids within a CDF project.

Maximum string length: 32

Pattern: ^[A-Za-z][A-Za-z0-9_]{0,31}$

Example:

"ocean_measures"

Body

application/json

Search and streaming feature request

allowCrsTransformation

boolean

Optional parameter indicating if input geometry properties should be transformed into the respective Coordinate Reference Systems defined in the feature type specification. If the parameter is true, then input geometries will be transformed when the input and output Coordinate Reference Systems differ. When it is false, then requests with geometries in Coordinate Reference System different from the ones defined in the feature type will result in bad request response code. Transformations apply to property geometries in case of create and update feature, as well as to geometries in spatial filters in search endpoints.

Example:

true

allowDimensionalityMismatch

boolean

Optional parameter indicating if the spatial filter operators allow input geometries with a different dimensionality than the properties they are applied to. For instance, when set to true, if a feature type has a property of type POLYGONZM (4D), its features can be filtered using the stContains operator and a POLYGON (2D) value. This option defaults to false if not specified.

Example:

true

filter

object

Show child attributes

limit

number

output

object

Desired output specification for streaming.

Show child attributes

Example:

{
  "jsonStreamFormat": "LENGTH_PREFIXED",
  "properties": {
    "*": {},
    "geometry1": { "srid": 4326 },
    "geometry2": { "srid": 3857 }
  }
}

Response

The feature search streaming response - it can be length prefixed, new line delimited, record separator delimited or concatenated depending on requested output.

externalId

string

The external ID provided by the client. Must be unique for the resource type.

Maximum string length: 255

Example:

"my.known.id"

createdTime

integer<int64>

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Required range: x >= 0

Example:

1730204346000

lastUpdatedTime

integer<int64>

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Required range: x >= 0

Example:

1730204346000

{key}

⌘I

JavaScript SDK

const params = {
 filter: {
   and: [
     { range:{ property: 'temperature', gt:4.54 } },
     { stWithin: { property:'location', value:'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))' } }
  ]
 },
 limit: 100,
 output: { jsonStreamFormat: 'NEW_LINE_DELIMITED' as const }
};

const featureStreamString = await client.geospatial.feature.searchStream('ocean_temperature', params);

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "and": [
      {
        "range": {
          "property": "temperature",
          "gt": 4.54
        }
      },
      {
        "stWithin": {
          "property": "location",
          "value": {
            "wkt": "POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))"
          }
        }
      }
    ]
  },
  "limit": 100,
  "output": {
    "jsonStreamFormat": "NEW_LINE_DELIMITED"
  }
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming"

payload = {
    "filter": { "and": [{ "range": {
                    "property": "temperature",
                    "gt": 4.54
                } }, { "stWithin": {
                    "property": "location",
                    "value": { "wkt": "POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))" }
                } }] },
    "limit": 100,
    "output": { "jsonStreamFormat": "NEW_LINE_DELIMITED" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => [
        'and' => [
                [
                                'range' => [
                                                                'property' => 'temperature',
                                                                'gt' => 4.54
                                ]
                ],
                [
                                'stWithin' => [
                                                                'property' => 'location',
                                                                'value' => [
                                                                                                                                'wkt' => 'POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))'
                                                                ]
                                ]
                ]
        ]
    ],
    'limit' => 100,
    'output' => [
        'jsonStreamFormat' => 'NEW_LINE_DELIMITED'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming"

	payload := strings.NewReader("{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/geospatial/featuretypes/{featureTypeExternalId}/features/search-streaming")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": {\n    \"and\": [\n      {\n        \"range\": {\n          \"property\": \"temperature\",\n          \"gt\": 4.54\n        }\n      },\n      {\n        \"stWithin\": {\n          \"property\": \"location\",\n          \"value\": {\n            \"wkt\": \"POLYGON((60.547602 -5.423433, 60.547602 -6.474416, 60.585858 -6.474416, 60.585858 -5.423433, 60.547602 -5.423433))\"\n          }\n        }\n      }\n    ]\n  },\n  \"limit\": 100,\n  \"output\": {\n    \"jsonStreamFormat\": \"NEW_LINE_DELIMITED\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "externalId": "my.known.id",
  "createdTime": 1730204346000,
  "lastUpdatedTime": 1730204346000
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ],
    "invalid": [
      {}
    ],
    "dependencies": [
      {}
    ]
  }
}