Vehicle Simulator
Learn about what to expect from Vehicle Simulator and how it compares to Live mode.
Vehicle Simulator allows you to test your application in realistic scenarios with a simulated Smartcar-compatible vehicle. Simulator responds to API requests just like a real vehicle. You can choose a simulated trip for your vehicle to take, and track it over time.
You can use the simulator for initial testing before you have a real vehicle to connect, or as part of an end-to-end testing suite.
Creating a Simulated Vehicle
Simulated vehicles are managed in the Smartcar Dashboard.
Select “Add a vehicle” and select a vehicle by Make, Model, and Year, or provide a VIN for a US-based vehicle that you want to simulate. You’ll be able to preview the API endpoints that are supported for the vehicle model you select.
Once you create your simulated vehicle, you’ll select a simulated trip profile that the vehicle will follow. This profile can run automatically over time, or you can manually select a stage of the trip for the vehicle in the Dashboard.
Connecting a Simulated Vehicle
Simulated vehicles generate a special set of credentials that mimic what a real-world vehicle owner would have. You’ll use these credentials to establish a vehicle connection through the same Smartcar Connect flow that you will use for live vehicles.
In order for Connect to know you’re using credentials generated from Vehicle Simulator, you’ll need to pass mode=simulated in the Connect URL.
Please ensure you’re passing or changing the country flag for Connect based on the region you’ve created your vehicle for. Failure to do so will result in an invalid credential error on login. You can read more about country selection for Connect here.
Making requests to a Simulated Vehicle
Once your simulated vehicle is connected, you can make API requests to it just as you would a real vehicle.
Supported endpoints for the simulated vehicle will send responses with simulated data - unsupported endpoints will return errors just as they would with a real vehicle.
You can also send commands to simulated vehicles, like start/stop charge or lock/unlock doors. These requests will send responses that mimic that of a real vehicle, but the vehicle state will continue to reflect the simulated trip that was selected.
Expected Responses
Data
| Permission | Request Method / Path | Example Response |
|---|---|---|
read_engine_oil | GET /engine/oil | { lifeRemaining: 0.35 } |
read_battery | GET /battery | { percentRemaining: 0.3, range: 40.5 } |
read_battery | GET /battery/capacity | { capacity: 28 } |
read_charge | GET /charge | { isPluggedIn: true, state: 'FULLY_CHARGED' } |
read_charge | GET /charge/limit | { limit: 1 } |
read_fuel | GET /fuel | { amountRemaining: 53.2, percentRemaining: 0.3, range: 40.5 } |
read_location | GET /location | { latitude: 37.4292, longitude: 122.1382 } |
read_odometer | GET /odometer | { distance: 104.32 } |
read_tires | GET /tires/pressure | { backLeft: 219.3, backRight: 219.3, frontLeft: 219.3, frontRight: 219.3 } |
read_vehicle_info | GET / | { id: 36ab27d0-fd9d-4455-823a-ce30af709ffc, make: "TESLA", model: "Model S", year: 2014 } |
read_vin | GET /vin | { vin: 1234A67Q90F2T4567 } |
Commands
Below are the various action requests that can be made to simulated vehicles, and what responses to expect based on the simulated vehicle’s current state or simulator support.
Not listed here are the standard API errors that will be returned if the vehicle does not support the capability or the application has not been granted permission.
| Permission | Request (method / path) | Action request | Vehicle state | Response |
|---|---|---|---|---|
control_security | POST /security | LOCK | Parked / Charging | { status: "success" } |
control_security | POST /security | UNLOCK | Parked / Charging | { status: "success" } |
control_security | POST /security | LOCK | Driving | { type: VEHICLE_STATE, code: IN_MOTION } |
control_security | POST /security | UNLOCK | Driving | { type: VEHICLE_STATE, code: IN_MOTION } |
control_charge | POST /charge | START | Charging | { status: "success" } |
control_charge | POST /charge | STOP | Charging | { status: "success" } |
control_charge | POST /charge | STOP | Parked / Driving (not plugged in) | { type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED } |
control_charge | POST /charge | START | Parked / Driving (not plugged in) | { type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED } |
control_charge | POST /charge-limit | <limit> | Charging | { "type": "COMPATIBILITY", "code": "SMARTCAR_NOT_CAPABLE", } |
control_charge | POST /charge-limit | <limit> | Parked / Driving (not plugged in) | { type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED } |
Errors
| Event | Error response | Suggested resolution |
|---|---|---|
| Making an API request to a simulated vehicle before connecting the vehicle to your application via Smartcar Connect | { type: "PERMISSION", statusCode: 403, resolution: "REAUTHENTICATE" } | Locate the ‘Connect Credentials’ button at the top of the simulation screen in the Smartcar Dashboard for your simulated vehicle. There you will find the credentials necessary to connect the vehicle to your application as well as instructions for doing so through Smartcar Connect. |
| Making an API request to a simulated vehicle before a simulation has been started on Dashboard | { type: "CONNECTED_SERVICES_ACCOUNT", code: "ACCOUNT_ISSUE", statusCode: 400 } | Open the Simulator tab in the Smartcar Dashboard and navigate to your target vehicle. If you haven’t yet selected a vehicle state, do so now, and then start the simulation using the ‘Play’ button on the simulation screen. |
| Making an API request to a simulated vehicle that is not associated with your application | { type: "CONNECTED_SERVICES_ACCOUNT", code: "VEHICLE_MISSING", statusCode: 400 } | Ensure the simulated vehicle you are making requests to has been created in the Simulator within your Smartcar Dashboard. |
Mode Comparison
| Feature | Simulator | Live | |
|---|---|---|---|
| Single Select | ✅ | ✅ | |
| Brand Select | ✅ | ✅ | |
| Compatibility API* | ✅ | ✅ | |
control_security | ✅ | ✅ | |
control_charge | ✅ | ✅ | |
| Make-Specific Endpoints | ❌ | ✅ | |
| Scheduled Webhooks | ❌ | ✅ | |
| Event Based Webhooks** | ❌ | ✅ |
*When a real VIN is used either through VIN@smartcar for test mode, or generating a simulated vehicle with a real VIN.
0SC and 1SC prefixed VINs will not work.
**For supported brands - Toyota, Ford and Tesla.