fressnapftracker 0.2.0

Asynchronous Python client for the Fressnapf Tracker GPS API

fressnapftracker

Asynchronous Python client for the Fressnapf Tracker GPS API

Installation

uv add fressnapftracker

Usage

Authentication Flow

If you don't have credentials yet, you can use the authentication flow:

import asyncio

from fressnapftracker import AuthClient


async def main() -> None:
    """Show example of authentication flow."""
    async with AuthClient() as auth:
        # Step 1: Request SMS code
        # Phone number should be in E.164 format (e.g., [phone])
        sms_response = await auth.request_sms_code("[phone]")
        user_id = sms_response.id
        print(f"User ID: {user_id}")

        # Step 2: Verify with SMS code (you'll receive this via SMS)
        sms_code = input("Enter SMS code: ")
        verify_response = await auth.verify_phone_number(user_id, sms_code)
        access_token = verify_response.user_token.access_token
        print(f"Access token: {access_token}")

        # Step 3: Get list of devices
        devices = await auth.get_devices(user_id, access_token)
        for device in devices:
            print(f"Device: {device.serialnumber} - Token: {device.token}")


if __name__ == "__main__":
    asyncio.run(main())

Getting Tracker Data

import asyncio

from fressnapftracker import ApiClient


async def main() -> None:
    """Show example of getting tracker data."""
    async with ApiClient(
        serial_number="<YOUR_SERIAL_NUMBER>",
        device_token="<YOUR_DEVICE_TOKEN>",
    ) as api:
        tracker = await api.get_tracker()
        print(f"Pet name: {tracker.name}")
        print(f"Battery: {tracker.battery}%")
        if tracker.position:
            print(f"Location: {tracker.position.lat}, {tracker.position.lng}")


if __name__ == "__main__":
    asyncio.run(main())

Controlling the Tracker

import asyncio

from fressnapftracker import ApiClient


async def main() -> None:
    """Show example of controlling the tracker."""
    async with ApiClient(
        serial_number="<YOUR_SERIAL_NUMBER>",
        device_token="<YOUR_DEVICE_TOKEN>",
    ) as api:
        # Set LED brightness (0-100)
        await api.set_led_brightness(75)

        # Enable/disable deep sleep mode
        await api.set_deep_sleep(True)


if __name__ == "__main__":
    asyncio.run(main())

API Reference

AuthClient

Client for handling authentication with the Fressnapf Tracker API.

Constructor Parameters

• request_timeout (int, optional): Request timeout in seconds (default: 10)
• client (httpx.AsyncClient, optional): Custom httpx client to use
• user_agent (str, optional): Custom user agent string

Methods

• request_sms_code(phone_number: str, locale: str = "en") -> SmsCodeResponse: Request SMS verification code
• verify_phone_number(user_id: int, sms_code: int) -> PhoneVerificationResponse: Verify phone with code received via SMS
• get_devices(user_id: int, user_access_token: str) -> list[Device]: Get list of devices

ApiClient

Client for interacting with the Fressnapf Tracker device API.

Constructor Parameters

• serial_number (str): The serial number of your tracker device (required)
• device_token (str): The device token for API authentication (required)
• request_timeout (int, optional): Request timeout in seconds (default: 10)
• client (httpx.AsyncClient, optional): Custom httpx client to use
• user_agent (str, optional): Custom user agent string

Methods

• get_tracker() -> Tracker: Get current tracker data
• set_led_brightness(brightness: int): Set LED brightness (0-100)
• set_deep_sleep(enabled: bool): Enable/disable deep sleep mode

Models

Tracker

• name: Pet/device name
• battery: Battery percentage
• charging: Whether the device is charging
• position: Position data (lat, lng, accuracy)
• tracker_settings: Device settings and features
• led_brightness: LED brightness settings
• deep_sleep: Deep sleep settings

Device

• serialnumber: Device serial number
• name: Device name
• device_token: Device token for API calls
• auth_token: Auth token for API calls

Exceptions

• FressnapfTrackerError: Base exception
• FressnapfTrackerConnectionError: Connection/timeout errors
• FressnapfTrackerAuthenticationError: Authentication errors
• FressnapfTrackerInvalidTokenError: Invalid auth token
• FressnapfTrackerInvalidDeviceTokenError: Invalid device token
• FressnapfTrackerInvalidSerialNumberError: Invalid serial number