Tramigo.Client 1.0.0

Tramigo Cloud API Client for .NET

A fully-featured .NET client library for the Tramigo Cloud API, providing easy access to vehicle tracking, fleet management, and device control functionality.

API Version: This client implements the Tramigo Cloud API v1.7 specification.

Features

• OAuth 2.0 Authentication: Secure login/logout with token management
• Device Management: List devices and device groups
• Reports: Get device reports with filtering by date, type, and custom filters
• Location Tracking: Get last known locations for devices
• Odometer (Mileage): Track vehicle mileage with range calculations
• Engine Hours: Monitor engine running time
• Commands: Send commands to devices including immobilizer control
• Dependency Injection: Built-in support for ASP.NET Core DI

Installation

NuGet Package

dotnet add package Tramigo.Client

From Source

git clone https://github.com/DaithiBradley/TramigoAPI.git
cd TramigoAPI
dotnet build

Quick Start

Basic Usage

using Tramigo.Client;

// Create client with default options
using var client = new TramigoClient();

// Or with custom options
var options = new TramigoClientOptions
{
    BaseUrl = "http://api.tracking.tramigocloud.com",
    TimeoutSeconds = 30
};
using var client = new TramigoClient(options);

// Authenticate
var loginResponse = await client.LoginAsync("username", "password");
Console.WriteLine($"Logged in! Token expires in {loginResponse.ExpiresIn} seconds");

// Get devices
var devices = await client.GetDevicesAsync(page: 1, perPage: 100);
foreach (var device in devices.Data)
{
    Console.WriteLine($"Device: {device.Name} (IMEI: {device.Imei})");
}

// Logout when done
await client.LogoutAsync();

ASP.NET Core Dependency Injection

// In Program.cs or Startup.cs
using Tramigo.Client.Extensions;

builder.Services.AddTramigoClient(options =>
{
    options.BaseUrl = "http://api.tracking.tramigocloud.com";
    options.TimeoutSeconds = 30;
});

// Or with HttpClientFactory support
builder.Services.AddTramigoClientWithHttpClientFactory(options =>
{
    options.BaseUrl = "http://api.tracking.tramigocloud.com";
});

// In your service or controller
public class TrackingService
{
    private readonly ITramigoClient _client;

    public TrackingService(ITramigoClient client)
    {
        _client = client;
    }

    public async Task<List<Device>> GetAllDevicesAsync()
    {
        // Login first if not authenticated
        if (!_client.IsAuthenticated)
        {
            await _client.LoginAsync("username", "password");
        }

        var response = await _client.GetDevicesAsync();
        return response.Data;
    }
}

API Reference

Authentication

// Login
var loginResponse = await client.LoginAsync("username", "password");

// Check authentication status
bool isAuthenticated = client.IsAuthenticated;
string? token = client.AccessToken;

// Logout
var logoutResponse = await client.LogoutAsync();

Devices

// Get paginated list of devices
var devices = await client.GetDevicesAsync(page: 1, perPage: 100);

// Get device groups
var groups = await client.GetDeviceGroupsAsync();

Reports

// Get reports for a device
var reports = await client.GetReportsAsync(
    deviceId: 389,
    page: 1,
    perPage: 50
);

// Get reports with date filter
var filteredReports = await client.GetReportsAsync(
    deviceId: 389,
    page: 1,
    perPage: 50,
    startDate: DateTime.UtcNow.AddDays(-7),
    endDate: DateTime.UtcNow
);

// Get reports with report group filter
var tripReports = await client.GetReportsAsync(
    deviceId: 389,
    reportGroup: ReportGroup.Trips
);

// Get reports with custom type filter
var customReports = await client.GetReportsAsync(
    deviceId: 389,
    reportGroup: ReportGroup.CustomFilter,
    reportTypes: new[] { ReportType.IgnitionOn, ReportType.IgnitionOff, ReportType.Moving }
);

// Get last report for a device
var lastReport = await client.GetLastReportAsync(deviceId: 389);

// Get last reports for multiple devices
var lastReports = await client.GetLastReportsAsync(new[] { 389, 10, 454 });

