Geolocation

Description

The geolocation module, given the required information, queries the geolocation data of lte devices.

Events

Following events are transmitted via the websocket.

GEOLOCATION_DEVICE_UPDATE

GEOLOCATION_DEVICE_DELETE

GEOLOCATION_CACHE_SET

GEOLOCATION_CACHE_DELETE

This event is sent via the websocket when a device updates either its properties that hold location information of when the actual location is known. This event requires read access to the resource geolocation.devices.

Name	Description
type stringconstant	Constant value: GEOLOCATION_DEVICE_UPDATE
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
propertyInformation objectoptional
propertyInformation.cellId numberoptional	The cell id of the device
propertyInformation.mobileCountryCode numberoptional	The mobile country code of the device
propertyInformation.mobileNetworkCode numberoptional	The mobile network code of the device
propertyInformation.locationAreaCode numberoptional	The location area code of the device
locationInformation objectoptional
locationInformation.location objectoptional
locationInformation.location.lat number	Latitude coordinate of the cell tower
locationInformation.location.lng number	Longitude coordinate of the cell tower
locationInformation.accuracy numberoptional	Approximate accuracy in meters.
locationInformation.recordedAt numberoptional	Unix timestamp when this was fetched via the API.

API

Endpoints

GET

List geo location cache data

DEL

Clear geo location cache

GET

List geo location device data

GET

Get geo location data for a device

DEL

Clear geo location device data

DEL

Remove device geo location data

List geo location cache data

Returns a list of currently cached geo location data.

GET

/api/v1/geolocation/cache

Access

This endpoint requires read permission for the resource geolocation.cache.

Response

Name	Description
location object
location.lat number	Latitude coordinate of the cell tower
location.lng number	Longitude coordinate of the cell tower
accuracy number	Approximate accuracy in meters.
recordedAt number	Unix timestamp when this was fetched via the API.
cellId number	The cell id of the device
mobileCountryCode number	The mobile country code of the device
mobileNetworkCode number	The mobile network code of the device
locationAreaCode number	The location area code of the device

Clear geo location cache

Clears the complete cache and forces a new fetch of entries.

DELETE

/api/v1/geolocation/cache

Access

This endpoint requires delete permission for the resource geolocation.cache.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

List geo location device data

Returns a list of geo location data for devices.

GET

/api/v1/geolocation/devices

Access

This endpoint requires read permission for the resource geolocation.devices.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
geoLocationInformation objectoptional
geoLocationInformation.propertyInformation objectoptional
geoLocationInformation.propertyInformation.cellId numberoptional	The cell id of the device
geoLocationInformation.propertyInformation.mobileCountryCode numberoptional	The mobile country code of the device
geoLocationInformation.propertyInformation.mobileNetworkCode numberoptional	The mobile network code of the device
geoLocationInformation.propertyInformation.locationAreaCode numberoptional	The location area code of the device
geoLocationInformation.locationInformation objectoptional
geoLocationInformation.locationInformation.location objectoptional
geoLocationInformation.locationInformation.location.lat number	Latitude coordinate of the cell tower
geoLocationInformation.locationInformation.location.lng number	Longitude coordinate of the cell tower
geoLocationInformation.locationInformation.accuracy numberoptional	Approximate accuracy in meters.
geoLocationInformation.locationInformation.recordedAt numberoptional	Unix timestamp when this was fetched via the API.

Get geo location data for a device

Returns a single entry of geo location data for a device if present.

GET

/api/v1/geolocation/devices/:deviceIdentifier

Access

This endpoint requires read permission for the resource geolocation.devices.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

Name	Description
propertyInformation objectoptional
propertyInformation.cellId numberoptional	The cell id of the device
propertyInformation.mobileCountryCode numberoptional	The mobile country code of the device
propertyInformation.mobileNetworkCode numberoptional	The mobile network code of the device
propertyInformation.locationAreaCode numberoptional	The location area code of the device
locationInformation objectoptional
locationInformation.location objectoptional
locationInformation.location.lat number	Latitude coordinate of the cell tower
locationInformation.location.lng number	Longitude coordinate of the cell tower
locationInformation.accuracy numberoptional	Approximate accuracy in meters.
locationInformation.recordedAt numberoptional	Unix timestamp when this was fetched via the API.

Clear geo location device data

Clears the complete geo location device data.

DELETE

/api/v1/geolocation/devices

Access

This endpoint requires delete permission for the resource geolocation.devices.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Remove device geo location data

Clears the geo location data for a single device.

DELETE

/api/v1/geolocation/devices/:deviceIdentifier

Access

This endpoint requires delete permission for the resource geolocation.devices.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.