gps_tracker.client package

Submodules

gps_tracker.client.asynchronous module

Asynchronous client for Invoxia API.

class gps_tracker.client.asynchronous.AsyncClient(config: Config)

Bases: object

Asynchronous client for Invoxia API.

async close()

Close current session.

async get_device(device_id: int) → gps_tracker.client.datatypes.Device

Return a device referenced by its id.

Parameters

device_id (int) – Unique identifier of a device

Returns

Device instance of given id

Return type

Device

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – Device of given ID is not linked to current account

• aiohttp.ClientResponseError – Unexpected HTTP error during API call

async get_devices(kind: Optional[str] = None) → List[gps_tracker.client.datatypes.Device]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters

kind (str, optional) – kind of devices to retrieve

Returns

List of retrieved devices

Return type

List[Device]

Raises

• UnauthorizedQuery – Credentials are invalid

• aiohttp.ClientResponseError – Unexpected HTTP error during API call

• KeyError – Undefined kind requested

async get_locations(device: gps_tracker.client.datatypes.Tracker, not_before: Optional[datetime.datetime] = None, not_after: Optional[datetime.datetime] = None, max_count: int = 20) → List[gps_tracker.client.datatypes.TrackerData]

Extract the list of tracker locations.

Parameters

• device (Tracker) – The tracker instance whose locations must be extracted.

• not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.

• not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.

• max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns

List of extracted locations

Return type

List[TrackerData]

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – provided Device is not linked to current account (should not happen if Device was obtained with get_devices()).

• aiohttp.ClientResponseError – Unexpected HTTP error during API call

async get_tracker_config(device: gps_tracker.client.datatypes.Tracker) → gps_tracker.client.datatypes.TrackerConfig

Get the current configuration of a given tracker.

Parameters

device (Tracker) – The tracker instance whose configuration is queried.

Returns

Current config of the tracker

Return type

TrackerConfig

async get_tracker_status(device: gps_tracker.client.datatypes.Tracker) → gps_tracker.client.datatypes.TrackerStatus

Get the current status of a given tracker.

Parameters

device (Tracker) – The tracker instance whose status is queried.

Returns

Current status of the tracker

Return type

TrackerStatus

async get_trackers() → List[gps_tracker.client.datatypes.Tracker]

Query API for the list of trackers associated to credentials.

Returns

Tracker devices associated to current account

Return type

List[Tracker]

Raises

• UnauthorizedQuery – Credentials are invalid

• requests.HTTPError – Unexpected HTTP error during API call

async get_user(user_id: int) → gps_tracker.client.datatypes.User

Return a user referenced by its id.

Parameters

user_id (int) – ID of the user to retrieve

Returns

User instance associated to given ID

Return type

User

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – User of given ID is not linked to current account

• aiohttp.ClientResponseError – Unexpected HTTP error during API call

async get_users() → List[gps_tracker.client.datatypes.User]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns

List of User instances associated to account

Return type

List[User]

Raises

• UnauthorizedQuery – Credentials are invalid

• aiohttp.ClientResponseError – Unexpected HTTP error during API call

gps_tracker.client.config module

Definition of Client configuration.

class gps_tracker.client.config.Config(username: str, password: str, api_url: str = 'https://labs.invoxia.io')

Bases: object

Configuration for API Clients.

api_url: str

Invoxia API URL.

classmethod default_api_url() → str

Return the default API URL.

password: str

Password used as credentials on Invoxia account.

username: str

Username used as credentials on Invoxia account.

gps_tracker.client.datatypes module

Data-types returned by Invoxia API.

class gps_tracker.client.datatypes.Android(id, created: Optional[str], name, timezone, version, serial)

Bases: gps_tracker.client.datatypes.Device

Definition of devices of type ‘android’.

created: datetime.datetime

Datetime of device registration.

id: int

Device unique identifier.

name: str

Device name.

serial: uuid.UUID

Device Universally Unique Identifier

timezone: str

Timezone associated to device.

version: str

Device version.

class gps_tracker.client.datatypes.Device(id, created: Optional[str], name, timezone, version)

Bases: object

Base class for devices.

created: datetime.datetime

Datetime of device registration.

static get(device_data: dict[str, Any]) → Device

Generate a Device object based on its type.

