Introduction
The sandbox environment serves as a secure, isolated testing ground that mimics your production environment. It allows you to simulate interactions with automotive OEMs, energy device manufacturers, and other entities without affecting live data.Base URL
The base URL for the sandbox environment is https://api.sandbox.volteras.com.Key Features
- Isolated testing: the sandbox is entirely separate from the production environment, ensuring that your tests won’t interfere with live data.
- Consent flow: connect vehicles via a consent flow — any credentials are accepted in the sandbox environment.
- VIN connection: connect vehicles by providing a VIN, make, and country via the Connect Vehicles API endpoint. Connected vehicles receive the same simulated data as consent flow vehicles.
- Realistic vehicle data: sandbox vehicles receive a full suite of simulated telemetry — including location, speed, odometer, state of charge, charging status, tire pressure, climate, and more — modelled on real vehicle behavior. As vehicles move, their telemetry updates realistically: location changes produce corresponding odometer and battery consumption changes, and charging sessions follow realistic power curves.
- Live updates: vehicle data is updated every 60 seconds, published via webhooks and available via the Connect API.
Quick guide
Generate sandbox application
First, navigate to our Volteras Portal and create a new application specifically for the sandbox environment to obtain your
client_id and client_secret.Retrieve token
Utilize the
client_id and client_secret generated for the sandbox to obtain an access token. We adhere to the OAuth 2.0 authorization standard.Test token
Validate the access token by making a request to the test endpoint:
https://api.sandbox.volteras.com/v1/oauth2/test-token. Include the token in the HTTP header as Bearer <access-token>.Connect vehicles
Connect vehicles in one of two ways:
- Consent flow: Generate a new consent flow via the consent flow endpoint. Any credentials are valid to complete the flow in sandbox.
- VIN connection: Connect vehicles directly by providing VIN, make, and country via the Connect Vehicles endpoint.
How sandbox data is generated
Behind the scenes, a large pool of simulated vehicles is continuously generating realistic telemetry. When you connect a vehicle in the sandbox, it is assigned to one of these simulated vehicles, and your vehicle inherits that simulated vehicle’s live data stream. Because the pool is shared, multiple connected vehicles may be assigned to the same simulated vehicle — meaning they could show identical data. This is expected behavior in the sandbox and does not occur in production. The simulated vehicle pool includes vehicles from every supported make, with realistic models and specifications drawn from real-world EVs (2020–2025 model years).Static data
When a vehicle is connected, it is assigned a real EV model and year from the same make. The following fields are set once and remain constant:- Make and model — e.g. Tesla Model 3 Long Range, BMW i4 eDrive40, Hyundai IONIQ 5 Long Range
- Model year — realistic model years (2020–2025)
- Battery capacity — based on the real vehicle’s specs (e.g. 75 kWh for a Tesla Model 3 LR)
- WLTP range — the official rated range for the model (e.g. 580 km)
Location
Simulated vehicles drive continuously around Monaco, following realistic road networks and traffic patterns. The simulation uses real road geometry, so GPS coordinates, altitude, heading, and speed all reflect actual driving dynamics.- Latitude and longitude — GPS coordinates along Monaco’s road network
- Altitude — elevation data from the road network
- Heading — direction of travel (0–360°)
- Speed — instantaneous speed derived from the traffic simulation, varying with road conditions and traffic
Charging and range
Battery state of charge and range evolve realistically as vehicles drive and charge.- State of charge (SOC) — decreases as the vehicle drives (based on speed, acceleration, and vehicle mass) and increases when the vehicle is at a charging station. Initial SOC varies per vehicle (50–95%).
- Battery level (kWh) — derived from SOC and the vehicle’s battery capacity
- Range (km) — estimated remaining range based on current SOC and the vehicle’s WLTP-rated range
- Charging status —
CHARGINGwhen the vehicle is at a charging station,STOPPEDotherwise - Charge port — open and latched when charging, closed otherwise
- Charging power — simulated at 11 kW (AC Level 2) with a 32 A current limit
- Remaining charge time — estimated minutes to reach full charge at the current power level
Odometer
The odometer accumulates continuously as vehicles drive. It represents the total distance driven since the simulated vehicle was created, and increases realistically based on actual distance covered along the road network.Tire pressure
Each vehicle has four tire pressure readings (front left, front right, rear left, rear right) in kPa. Values are deterministic per vehicle — each vehicle gets a consistent baseline pressure with small variations between tires. The readings fluctuate slightly over time to reflect how tire pressure fluctuates in reality.Climate
Climate readings are simulated with stable values:- External temperature — ambient temperature
- Internal temperature — cabin temperature
Ignition
The ignition status reflects whether the vehicle is actively moving:- ON — when the vehicle is driving (speed above threshold)
- OFF — when the vehicle is stationary
Service intervals
Each simulated vehicle has a scheduled service interval with two components:- Next service date — initially set approximately 3 months in the future. When the date becomes one month overdue, it resets to simulate a completed service and schedule the next one.
- Next service odometer — initially set 5,000 km ahead of the current odometer. When the vehicle approaches or passes this threshold, it resets to simulate a completed service.
OEM alerts
A subset of simulated vehicles generate OEM alert codes — diagnostic warnings similar to those reported by real vehicle manufacturers. Vehicles with alerts carry all six of the following codes:| Alert | Component | Severity | Description |
|---|---|---|---|
| Tire pressure alert | Tires | Medium | Tire pressure is below recommended level |
| Brake pad wear | Brakes | Critical | Brake pads are worn and require replacement |
| Washer fluid low | Vehicle | Low | Washer fluid level is low |
| Battery charge low | Battery | Medium | Battery charge level is low |
| Service due | Vehicle | Medium | Scheduled vehicle service is due |
| Brake fluid low | Brakes | High | Brake fluid level is low |
Connecting a vehicle with alerts
By default, vehicles are assigned to a random simulated vehicle matching their make — which may or may not have alerts. To guarantee a vehicle with alerts, use a VIN that starts with the prefixALERT511. For example:
Special VIN prefixes
The sandbox supports several VIN prefixes that trigger specific behaviors for testing error handling and edge cases:| Prefix | Behavior |
|---|---|
ALERT511 | Assigns a simulated vehicle with OEM alerts |
PERR0R11 | Returns a public-facing error — i.e. an error that is surfaced to you, as it involves a fix on your side (such as a software update required in the vehicle) |
1NC0MP11 | Returns an incompatibility error (vehicle is incompatible) |
PR0C11 | Returns a pending/processing status |
Next Steps
- Familiarize yourself with the API Reference for available endpoints in the sandbox environment.
- Review tutorials for complex scenarios and use-cases.