Skip to content
camara
Get started
API Reference
Regiondevicecount

API operation to get the device count in the specified area during a certain time interval.

client.regiondevicecount.getCount(RegiondevicecountGetCountParams { area, endtime, filter, 4 more } params, RequestOptionsoptions?): RegiondevicecountGetCountResponse { count, status }
POST/regiondevicecount/count

Get the number of devices in the specified area during a certain time interval.

  • The query area can be a circle or a polygon composed of longitude and latitude points.
  • If the areaType is circle, the circleCenter and circleRadius must be provided; if the area is a polygon, the point list must be provided.
  • If starttime and endtime are not passed in,this api should return the current number of devices in the area.
  • If the device appears in the specified area at least once during the certain time interval, it should be counted.
ParametersExpand Collapse
params: RegiondevicecountGetCountParams { area, endtime, filter, 4 more }
area?: Area

Body param

areaType: "CIRCLE" | "POLYGON"

Type of this area. CIRCLE - The area is defined as a circle. POLYGON - The area is defined as a polygon.

One of the following:
"CIRCLE"
"POLYGON"
endtime?: string | null

Body param: Ending timestamp for counting the number of devices in the area. It must follow RFC 3339 and must have time zone.

formatdate-time
filter?: Filter

Body param: This parameter is used to filter devices. Currently, two filtering criteria are defined, roamingStatus and deviceType, which can be expanded in the future. IN logic is used used for multiple filtering items within a single filtering criterion, AND logic is used between multiple filtering criteria.

  • If a filtering critera is not provided, it means that there is no need to filter this item.
  • At least one of the criteria must be provided,a filter without any criteria is not allowed.
  • If no filtering is required, this parameter does not need to be provided. For example ,"filter":{"roamingStatus": ["roaming"],"deviceType": ["human device","IoT device"]} means the API need to return the count of human network devices and IoT devices that are in roaming mode."filter":{"roamingStatus": ["non-roaming"]} means that the API need to return the count of all devices that are not in roaming mode.
deviceType?: Array<"human device" | "IoT device" | "other">

Filtering by device type, ‘human device’ represents the need to filter for human network devices, ‘IoT device’ represents the need to filter for IoT devices, and ‘other’ represents the need to filter for other types of devices.

One of the following:
"human device"
"IoT device"
"other"
roamingStatus?: Array<"roaming" | "non-roaming">

Filter whether the device is in roaming mode,‘roaming’ represents the need to filter devices that are in roaming mode,‘non-roaming’ represents the need to filter devices that are not roaming.

One of the following:
"roaming"
"non-roaming"
sink?: string

Body param: The URL where the API response will be asynchronously delivered, using the HTTP protocol.

formaturi
sinkCredential?: SinkCredential

Body param: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.

credentialType: "PLAIN" | "ACCESSTOKEN" | "REFRESHTOKEN"

The type of the credential. Note: Type of the credential - MUST be set to ACCESSTOKEN for now

One of the following:
"PLAIN"
"ACCESSTOKEN"
"REFRESHTOKEN"
starttime?: string | null

Body param: Starting timestamp for counting the number of devices in the area. It must follow RFC 3339 and must have time zone.

formatdate-time
xCorrelator?: string

Header param: Correlation ID for cross-service tracking

ReturnsExpand Collapse
RegiondevicecountGetCountResponse { count, status }

RegionDeviceCount result

count?: number

Device Count

status?: "SUPPORTED_AREA" | "PART_OF_AREA_NOT_SUPPORTED" | "AREA_NOT_SUPPORTED" | 2 more

SUPPORTED_AREA: The whole requested area is supported Region Device Count for the entire requested area is returned - Telco Coverage = 100 %

PART_OF_AREA_NOT_SUPPORTED: Part of the requested area is outside the MNOs coverage area, the area outside the coverage area are not returned - 100% >Telco Coverage >=50%

AREA_NOT_SUPPORTED: The whole requested area is outside the MNO coverage area No data will be returned- Telco Coverage <50%

