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

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.

Header ParametersExpand Collapse

"x-correlator": optional string

Body ParametersJSONExpand Collapse

area: optional object { areaType }

areaType: "CIRCLE" or "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: optional string

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

formatdate-time

filter: optional object { deviceType, roamingStatus }

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: optional array of "human device" or "IoT device" or "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: optional array of "roaming" or "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: optional string

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

formaturi

sinkCredential: optional object { credentialType }

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

credentialType: "PLAIN" or "ACCESSTOKEN" or "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: optional string

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

formatdate-time

ReturnsExpand Collapse

count: optional number

Device Count

status: optional "SUPPORTED_AREA" or "PART_OF_AREA_NOT_SUPPORTED" or "AREA_NOT_SUPPORTED" or 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.

curl https://api.example.com/camara/regiondevicecount/count \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CAMARA_BEARER_TOKEN" \
    -d '{
          "endtime": "2023-07-04T14:27:08.312+02:00",
          "sink": "https://endpoint.example.com/sink",
          "starttime": "2023-07-03T14:27:08.312+02:00"
        }'

{
  "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."
}