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
 
# We initialize the client object with your application key
client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)
 
# Create a device object for the mobile device we want to use
my_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
    ),
    ipv6_address = "2001:db8:1234:5678:9abc:def0:fedc:ba98",
    # The phone number accepts the "+" sign, but not spaces or "()" marks
    phone_number = "36721601234567"
)
 
# For estimations, use the is_there object
# followed by the `verify_location()` method
# with the geo-coordinates and maximum age in seconds.
# If the amount in seconds is not given, the default will be 60 seconds.
is_there = my_device.verify_location(
    longitude=60.252,
    latitude=25.227,
    radius=10_000,
    max_age=3600
)

Device object parameters

The snippets 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

Here are all the mandatory parameters for location estimations and a more detailed description of what they should contain:

ParameterDescription
latitudeIt expects the latitude integer or float value to be informed.
longitudeIt expects the longitude integer or float value to be informed.
radiusThe radius integer or float value should be given as number of meters.
max_ageThe maximum age accepted for the location information request.

Good to know: Verifying location in sparse areas might require a larger radius. If the location information is older than the one you defined in seconds, then the output of request will be UNKNOWN.

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. 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 May 23, 2024