DENSITY_BELOW_PRIVACY_THRESHOLD: The number of connected devices is below privacy threshold of local regulation

TIME_INTERVAL_NO_DATA_FOUND: Unable to find device count data within the requested time interval

One of the following:
"SUPPORTED_AREA"
"PART_OF_AREA_NOT_SUPPORTED"
"AREA_NOT_SUPPORTED"
"DENSITY_BELOW_PRIVACY_THRESHOLD"
"TIME_INTERVAL_NO_DATA_FOUND"

API operation to get the device count in the specified area during a certain time interval.

import Camara from 'camara-sdk';

const client = new Camara({
  bearerToken: process.env['CAMARA_BEARER_TOKEN'], // This is the default and can be omitted
});

const response = await client.regiondevicecount.getCount({
  area: { areaType: 'CIRCLE' },
  endtime: '2023-07-04T14:27:08.312+02:00',
  filter: { roamingStatus: ['roaming'], deviceType: ['human device', 'IoT device'] },
  sink: 'https://endpoint.example.com/sink',
  sinkCredential: { credentialType: 'ACCESSTOKEN' },
  starttime: '2023-07-03T14:27:08.312+02:00',
});

console.log(response.count);
{
  "count": 100,
  "status": "SUPPORTED_AREA"
}
{
  "count": 100,
  "status": "PART_OF_AREA_NOT_SUPPORTED"
}
{
  "status": "AREA_NOT_SUPPORTED"
}
{
  "status": "DENSITY_BELOW_PRIVACY_THRESHOLD"
}
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.TIME_INVALID_ARGUMENT",
  "message": "starttime and endtime cannot be passed separately. Either both are passed or neither is passed."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_END_DATE",
  "message": "Indicated endTime is earlier than the startTime."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_CIRCLE_AREA",
  "message": "Missing circle center or radius."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_POLYGON_AREA",
  "message": "The area is not a polygon shape or has an arbitrary complexity."
}
{
  "status": 400,
  "code": "INVALID_CREDENTIAL",
  "message": "Only Access token is supported"
}
{
  "status": 400,
  "code": "INVALID_TOKEN",
  "message": "Only bearer token is supported"
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.UNSUPPORTED_SYNC_RESPONSE",
  "message": "Indicated combination of area or time interval is too big for a sync response"
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.UNSUPPPORTED_REQUEST",
  "message": "Indicated combination of area or time interval is too big"
}
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials."
}
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}
{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "{{field}} is not consistent with access token."
}
{
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "message": "Out of resource quota."
}
{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit reached."
}
Returns Examples
{
  "count": 100,
  "status": "SUPPORTED_AREA"
}
{
  "count": 100,
  "status": "PART_OF_AREA_NOT_SUPPORTED"
}
{
  "status": "AREA_NOT_SUPPORTED"
}
{
  "status": "DENSITY_BELOW_PRIVACY_THRESHOLD"
}
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.TIME_INVALID_ARGUMENT",
  "message": "starttime and endtime cannot be passed separately. Either both are passed or neither is passed."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_END_DATE",
  "message": "Indicated endTime is earlier than the startTime."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_CIRCLE_AREA",
  "message": "Missing circle center or radius."
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.INVALID_POLYGON_AREA",
  "message": "The area is not a polygon shape or has an arbitrary complexity."
}
{
  "status": 400,
  "code": "INVALID_CREDENTIAL",
  "message": "Only Access token is supported"
}
{
  "status": 400,
  "code": "INVALID_TOKEN",
  "message": "Only bearer token is supported"
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.UNSUPPORTED_SYNC_RESPONSE",
  "message": "Indicated combination of area or time interval is too big for a sync response"
}
{
  "status": 400,
  "code": "REGION_DEVICE_COUNT.UNSUPPPORTED_REQUEST",
  "message": "Indicated combination of area or time interval is too big"
}
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials."
}
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}
{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "{{field}} is not consistent with access token."
}
{
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "message": "Out of resource quota."
}
{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit reached."
}