classmethod get_types() → Iterable[str]

Return list of registered device types.

id: int

Device unique identifier.

name: str

Device name.

timezone: str

Timezone associated to device.

version: str

Device version.

class gps_tracker.client.datatypes.Iphone(id, created: Optional[str], name, timezone, version, serial)

Bases: gps_tracker.client.datatypes.Device

Definition of devices of type ‘iphone’.

created: datetime.datetime

Datetime of device registration.

id: int

Device unique identifier.

name: str

Device name.

serial: uuid.UUID

Device Universally Unique Identifier

timezone: str

Timezone associated to device.

version: str

Device version.

class gps_tracker.client.datatypes.Tracker(id, created: Optional[str], name, timezone, version)

Bases: gps_tracker.client.datatypes.Device

Base class for trackers.

created: datetime.datetime

Datetime of device registration.

id: int

Device unique identifier.

name: str

Device name.

timezone: str

Timezone associated to device.

version: str

Device version.

class gps_tracker.client.datatypes.Tracker01(id, created: Optional[str], name, timezone, version, serial, version_build, tracker_config: Dict[str, Any], tracker_status: Dict[str, Any], model: Optional[str] = None)

Bases: gps_tracker.client.datatypes.Tracker

Definition of devices of type ‘tracker_01’.

created: datetime.datetime

Datetime of device registration.

id: int

Device unique identifier.

model: Optional[str]

Tracker model.

name: str

Device name.

serial: str

Tracker serial number.

timezone: str

Timezone associated to device.

tracker_config: gps_tracker.client.datatypes.TrackerConfig

Tracker configuration data.

tracker_status: gps_tracker.client.datatypes.TrackerStatus

Tracker current status.

version: str

Device version.

version_build: str

Firmware build reference (To be confirmed).

class gps_tracker.client.datatypes.TrackerConfig(board_name, color, firmware_path, icon, mode, network, network_config, network_region, notify_position, notify_long_walk, usage, image: Optional[str] = None, weight=None)

Bases: object

Definition of tracker config data.

board_name: str

Tracker board-model reference.

color: int

Icon color.

firmware_path: str

URL to firmware update (To be confirmed).

icon: gps_tracker.client.datatypes.TrackerIcon

ID of the icon selected for this tracker.

image: Optional[str]

Image reference when icon as been replaced by a user-defined image.

mode: gps_tracker.client.datatypes.TrackerMode

Operating mode of the tracker.

network: str

Network used by tracker (LoRa/SigFox).

network_config: int

To be determined.

network_region: str

Region configured for the network (To be confirmed).

notify_long_walk: bool

To be determined. Probably related to pet mode.

notify_position: bool

Whether notifications must be send when tracker position changes.

usage: gps_tracker.client.datatypes.TrackerUsage

Tracker usage defined during device setup.

weight: Optional[float]

To be determined. Probably weight of object to which tracker is attached.

class gps_tracker.client.datatypes.TrackerData(datetime: Optional[str], lat, lng, method, pkt_drop, precision, uuid)

Bases: object

Definition of tracker location data.

datetime: datetime.datetime

Datetime of location measurement.

lat: float

Device latitude.

lng: float

Device longitude.

method: gps_tracker.client.datatypes.TrackerMethod

Method used for location acquisition.

pkt_drop: int

To be determined. (Probably number of packet drop since last location).

precision: int

Precision of location measurement (To be confirmed).

uuid: uuid.UUID

Universally unique identifier of location data.

class gps_tracker.client.datatypes.TrackerIcon(value)

Bases: enum.Enum

Enumeration of tracker icons.

ANIMAL = 37

ANTENNA = 43

BACKHOE_LOADER = 36

BACKPACK = 5

BEEHIVE = 41

BIKE = 7

BOAT = 8

BRIEFCASE = 2

CAR = 10

CARAVAN = 12

CARPARK = 42

CART = 13

CAT = 31

DOG = 30

EBIKE = 40

GIRL = 34

HANDBAG = 1

HEALTH = 44

HELICOPTER = 18

KAYAK = 15

KEYS = 46

LAPTOP = 16

MAN = 39

MOTO = 17

OTHER = 0

PERSON = 32

PHONE = 48

PLANE = 19

SCOOTER = 21

