Location verification
The location verification feature allows you to check if a device is at a given location or not at a given moment. Network as Code sends a location retrieval request to the Network Operator, which will then tell you whether the device is within the circle you defined.
Think of the following scenario: A bank wants to check if an account holder's device is close to the ATM or even the bank branch where a transaction is about to take place. For security or authorization purposes, for example, they may wish to use the location feature.
NOTE: Querying a device's location might have serious privacy implications. So, it should be done carefully and strict authorization may be needed.
Creating a Device ID and querying specific geographic coordinates
This section has some SDK code-snippets that will allow you to create a Device ID and verify its location in just a few minutes!
import network_as_code as nac
from network_as_code.models.location import CivicAddress, Location
from network_as_code.models.device import Device, DeviceIpv4Addr
# Begin with the client object followed by the NetworkAsCodeClient() method and client's token:
client = nac.NetworkAsCodeClient(
token="<your-application-key-here>"
)
# This step will require the External Identifier, IP and ports input:
device = client.devices.get("device@testcsp.net",
ipv4_address = DeviceIpv4Addr(public_address="233.252.0.2",
private_address="192.0.2.25",
public_port=80)
)
# Create a location object followed by a method that will enable it:
location = device.location()
# For estimations, use the is_there object followed by a method with the geographic coordinates:
is_there = device.verify_location(longitude=19, latitude=47, radius=10_000, max_age=60)
Location
- The
locationobject is created to represent the device's current location using thedevice.location()method.
Verification
- A device location verification can be performed using the
device.verify_location()method.
Device object parameters
The snippet above identified a mobile network device in multiple ways (IP addresses, port, etc). Learn how to create a device object and understand how the DeviceIPv4Addr model works using NAT technology.
Location verification parameters
The device.verify_location() method, mentioned in the code above,
will require all the following mandatory parameters:
| Parameters | Description |
|---|---|
latitude=47 | Latitude: it expects the latitude integer or float value to be informed. |
longitude=19 | Longitude: it expects the longitude integer or float value to be informed. |
radius=10_000 | Radius: the radius integer or float value should be given as number of meters. Note that for the verification check, the maximum distance allowed between the device and the center of the circle (radius) is about 10.000 meters. |
max_age=60 | Maximum Age: it indicates the maximum age accepted for the location information request. Here you should inform the integer value expected in seconds. Let's suppose you don't want to receive location information which is older than 1 minute. Then, defining the value in seconds, 60, will check if the device was at the location radius defined at least 1 minute ago. |
Good to know: If the location information is older than the one accepted, which was defined with the
max_age=60parameter, then the output of request will beUNKNOWN.
Accuracy of the location query
It's also good to know the accuracy of this feature is on Cell ID level and a brief loss of connection will not affect the service, which is provided promptly upon each request. Here are the inputs and outputs expected for this feature:
- Input: The geo-coordinate values for latitude, longitude, radius and the maximum age (time amount in seconds) accepted for the location information request. These are all mandatory parameters.
- Output: It will tell whether a device is within the circle defined by its center location and radius (maximum distance). It can also be unknown in case the location information is older than the maximum age accepted or if the device location cannot be accessed.
Remember that the geo-spatial coordinates here work on Earth only and if the radius is larger than half of Earth's circumference, it should be enough to tell if the device is in our home planet.
Note: The location data might be more accurate in areas with a dense concentration of base stations, but less accurate in more sparse or remote areas.
Last updated on July 31, 2023