Location retrieval

This feature allows you to get the geographic coordinates of a device and exhibit them on the screen. You will also need to specify a certain amount of time or maximum time limit for the location information you receive. This way, your device's location will always be up to date!

NOTE: Querying a device's location might have serious privacy implications. So, it should be done carefully and strict authorization may be needed.

Retrieving and displaying a device's location

Retrieving the location of a device can be fairly simple. Assuming a device was already created in this previous step, a location object, as the ones below, can be instantiated from the fields for longitude and latitude.

You can use the following code snippets to exhibit a device's geographic coordinates and address on the screen:

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>",
)
 
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"
)
 
# Specify the maximum amount of time accepted
# to get location information, it's a mandatory parameter.
# If the amount in seconds is not given, the default will be 60 seconds.
location = my_device.location(max_age=3600)
 
# The location object contains fields for longitude, latitude and also elevation
longitude = location.longitude
latitude = location.latitude
 
 
print(longitude)
print(latitude)
print(location.civic_address)

What does this code do?

It will print your device's current latitude, longitude coordinates.

NOTE: The civic address is an optional field in the query response. If it is set in the API, then it will return the device's current civic address. In case it is not set, it may also return None on undefined values.

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 retrieval parameters

The only mandatory parameter to retrieve a location is the Maximum Age. You should inform the integer value expected in seconds. Let's suppose you don't want to retrieve information older than 1 hour. Then, defining the value in seconds, for example 3600, will check if the device was at the location informed at least 1 hour ago.

ParameterDescription
max_ageThe maximum age accepted for the location information request.

Good to know: If the location information is older than the one accepted, which was defined with the max_age parameter, then the output of request will be UNKNOWN.

Remember: The location data does not update automatically. So, to get an up-to-date device location, just fetch it again:

location = my_device.location(max_age=3600)
 
print(location)

Important to keep in mind: 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