SUITCASE = 3

TENT = 23

TRACTOR = 26

TRUCK = 24

TV = 47

WOMAN = 38

class gps_tracker.client.datatypes.TrackerMethod(value)

Bases: enum.Enum

Enumeration of tracking methods.

BLE_NEIGHBOR = 13

BSSID = 3

BSSID2 = 9

BSSID3 = 10

BSSID4 = 11

BSSID_TGU = 7

FLEET_CORRECTION = 12

GPS = 2

GPS_BLE = 14

NETWORK = 1

PHONE = 6

PHONE2 = 15

PLACE = 4

SERVER = 8

UBISCALE = 5

UNKNOWN = 0

class gps_tracker.client.datatypes.TrackerMode(value)

Bases: enum.Enum

Enumeration of possible tracker modes.

AIRPLANE = 6

CHILD = 3

CHILD_PET = 23

DAILY = 1

DAILY_PET = 21

INTENSE = 2

INTENSE_PET = 22

KEEP_ALIVE = 4

LOST = 7

LOST_PET = 27

LOST_PET_DEBUG = 24

LWT3 = 235

VEHICLE_S1 = 8

VEHICLE_S2 = 9

VEHICLE_S3 = 10

class gps_tracker.client.datatypes.TrackerStatus(battery, begin_date: Optional[str], network_operator, state, stationary, sub_end_date, sub_state, last_event: Optional[str] = None, last_location: Optional[str] = None)

Bases: object

Definition of tracker status data.

battery: int

begin_date: datetime.datetime

last_event: Optional[datetime.datetime]

last_location: Optional[datetime.datetime]

network_operator: str

state: str

stationary: int

sub_end_date: str

sub_state: str

class gps_tracker.client.datatypes.TrackerUsage(value)

Bases: enum.Enum

Enumeration of possible tracker usages.

BIKE = 'bike'

CAT = 'cat'

CHILD = 'child'

DOG = 'dog'

MOTO = 'moto'

OTHER = 'other'

PERSON = 'person'

PET = 'pet'

TOOL = 'tool'

UND = ''

VEHICLE = 'vehicle'

class gps_tracker.client.datatypes.User(id, username, profiles)

Bases: object

User definition as returned by Invoxia API.

id: int

User unique identifier.

profiles: List[int]

List of profile ids associated to user.

username: str

User name.

gps_tracker.client.exceptions module

Definition of exceptions possibly raised by the Client.

exception gps_tracker.client.exceptions.ForbiddenQuery(msg: Optional[str] = None, json_answer: Optional[Union[Dict, List]] = None)

Bases: gps_tracker.client.exceptions.HttpException

Exception raised when an API query is forbidden with current credentials.

message() → Optional[str]

Define message for forbidden queries.

exception gps_tracker.client.exceptions.HttpException(msg: Optional[str] = None, json_answer: Optional[Union[Dict, List]] = None)

Bases: Exception

Base class for HTTP exceptions.

static get(code: int) → Optional[Type[gps_tracker.client.exceptions.HttpException]]

Return the subclass associated to code if it exists.

Parameters

code (int) – HTTP code returned by the API call

Returns

SubClass of HttpException with correct code if it exists

Return type

Type[HttpException]

message() → Optional[str]

Define a specific message for the subclass

exception gps_tracker.client.exceptions.NoContentQuery(msg: Optional[str] = None, json_answer: Optional[Union[Dict, List]] = None)

Bases: gps_tracker.client.exceptions.HttpException

Exception raised when API has no content to return.

message() → Optional[str]

Define message for no-content queries.

exception gps_tracker.client.exceptions.UnauthorizedQuery(msg: Optional[str] = None, json_answer: Optional[Union[Dict, List]] = None)

Bases: gps_tracker.client.exceptions.HttpException

Exception raised if credentials are incorrect.

message() → Optional[str]

Return the “detail” message if provided by the API.

exception gps_tracker.client.exceptions.UnknownDeviceType(device_data: Dict[str, Any])

Bases: Exception

Exception raised when a device of unknown type is found.

gps_tracker.client.synchronous module

Synchronous client for Invoxia API.

class gps_tracker.client.synchronous.Client(config: Config)

Bases: object

Synchronous client for Invoxia API.

