API Reference

IMyToyotaClient Interface

Configuration Methods

All configuration methods return IMyToyotaClient for method chaining (fluent API).

UseCredentials

IMyToyotaClient UseCredentials(string username, string password)

Sets the MyToyota username and password for authentication.

Parameters:

username - Your MyToyota username
password - Your MyToyota password

Example:

client.UseCredentials("myemail@example.com", "mypassword");

UseLogger

IMyToyotaClient UseLogger(Action<string> logger)

Provides a custom logging function for debugging and monitoring.

Parameters:

logger - Action to receive log messages

Example:

client.UseLogger(msg => Console.WriteLine($"[Toyota] {msg}"));

UseTimeout

IMyToyotaClient UseTimeout(int timeoutSeconds)

Sets the request timeout in seconds.

Parameters:

timeoutSeconds - Timeout duration in seconds

Example:

client.UseTimeout(60);  // 60 second timeout

UseTokenCaching

IMyToyotaClient UseTokenCaching(bool useTokenCaching)

Enables or disables token caching to avoid repeated login calls.

Parameters:

useTokenCaching - True to enable caching, false to disable

Example:

client.UseTokenCaching(true);

UseTokenCacheFilename

IMyToyotaClient UseTokenCacheFilename(string tokenCacheFilename)

Sets the file path for token caching. Only relevant if UseTokenCaching(true).

Parameters:

tokenCacheFilename - File path for storing cached tokens

Example:

client.UseTokenCacheFilename("~/.cache/toyota_tokens.json");

Authentication

LoginAsync

Task<bool> LoginAsync(CancellationToken cancellationToken = default)

Authenticates with the MyToyota API using configured credentials.

Returns: true if successful, false otherwise

Throws: ArgumentException if credentials not configured

Example:

var success = await client.LoginAsync();
if (!success)
    throw new InvalidOperationException("Failed to authenticate");

Vehicle Information

GetVehiclesAsync

Task<VehiclesModel?> GetVehiclesAsync(CancellationToken cancellationToken = default)

Retrieves all vehicles associated with the authenticated user.

Returns: VehiclesModel containing list of vehicles, or null on error

Example:

var vehicles = await client.GetVehiclesAsync();
foreach (var vehicle in vehicles?.Data ?? [])
{
    Console.WriteLine($"VIN: {vehicle.Vin}, Name: {vehicle.Nickname}");
}

Electric/EV Status

GetElectricAsync

Task<ElectricResponseModel?> GetElectricAsync(string vin, CancellationToken cancellationToken = default)

Retrieves EV battery and charging information.

Parameters:

vin - Vehicle Identification Number

Returns: ElectricResponseModel with battery and charging status

Example:

var electric = await client.GetElectricAsync("JTHJP5C27D5012345");
Console.WriteLine($"Battery: {electric?.Data?.BatteryLevel}%");
Console.WriteLine($"Charging: {electric?.Data?.IsCharging}");

GetElectricRealtimeStatusAsync

Task<RealtimeStatus?> GetElectricRealtimeStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves real-time EV status data.

Parameters:

vin - Vehicle Identification Number

Returns: RealtimeStatus with real-time data

Example:

var status = await client.GetElectricRealtimeStatusAsync(vin);

Location & Lock Status

GetLocationAsync

Task<LocationResponseModel?> GetLocationAsync(string vin, CancellationToken cancellationToken = default)

Retrieves the current GPS location of the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: LocationResponseModel with latitude and longitude

Example:

var location = await client.GetLocationAsync(vin);
Console.WriteLine($"Location: {location?.Data?.Latitude}, {location?.Data?.Longitude}");

GetLockStatusAsync

Task<LockStatusResponseModel?> GetLockStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves the lock status of all doors, trunk, and windows.

Parameters:

vin - Vehicle Identification Number

Returns: LockStatusResponseModel with lock statuses

Example:

var lockStatus = await client.GetLockStatusAsync(vin);
Console.WriteLine($"Driver Door: {lockStatus?.Data?.DriverDoor}");
Console.WriteLine($"Trunk: {lockStatus?.Data?.Trunk}");

Climate Control

GetClimateSettingsAsync

Task<ClimateSettingsResponseModel?> GetClimateSettingsAsync(string vin, CancellationToken cancellationToken = default)

Retrieves the current climate control settings configured on the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: ClimateSettingsResponseModel with climate settings

Example:

var settings = await client.GetClimateSettingsAsync(vin);
Console.WriteLine($"Temperature: {settings?.Data?.Temperature}°C");

GetClimateStatusAsync

Task<ClimateStatusResponseModel?> GetClimateStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves the current climate control status (running/stopped, cabin temperature).

Parameters:

vin - Vehicle Identification Number

Returns: ClimateStatusResponseModel with current status

Example:

var status = await client.GetClimateStatusAsync(vin);
Console.WriteLine($"Climate Running: {status?.Data?.IsRunning}");
Console.WriteLine($"Cabin Temp: {status?.Data?.CabinTemperature}°C");

StartClimateControlAsync

Task<ClimateControlResponseModel?> StartClimateControlAsync(string vin, CancellationToken cancellationToken = default)