// Get last location for a device
var lastLocation = await client.GetLastLocationAsync(deviceId: 389);

// Get last locations for multiple devices
var lastLocations = await client.GetLastLocationsAsync(new[] { 389, 10, 454 });

Available Report Types

Odometer (Mileage)

// Get last odometer readings for all devices
var lastOdometer = await client.GetLastOdometerAsync(page: 1, perPage: 100);

// Get odometer range for all devices
var odometerRange = await client.GetOdometerRangeAsync(
    startDate: DateTime.UtcNow.AddDays(-30),
    endDate: DateTime.UtcNow
);

// Get odometer for a specific device
var deviceOdometer = await client.GetDeviceOdometerAsync(
    deviceId: 7485,
    startDate: DateTime.UtcNow.AddDays(-7),
    endDate: DateTime.UtcNow,
    order: "asc"
);

Engine Hours

// Get last engine hours for all devices
var lastEngineHours = await client.GetLastEngineHoursAsync(page: 1, perPage: 100);

// Get engine hours range for all devices
var engineHoursRange = await client.GetEngineHourRangeAsync(
    startDate: DateTime.UtcNow.AddDays(-30),
    endDate: DateTime.UtcNow
);

// Get engine hours for a specific device
var deviceEngineHours = await client.GetDeviceEngineHoursAsync(
    deviceId: 7485,
    startDate: DateTime.UtcNow.AddDays(-7),
    endDate: DateTime.UtcNow,
    order: "asc"
);

Commands

// Send a command to a device
var response = await client.SendCommandAsync(
    deviceId: 577,
    message: "find"
);

// Send commands to multiple devices
var responses = await client.SendCommandsAsync(new[]
{
    new CommandRequest { DeviceId = 577, Message = "find" },
    new CommandRequest { DeviceId = 578, Message = "status" }
});

// Activate immobilizer
var activateResponse = await client.ImmobilizeAsync(deviceId: 577, activate: true);

// Deactivate immobilizer
var deactivateResponse = await client.ImmobilizeAsync(deviceId: 577, activate: false);

Error Handling

The client throws specific exceptions for different error scenarios:

using Tramigo.Client.Exceptions;

try
{
    await client.LoginAsync("user", "pass");
}
catch (TramigoAuthenticationException ex)
{
    // Authentication failed (invalid credentials, expired token, etc.)
    Console.WriteLine($"Auth error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
}
catch (TramigoApiException ex)
{
    // Other API errors
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
    Console.WriteLine($"Response: {ex.ResponseContent}");
}

Configuration Options

Project Structure

TramigoAPI/
├── Tramigo.Client/                    # Main client library
│   ├── Models/
│   │   ├── Authentication/            # Login/Logout models
│   │   ├── Commands/                  # Command request/response models
│   │   ├── Common/                    # Shared models (PagedResponse)
│   │   ├── Config/                    # API configuration models
│   │   ├── Devices/                   # Device and DeviceGroup models
│   │   ├── EngineHours/               # Engine hours models
│   │   ├── Odometer/                  # Odometer models
│   │   └── Reports/                   # Report models and enums
│   ├── Exceptions/                    # Custom exceptions
│   ├── Extensions/                    # DI extensions
│   ├── ITramigoClient.cs              # Client interface
│   ├── TramigoClient.cs               # Client implementation
│   └── TramigoClientOptions.cs        # Configuration options
├── Tramigo.Client.Tests/              # Unit tests (165 tests)
├── Tramigo.Examples/                  # Example console application
├── TramigoAPI.sln
└── README.md

Running Tests

cd TramigoAPI
dotnet test

Running Examples

cd TramigoAPI
dotnet run --project Tramigo.Examples

The example application demonstrates all API endpoints with sample data. Update the credentials in Program.cs to use your actual Tramigo Cloud account.

API Documentation

This client is based on the official Tramigo Cloud API Documentation v1.7. For the full API specification, contact Tramigo Ltd.

Requirements

• .NET 8.0 or later
• Valid Tramigo Cloud account credentials

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.