get_device(device_id: int) → gps_tracker.client.datatypes.Device

Return a device referenced by its id.

Parameters

device_id (int) – Unique identifier of a device

Returns

Device instance of given id

Return type

Device

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – Device of given ID is not linked to current account

• requests.HTTPError – Unexpected HTTP error during API call

get_devices(kind: Optional[str] = None) → List[gps_tracker.client.datatypes.Device]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters

kind (str, optional) – kind of devices to retrieve

Returns

List of retrieved devices

Return type

List[Device]

Raises

• UnauthorizedQuery – Credentials are invalid

• requests.HTTPError – Unexpected HTTP error during API call

• KeyError – Undefined kind requested

get_locations(device: gps_tracker.client.datatypes.Tracker, not_before: Optional[datetime.datetime] = None, not_after: Optional[datetime.datetime] = None, max_count: int = 20) → List[gps_tracker.client.datatypes.TrackerData]

Extract the list of tracker locations.

Parameters

• device (Tracker) – The tracker instance whose locations must be extracted.

• not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.

• not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.

• max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns

List of extracted locations

Return type

List[TrackerData]

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – provided Device is not linked to current account (should not happen if Device was obtained with get_devices()).

• requests.HTTPError – Unexpected HTTP error during API call

get_tracker_config(device: gps_tracker.client.datatypes.Tracker) → gps_tracker.client.datatypes.TrackerConfig

Get the current configuration of a given tracker.

Parameters

device (Tracker) – The tracker instance whose configuration is queried.

Returns

Current config of the tracker

Return type

TrackerConfig

get_tracker_status(device: gps_tracker.client.datatypes.Tracker) → gps_tracker.client.datatypes.TrackerStatus

Get the current status of a given tracker.

Parameters

device (Tracker) – The tracker instance whose status is queried.

Returns

Current status of the tracker

Return type

TrackerStatus

get_trackers() → List[gps_tracker.client.datatypes.Tracker]

Query API for the list of trackers associated to credentials.

Returns

Tracker devices associated to current account

Return type

List[Tracker]

Raises

• UnauthorizedQuery – Credentials are invalid

• requests.HTTPError – Unexpected HTTP error during API call

get_user(user_id: int) → gps_tracker.client.datatypes.User

Return a user referenced by its id.

Parameters

user_id (int) – ID of the user to retrieve

Returns

User instance associated to given ID

Return type

User

Raises

• UnauthorizedQuery – Credentials are invalid

• ForbiddenQuery – User of given ID is not linked to current account

• requests.HTTPError – Unexpected HTTP error during API call

get_users() → List[gps_tracker.client.datatypes.User]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns

List of User instances associated to account

Return type

List[User]

Raises

• UnauthorizedQuery – Credentials are invalid

• requests.HTTPError – Unexpected HTTP error during API call

gps_tracker.client.url_provider module

URL provider for specific Invoxia API queries.

class gps_tracker.client.url_provider.UrlProvider(api_url: str = 'https://labs.invoxia.io')

Bases: object

URL provider generates the API urls used to access user data.

device(device_id: int) → str

Form the URL to access a specific device by its id.

Parameters

device_id (int) – device unique identifier

Returns

API URL

Return type

str

devices(kind: Optional[str] = None) → str

Form the URL to access all devices associated with current credentials.

Parameters

kind (str, optional) – Kind of device to list (tracker, android, iphone)

Returns

API URL

Return type

str

locations(device_id: int, not_before: Optional[int] = None, not_after: Optional[int] = None) → str

Form the URL to access tracker locations in a given time-range.

Parameters

• device_id (int) – tracker device unique identifier

• not_before (int, optional) – timestamp of the minimum datetime to consider

• not_after (int, optional) – timestamp of the maximum datetime to consider

Returns

API URL

Return type

str

tracker_config(device_id: int) → str

Form the URL to get the current tracker config.

tracker_status(device_id: int) → str

Form the URL to get the current tracker status.

user(user_id: int) → str

Form the URL to access a specific user by its id.

Parameters

user_id (int) – user unique identifier

Returns

API URL

Return type

str

users() → str

Form the URL to access list of users associated with credentials.

Returns

API URL

Return type

str

Module contents

Definitions of subpackage gps_tracker.client.