Sends a command to start climate control on the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: ClimateControlResponseModel with operation result

Throws: OperationNotSupportedException if vehicle doesn't support this

Example:

var result = await client.StartClimateControlAsync(vin);

With explicit settings (POST /v2/remote/climate-control):

Task<ClimateControlResponseModel?> StartClimateControlAsync(string vin, ClimateControlSettings settings, CancellationToken cancellationToken = default)

Only the settings you set are sent; null members are omitted and the car falls back to its saved values.

await client.StartClimateControlAsync(vin, new ClimateControlSettings
{
    temperature = 21.5,
    temperatureUnit = "C",
    heatingOptions = new ClimateHeatingOptions
    {
        frontDefroster = "on",
        steeringHeater = "on"
    },
    seatOptions = new ClimateSeatOptions { driverSeat = "high" },
    duration = 30
});

StopClimateControlAsync

Task<ClimateControlResponseModel?> StopClimateControlAsync(string vin, CancellationToken cancellationToken = default)

Sends a command to stop climate control on the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: ClimateControlResponseModel with operation result

Example:

var result = await client.StopClimateControlAsync(vin);

RefreshClimateStatusAsync

Task<ClimateControlResponseModel?> RefreshClimateStatusAsync(string vin, CancellationToken cancellationToken = default)

Triggers a fresh climate status request from the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: ClimateControlResponseModel with updated status

Example:

var status = await client.RefreshClimateStatusAsync(vin);

Remote Commands

SendRemoteCommandAsync

Task<RemoteCommandResponseModel?> SendRemoteCommandAsync(string vin, RemoteCommandType command, CancellationToken cancellationToken = default)

Sends a remote command to the vehicle (lock, unlock, engine start/stop, etc.).

Parameters:

vin - Vehicle Identification Number
command - The command to execute (see RemoteCommandType enum)

Returns: RemoteCommandResponseModel with operation result

Supported Commands:

Lock - Lock the vehicle
Unlock - Unlock the vehicle
EngineStart - Start the engine
EngineStop - Stop the engine
HazardLights - Toggle hazard lights
Headlights - Control headlights
Trunk - Open/close trunk

Example:

var result = await client.SendRemoteCommandAsync(vin, RemoteCommandType.Lock);
if (result?.IsSuccess == true)
    Console.WriteLine("Vehicle locked");

Note: Check RemoteServiceCapabilities on the vehicle to verify support before calling.

GetRemoteStatusAsync

Task<RemoteStatusResponseModel?> GetRemoteStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves the current vehicle status (GET /v1/vehicle/status). Toyota migrated this read from the retired /v1/global/remote/status route mid-2026; the payload is now directly typed (per-component door/window lock & open states) and no longer carries location/telemetry.

Parameters:

vin - Vehicle Identification Number

Returns: RemoteStatusResponseModel with per-component lock/open state

Example:

var status = await client.GetRemoteStatusAsync(vin);

RefreshRemoteStatusAsync

Task<RemoteStatusRefreshResponseModel?> RefreshRemoteStatusAsync(string vin, CancellationToken cancellationToken = default)

"Wakes" the vehicle (POST /v1/remote/status, VIN header, empty body) so the gateway populates its cache before a status read. Mirrors the official MyT app and improves the success rate of GetRemoteStatusAsync. Waking uses the car's 12V battery — use sparingly.

Example:

var wake = await client.RefreshRemoteStatusAsync(vin);
if (wake?.payload?.returnCode == "000000")
    Console.WriteLine("Vehicle status refreshed");
var status = await client.GetRemoteStatusAsync(vin);

Vehicle Status & Diagnostics

GetHealthStatusAsync

Task<HealthStatusResponseModel?> GetHealthStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves vehicle health diagnostics information.

Parameters:

vin - Vehicle Identification Number

Returns: HealthStatusResponseModel with health status

Example:

var health = await client.GetHealthStatusAsync(vin);

GetTelemetryStatusAsync

Task<TelemetryStatusResponseModel?> GetTelemetryStatusAsync(string vin, CancellationToken cancellationToken = default)

Retrieves vehicle telemetry data.

Parameters:

vin - Vehicle Identification Number

Returns: TelemetryStatusResponseModel with telemetry data

Example:

var telemetry = await client.GetTelemetryStatusAsync(vin);

Trip & Service History

GetTripsAsync

Task<TripsResponseModel?> GetTripsAsync(string vin, DateOnly from, DateOnly to, TripQueryOptions? options = null, CancellationToken cancellationToken = default)

Retrieves trip history for the vehicle within a date range.

Parameters:

vin - Vehicle Identification Number
from - Start date for trip history
to - End date for trip history
options - Optional TripQueryOptions:
- Route - Include detailed route data (default: false)
- Summary - Include trip summary (default: true)
- Limit - Maximum number of trips to return (default: 50)
- Offset - Pagination offset (default: 0)
cancellationToken - Cancellation token

Returns: TripsResponseModel with trip data

Example:

var trips = await client.GetTripsAsync(
    vin,
    from: DateOnly.FromDateTime(DateTime.Now.AddDays(-7)),
    to: DateOnly.FromDateTime(DateTime.Now),
    options: new TripQueryOptions { Route = true, Limit = 100 }
);

foreach (var trip in trips?.Data ?? [])
{
    Console.WriteLine($"Trip: {trip.StartTime} - {trip.Distance}km");
}

GetServiceHistoryAsync

Task<ServiceHistoryResponseModel?> GetServiceHistoryAsync(string vin, CancellationToken cancellationToken = default)

Retrieves service and maintenance records for the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: ServiceHistoryResponseModel with service records

Example:

var history = await client.GetServiceHistoryAsync(vin);

Notifications

GetNotificationsAsync

Task<NotificationsResponseModel?> GetNotificationsAsync(string vin, CancellationToken cancellationToken = default)

Retrieves recent notifications for the vehicle.

Parameters:

vin - Vehicle Identification Number

Returns: NotificationsResponseModel with notifications

Example:

var notifications = await client.GetNotificationsAsync(vin);

Charging Commands

SendChargingCommandAsync

Task<ElectricCommandResponseModel?> SendChargingCommandAsync(
    string vin,
    ElectricChargeCommandType command,
    ReservationCharge? reservationCharge = null,
    CancellationToken cancellationToken = default)

Sends a charging command via POST /v1/global/remote/electric/command.

Commands:

ChargeNow — start charging immediately
ReserveCharge / SetChargingTime — schedule a charging window using reservationCharge

Returns: ElectricCommandResponseModel — payload.returnCode == "000000" means accepted.

Example:

await client.SendChargingCommandAsync(vin, ElectricChargeCommandType.ChargeNow);

await client.SendChargingCommandAsync(
    vin,
    ElectricChargeCommandType.SetChargingTime,
    new ReservationCharge
    {
        chargeType = "startOnly",
        day = "THURSDAY",
        startTime = new ChargeTime { hour = 21, minute = 0 }
    });

Battery & Location Monitor

MonitorDrivingTelemetryAsync

Task MonitorDrivingTelemetryAsync(
    string vin,
    Func<DrivingTelemetrySnapshot, Task> onUpdate,
    DrivingTelemetryOptions? options = null,
    CancellationToken cancellationToken = default)

Periodically reports the battery SOC/range the car reports plus its current geo location, with an adaptive cadence based on the derived vehicle mode:

Driving — frequent polling (default 30s) and an optional remote wake (WakeVehicleWhileDriving).
Charging — moderate polling (default 2 min), no wake.
Parked — minimal polling (default 10 min). Reads cached gateway data only and never wakes the vehicle, so the 12V battery is not drained while the car isn't on a charger.

Movement is detected by comparing consecutive odometer readings; the loop runs until the token is cancelled.

Example:

using var cts = new CancellationTokenSource();
var monitor = Task.Run(() => client.MonitorDrivingTelemetryAsync(
    vin,
    async report =>
    {
        Console.WriteLine(
            $"[{report.Mode}] SOC {report.BatteryLevelPercent}% | range {report.Range?.value} {report.Range?.unit} | " +
            $"{report.Location?.latitude},{report.Location?.longitude}");
    },
    new DrivingTelemetryOptions { PollingIntervalWhileParked = TimeSpan.FromMinutes(5) },
    cts.Token));

// Later: cts.Cancel(); await monitor; // stops the monitor cleanly

Exceptions

The library throws specific exceptions for different scenarios:

AuthenticationException - Login or token validation failed
ApiException - API returned an error or unexpected response
OperationCanceledException - Operation was cancelled via CancellationToken
TimeoutException - Operation exceeded configured timeout
OperationNotSupportedException - Vehicle doesn't support the requested operation
ArgumentException - Invalid arguments provided
ArgumentNullException - Required argument is null

Response Models

All API methods return model classes or null on error. Response models follow this pattern:

public class ResponseModel<T>
{
    public T? Data { get; set; }
    public bool IsSuccess { get; set; }
    public string? ErrorMessage { get; set; }
    public DateTime Timestamp { get; set; }
}

Always check for null or IsSuccess before accessing Data.

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

API Reference

IMyToyotaClient Interface

Configuration Methods

UseCredentials

UseLogger

UseTimeout

UseTokenCaching

UseTokenCacheFilename

Authentication

LoginAsync

Vehicle Information

GetVehiclesAsync

Electric/EV Status

GetElectricAsync

GetElectricRealtimeStatusAsync

Location & Lock Status

GetLocationAsync

GetLockStatusAsync

Climate Control

GetClimateSettingsAsync

GetClimateStatusAsync

StartClimateControlAsync

StopClimateControlAsync

RefreshClimateStatusAsync

Remote Commands

SendRemoteCommandAsync

GetRemoteStatusAsync

RefreshRemoteStatusAsync

Vehicle Status & Diagnostics

GetHealthStatusAsync

GetTelemetryStatusAsync

Trip & Service History

GetTripsAsync

GetServiceHistoryAsync

Notifications

GetNotificationsAsync

Charging Commands

SendChargingCommandAsync

Battery & Location Monitor

MonitorDrivingTelemetryAsync

Exceptions

Response Models