Client API (Sync/Async)

Usage example

gps_tracker provides both a Synchronous Client and an Asynchronous Client both implementing the same methods.

The use of each client is illustrated in the following example:

from gps_tracker import AsyncClient, Client, Config


def main(config):
    """Use of synchronous client."""
    client = Client(cfg)

    users = client.get_users()
    return users


async def async_main(config):
    """Use of asynchronous client."""

    async with AsyncClient(config) as client:
        users = await client.get_users()

    return users


async def async_main_nocontext(config):
    """Use of async client without context."""
    client = AsyncClient(config)

    users = await client.get_users()

    client.close()
    return users


if __name__ == "__main__":
    cfg = Config(username="myusername", password="mypassword")

    users_sync = main(cfg)
    users_async1 = await async_main(cfg)
    users_async2 = await async_main_nocontext(cfg)

Asynchronous client: closing the session

As illustrated previously, asynchronous clients must be closed either by:

  • Using an asynchronous context manager

async with AsyncClient(config) as client:
    ...  # Use client to retrieve data

  • By explicitly calling the close() method:

client = AsyncClient(config)

...  # use client to retrieve data

client.close()

Client methods

Retrieve user details

Invoxia™ API seems to allow multiple users to be associated to a given account. All these users can be retrieved by:

users: List[User] = client.get_users()

Where User contains

The notion of profiles seems to be useful only for pro users of Invoxia™ devices and services. Devices can be associated to theses profiles but for general consumers, only a single profile is associated to your account, thus making profiles irrelevant. similarly, you will only have a single User associated to your credentials.

A single User can also be retrieve if its id is known:

user: User = client.get_user(user_id)

Retrieve devices

Invoxia™ API lets you access the list of devices associated to your account. These contain not only your trackers, but also the smartphones you installed the Invoxia™ app on. To get the list of all your devices, user

devices: List[Device] = client.get_devices()

Each Device defines its

  • id

  • name

  • created: date-time when the device was added to your account

  • timezone: timezone associated to your device

  • version: version of the smartphone app or of the tracker firmware

  • serial: serial number of the device

Moreover, Device which are also Tracker instances will have following attributes:

  • tracker_config: Device configuration

  • tracker_status: Current device status

You may retrieve only trackers with

trackers: List[Device] = client.get_devices(kind="tracker")

or with its alias which is typed to return List[Tracker]

trackers: List[Tracker] = client.get_trackers()

Get tracker location

Once you obtain a Tracker instance, you may query its locations with

locations: List[TrackerData] = client.get_locations(tracker)

You may limit the time-period for which you query locations and/or the maximum count of locations to return:

locations: List[TrackerData] = client.get_locations(
    tracker,
    not_before=datetime.datetime(year=2021, month=10, day=8),
    not_after=datetime.datetime(year=2021, month=12, day=31),
    max_count=50,
)

Note that one API query returns up to 20 locations. Asking for more than that will thus be slower.

Exceptions

All client methods which interrogate the Invoxia™ API can return any of the following exceptions which all derive from the base exception GpsTrackerException:

  • ApiConnectionError: Error raised during the connection to the API endpoint (failed DNS lookup, SSL issue, internet connection not available, …).

  • UnknownAnswerScheme: The data returned by the API does not match expected content. Please open an issue is you face this exception so that the data scheme can be updated.

  • UnknownDeviceType: A device of unknown type is linked to your account. Please open an issue if you face this exception so that the new kind of device can be supported by gps_tracker.

  • UnauthorizedQuery: Your credentials are incorrect.

  • ForbiddenQuery: You are correctly authenticated but you are requesting data for which you do not have the permissions.

  • NoContentQuery: The server does not have any data for your request. Happens mainly when asking for tracker-specific data on a non-tracker device.

  • FailedQuery: The server returned an error code which does not correspond to any previous exception.