Introduction

Welcome to Smartcar! Below you'll find everything you need to get started with Smartcar. If you have any questions, please let us know!.

Smartcar makes it easy to read vehicle data and send commands to vehicles of any brand using HTTP requests. The Smartcar API is organized around REST. We use built-in HTTP features like HTTP verbs and HTTP authentication so you can use any HTTP client. All responses are returned in standard JSON and are documented in our API Reference.

All requests made to our API require an access token. Our API uses the OAuth2 authorization framework and provides a granular permissioning system that authorizes API endpoints based on vehicle owner preferences. This allows applications to easily authorize and interact with vehicles through the Smartcar API.

We're giving access to the Smartcar API on a rolling basis. Please request access and we'll be in touch to help you get set up!

Authentication

Smartcar uses the OAuth2 authorization framework. This allows applications to authorize and interact with vehicles using the Smartcar API.

Register

To get started, request access to our platform. Next, register your application with Smartcar by navigating to our developer dashboard.

After registration, your application will be assigned a client id and a client secret. The client secret must be kept safe and used only in exchanges between your application's server and Smartcar's authorization server (https://auth.smartcar.com).

When registering you will also be asked to provide one or more redirect URIs. This is a url located on your application's server which will be redirected to upon completion of the authorization flow.

Request Authorization

A vehicle owner must first grant your application the necessary permissions to interact with their vehicle. The authorization steps are as follows:

  1. Redirect to Smartcar - Your application directs a vehicle owner to the Smartcar authentication dialog.

  2. Smartcar Prompts for Consent - Smartcar prompts the vehicle owner to log in with their credentials. Once logged in, the user will be asked to grant your application access to the specific scope of permissions requested. The user can choose to either "Allow" or "Deny".

  3. Handle Smartcar Response - Smartcar responds with the authorization code (or an error message if the user chose "Deny"), redirecting the response back to your application using the redirect_uri.

1. Redirect to Smartcar

When your application needs access to a user's vehicles, redirect them to Smartcar's authentication dialog.

The Smartcar authentication dialog redirect requires query parameters to identify your application and the requested permissions:

Parameter Required Description
client_id true The application's unique identifier. This is available on the Apps tab of the dashboard.
redirect_uri true The URI a user will be redirected to after authorization. This value must match one of the redirect URIs set in the Apps tab of the dashboard.
response_type true This value must be set to code . OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Authorization Code' flow.
scope true A space separated list of permissions your application is requesting access to. The valid permission names are found in the API Reference .
state false An optional value included as a query parameter in the redirect_uri back to your application. This value is often used to identify a user and/or prevent cross-site request forgery.

Your application should generate a redirect URL similar to this one:

https://<make>.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info
&redirect_uri=https://example.com/home
&state=0facda3319

Note: <make> should be replaced by the vehicle make (e.g. tesla, bmw or mock).

For testing, set the make to mock to make API requests on a simulated vehicle: https://mock.smartcar.com/oauth/authorize. When logging into a mock vehicle, use any .com email address (anything@anything.com) with any password.

In this step, the vehicle owner decides whether to grant your application the requested access. Smartcar will display a consent window that shows the name of your application and the list of permissions your application needs to access. The vehicle owner can approve or deny your application's requested access.

The vehicle owner's approval or denial is sent back to your application server via the redirect URL you specified.

3. Handle Smartcar Response

The vehicle owner can choose to approve or deny your applications request. Smartcar's redirect to your server will differ depending on the vehicle owner's decision.

Access Granted

If the user grants your application access, the redirect to your application will contain the following query parameters:

HTTP/1.1 302 Found
Location: https://example.com/home?
code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&state=0facda3319
Parameter Description
code A short-lived authorization code which will be used in the following step to obtain an access token.
state If the state parameter was set in the redirect to the Smartcar authorization dialog, it will returned here.

Access Denied

If the user denies your application, an error will be returned instead:

HTTP/1.1 302 Found
Location: https://example.com/home?
error=access_denied
&error_description=User+denied+access+to+application.
&state=0facda3319
Parameter Description
error This will be set to access_denied if the user decided to deny your application access to the requested scope of permissions.
error_description Detailed description of the error.
state If the state parameter was set in the redirect to the Smartcar authorization dialog, it will returned here.

Request Access Token

To interact with the Smartcar API, you will need to exchange your authorization code for an access token. The authorization code represents a user's consent, but cannot be used to make requests to a vehicle. The authorization code must be exchanged for an access token. An example request is provided to the right.

Request

The following headers must be provided with the request:

Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret . The header is formed by concatenating the word "Basic", followed by a space, and a base64 encoded string of the client_id , a colon : , and the client_secret .
Content-Type Must be set to application/x-www-form-urlencoded , matching the format of the request body.

The following parameters must be provided in the request body encoded in form-urlencoded format:

Parameter Required Description
code true The authorization code received in the response of Authorize User step.
grant_type true This value must be set to authorization_code . OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Authorization Code' flow.
redirect_uri true The redirect_uri provided in Authorize User step. This value is checked to match the URI sent when the user was directed to the Smartcar authorization dialog.

Response

Parameter Description
access_token A string representing an access token used to make requests to the Smartcar API.
expires_in The number of seconds the access token is valid for. This is always set to 7200 (2 hours).
refresh_token A string representing a refresh token, which is used to renew access when the current access token expires. The refresh token expires in 60 days.
token_type Always set to Bearer . Token type is used in forming the Authorization header used by the Smartcar API in the following step.
Example Request
curl https://auth.smartcar.com/oauth/token
  -X POST
  -H 'Authorization: Basic base64(<client_id>:<client_secret>)'
  -H 'Content-Type: application/x-www-form-urlencoded'
  -d 'grant_type=authorization_code
      &code=35a59c0b-745c-436c-a8a2-7758e718dcb8
      &redirect_uri=https://example.com/home'
Example Response
{
  "access_token":"cf7ba7e9-8c5d-417d-a99f-c386cfc235cc",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"3e565aed-d4b2-4296-9b4c-aec35825a6aa"
}

Use Smartcar API

Now that you have an access token, your application can make requests to the Smartcar API. Our API uses the bearer authorization header, which is formed by concatenating the word "Bearer" with the access token, separated by a space.

Header Description
Authorization Bearer authorization header containing an access_token . The header is formed by concatenating the word "Bearer", followed by a space, and an access token as shown above.

Remember that your application can only interact with the endpoints your application was granted access to in the authorization flow. In the Request Authorization step, the user granted our application permission to read_vehicle_info and read_odometer.

Get a Vehicle Id

All vehicle endpoints require a vehicle id. Send a GET request to the https://api.smartcar.com/v1.0/vehicles endpoint to retrieve a list of vehicles authorized by the user.

Note: A user's account may include more than one vehicle, all of which are displayed in the authorization flow. The user may choose to grant your application access to any number of vehicles from that set.

Example Request
curl https://api.smartcar.com/v{version}/vehicles
-H "Authorization: Bearer cf7ba7e9-8c5d-417d-a99f-c386cfc235cc"
-X "GET"
Example Response
{
  "paging": {
    "count": 3,
    "offset": 0
  },
  "vehicles": [
    "36ab27d0-fd9d-4455-823a-ce30af709ffc",
    "d6f36bb5-cea9-4963-bbf1-7eb4641e7466",
    "ea2ec8d3-cf26-46dc-8957-c4d0a14af67c"
  ]
}

Basic Vehicle Info

You can retrieve the vehicle's make, model, and year by making a request to the Basic Vehicle Info endpoint.

Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id} -H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  "make": "TESLA",
  "model": "Model S",
  "year": 2014
}

Read Odometer

You can also check the odometer by making a request to the Odometer endpoint.

Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/odometer
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "distance": 104.32
}

Renew Access

Your access token will expire 2 hours after it is issued. When this happens, your application can retrieve a new one by using the refresh_token returned in the Request Access Token step. An example request is provided to the right.

Request

The following headers must be provided with the request:

Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret . The header is formed by concatenating the word "Basic" followed by a space, and a base64 encoded string of the client_id , a colon : , and the client_secret .
Content-Type Must be set to application/x-www-form-urlencoded , matching the format of the request body.

The following parameters must be provided in the request body encoded in form-urlencoded format:

Parameter Required Description
grant_type true This value must be set to refresh_token . OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Refresh Token' flow to allow applications to renew access.
refresh_token true The refresh token received in the response with the access token in the Request Access Token step.

Response

This new access token can now be used to use Smartcar's API.

Parameter Description
access_token A string representing a new access token to be used in requests to the Smartcar API.
expires_in The number of seconds the access token is valid for. This is always set to 7200 (2 hours).
refresh_token A string representing a new refresh token, the previous refresh token is invalidated immediately once it is used. The refresh token expires in 60 days.
token_type Always set to Bearer . The type is used in forming the Authorization header used by the Smartcar API.
Example Request
curl https://auth.smartcar.com/oauth/token
  -X POST
  -H 'Authorization: Basic base64(<client_id>:<client_secret>)'
  -H 'Content-Type: application/x-www-form-urlencoded'
  -d 'grant_type=refresh_token
      &refresh_token=3e565aed-d4b2-4296-9b4c-aec35825a6aa'
Example Response
{
  "access_token":"11016e76-610c-41c6-9688-1f5613889932",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"09337f8a-da3a-46c0-95e7-9c19180b06c0"
}

Headers

Smartcar provides custom HTTP headers to allow you to configure API responses. Our headers are prefixed with sc-. Currently, our API only supports unit configurations using headers.

Units

Smartcar supports both Metric and Imperial unit systems of measurement. Metric is the default unit system for all responses. Use the sc-unit-system header to set your preferred unit system.

Header Description
sc-unit-system Set this to metric or imperial to set the unit system for API response data.

An example using the sc-unit-system to set imperial units is provided to the right. In this example, the odometer reading will be in miles.

Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/odometer
-H "Authorization: Bearer {token}"
-H "SC-Unit-System: imperial"
-X "GET"
Example Response
{
  "distance": 64.82
}

Errors

Smartcar uses HTTP status codes to indicate success or failure of API requests. This includes:

  • 2XX: indicates success
  • 4XX: indicates an invalid request (e.g. a required parameter is missing from the request body)
  • 5XX: indicates Smartcar-related issues (e.g. a vehicle is not capable of fulfilling a request).

Error Response

All Smartcar errors contain the following fields:

Name Type Description
error string A string describing the error type
message string A message explaining the error

Error Types

Error Status Description
validation_error 400 The request was malformed due to incorrect syntax or missing parameters.
authentication_error 401 The provided application credentials were incorrect.
permission_error 403 The application credentials have insufficient permissions to access the requested resource.
resource_not_found_error 404 The requested resource does not exist.
vehicle_state_error 409 The vehicle is not capable of performing the request in its current state.
rate_limiting_error 429 The application has sent too many requests in a short time span.
monthly_limit_exceeded 430 The application has exceeded its monthly request limit.
server_error 500 The server experienced an unexpected error. The vehicle may be unreachable, e.g., in an underground parking lot.
not_capable_error 501 The vehicle is not capable of performing the request. For example, a vehicle without a sunroof cannot perform an ' open sunroof ' command.
Example Error Response
{
  "error": "validation_error",
  "message": "Invalid or missing request parameters."
}
{
  "error": "authentication_error",
  "message": "Invalid or expired token provided."
}
{
  "error": "permission_error",
  "message": "Insufficient permissions to access requested resource."
}
{
  "error": "resource_not_found_error",
  "message": "The requested resource was not found."
}
{
  "error": "vehicle_state_error",
  "message": "Vehicle is not capable of performing request in current state."
}
{
  "error": "rate_limiting_error",
  "message": "The application has sent too many requests and cannot be served due to the application's rate limit being exhausted."
}
{
  "error": "monthly_limit_exceeded",
  "message": "The application has exceeded its monthly limit. Please upgrade the billing plan on the account dashboard."
}
{
  "error": "server_error",
  "message": "Unexpected server error, please try again."
}
{
  "error": "not_capable_error",
  "message": "Vehicle is not capable of performing the request."
}

get All Vehicles

Returns a paged list of all vehicles connected to the application for the current authorized user.

Required Permissions

read_vehicle_info

Response Body

Name Type Description
vehicles array An array of vehicle IDs.
vehicles.[] string A vehicle ID (UUID v4).
paging object Metadata about the current list of elements.
paging.count integer The total number of elements for the entire query (not just the given page).
paging.offset integer The current start index of the returned element list.
get
https://api.smartcar.com/v1.0/vehicles
Example Request
curl https://api.smartcar.com/v{version}/vehicles
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "vehicles": [
    "36ab27d0-fd9d-4455-823a-ce30af709ffc"
  ]
}

get Basic Vehicle Info

Returns a single vehicle object, containing identifying information.

Required Permissions

read_vehicle_info

Response Body

Name Type Description
id string A vehicle ID (UUID v4).
make string The manufacturer of the vehicle.
model string The model of the vehicle.
year integer The model year.
get
https://api.smartcar.com/v1.0/vehicles/{id}
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  "make": "TESLA",
  "model": "Model S",
  "year": 2014
}

delete Disconnect

Revoke access for the current requesting application. This is the correct way to disconnect a user.

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
delete
https://api.smartcar.com/v1.0/vehicles/{id}/application
Example Request
https://api.smartcar.com/v{version}/vehicles/{id}/application
-H "Authorization: Bearer {token}"
-X "DELETE"
Example Response
{
  "status": "success"
}

get Battery

Returns the state of the electric vehicle's battery.

Required Permissions

read_battery

Response Body

Name Type Description
percentRemaining number The remaining level of charge in the battery (in percent).
range number The estimated remaining distance the vehicle can travel (in kilometers by default or in miles using the sc-unit-system ).
get
https://api.smartcar.com/v1.0/vehicles/{id}/battery
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/battery
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "percentRemaining": 0.3,
  "range": 40.5
}

get Charge

Returns the current charge status of the vehicle.

Required Permissions

read_charge

Response Body

Name Type Description
isPluggedIn boolean Indicates whether the charge cable is currently plugged in.
state string Indicates the current state of the charge system.
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "isPluggedIn": false,
  "state": "FULLY_CHARGED"
}

post Charge

Start or stop charging the vehicle.

Required Permissions

control_charge, control_charge:start, control_charge:stop

Request Body

Name Type Required Description
action string true The action to take on the charge system.
Options: START STOP

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/charge
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START"}'
Example Response
{
  "status": "success"
}

get Charge Limit

Returns the current charge limit of the vehicle.

Required Permissions

read_charge_limit

Response Body

Name Type Description
limit number Indicates the level at which the vehicle will stop charging and be considered fully charged (in percent).
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge/limit
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge/limit
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "limit": 0.8
}

post Charge Limit

Enable or disable the vehicle's charge limit setting, optionally changing this limit.

Required Permissions

control_charge_limit, control_charge_limit:enable, control_charge_limit:disable

Request Body

Name Type Required Description
action string true The action to take on the charge limit setting.
Options: ENABLE DISABLE
limit number false The charge limit. The default will be the last set limit. This is unnecessary for the DISABLE action. Indicates the level at which the vehicle will stop charging and be considered fully charged (in percent).

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/charge/limit
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge/limit
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action":"ENABLE", "limit": 0.9}'
Example Response
{
  "status": "success"
}

get Charge Schedule

Returns the current charge schedule of the vehicle.

Required Permissions

read_charge_schedule

Response Body

Name Type Description
state string Indicates the current state of the charge scheduler.
startTime string The time the scheduler will begin charging (in HH:MM format where HH is a 24 hour clock in UTC time).
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge/schedule
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge/schedule
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "startTime": "18:30",
  "state": "ENABLED"
}

get Charge Voltmeter

Returns the voltage of the electric vehicle's charger.

Required Permissions

read_charge_voltmeter

Response Body

Name Type Description
voltage number The current reading of the voltmeter (in volts).
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge/voltmeter
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge/voltmeter
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "voltage": 350
}

get Charge Ammeter

Returns the amperage of the electric vehicle's charger.

Required Permissions

read_charge_ammeter

Response Body

Name Type Description
amperage number The current reading of the ammeter (in amperes).
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge/ammeter
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/charge/ammeter
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "amperage": 1000
}

get Climate

Returns the current state of the vehicle's climate control system.

Required Permissions

read_climate

Response Body

Name Type Description
temperature number The target temperature of the climate system (in celsius by default or in fahrenheit using the sc-unit-system ).
isOn boolean Indicates whether the climate control system is currently running.
get
https://api.smartcar.com/v1.0/vehicles/{id}/climate
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/climate
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "isOn": false,
  "temperature": 35.3
}

post Climate

Turn the climate control system on or off in addition to setting its temperature.

Required Permissions

control_climate, control_climate:start, control_climate:stop

Request Body

Name Type Required Description
action string true The action to take on the climate control system.
Options: START STOP
temperature number false The temperature to set. The default will be the last set temperature. This is unnecessary for the STOP action. If the provided temperature is out of the bounds allowed by the climate control system, the actual temperature will be set to the minimum / maximum value allowed by the climate control system (in celsius by default or in fahrenheit using the sc-unit-system ).

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/climate
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/climate
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START", "temperature": 28.5}'
Example Response
{
  "status": "success"
}

get Compass

Returns the current heading of the vehicle as indicated by the compass.

Required Permissions

read_compass

Response Body

Name Type Description
heading number The current compass heading (in degrees).
get
https://api.smartcar.com/v1.0/vehicles/{id}/compass
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/compass
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "heading": 4.23
}

get Doors

Returns the state of the vehicle doors.

Required Permissions

read_doors

Response Body

Name Type Description
doors array An array containing information for each vehicle door.
doors.[].location string A door ' s position in the vehicle.
doors.[].isOpen boolean Indicates whether the door is open.
get
https://api.smartcar.com/v1.0/vehicles/{id}/doors
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/doors
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "doors": [
    {
      "isOpen": false,
      "location": "FRONT_LEFT"
    }
  ]
}

post Ignition

Start or stop the vehicle's engine/accessory modes. This also includes vehicles with electric motors. `START` allows the driver to start moving the vehicle.

Required Permissions

control_ignition, control_ignition:start, control_ignition:on, control_ignition:accessory, control_ignition:off

Request Body

Name Type Required Description
action string true The action to take on the ignition. The ` START ` action will result in the ignition state being set to ` ON ` .
Options: OFF ACCESSORY ON START

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/ignition
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/ignition
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START"}'
Example Response
{
  "status": "success"
}

post Horn

Honk the vehicle's horn.

Required Permissions

control_horn, control_horn:honk

Request Body

Name Type Required Description
action string true The action to take on the horn.
Options: HONK

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/horn
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/horn
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "HONK"}'
Example Response
{
  "status": "success"
}

post Headlights

Control the vehicle's headlights.

Required Permissions

control_headlights, control_headlights:flash, control_headlights:on, control_headlights:off

Request Body

Name Type Required Description
action string true The action to take on the headlights.
Options: FLASH ON OFF
type string true The type of headlights to take action on.
Options: LOW_BEAM HIGH_BEAM FOG DRL

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/lights/headlights
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/lights/headlights
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "FLASH", "type": "LOW_BEAM"}'
Example Response
{
  "status": "success"
}

get Location

Returns the location of the vehicle in geographic coordinates.

Required Permissions

read_location

Response Body

Name Type Description
latitude number The latitude (in degrees).
longitude number The longitude (in degrees).
get
https://api.smartcar.com/v1.0/vehicles/{id}/location
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/location
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "latitude": 37.4292,
  "longitude": 122.1381
}

get Odometer

Returns the vehicle's current odometer reading.

Required Permissions

read_odometer

Response Body

Name Type Description
distance number The current odometer of the vehicle (in kilometers by default or in miles using the sc-unit-system ).
get
https://api.smartcar.com/v1.0/vehicles/{id}/odometer
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/odometer
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "distance": 104.32
}

get Application Permissions

Returns a paged list of all permissions currently associated with this vehicle.

Response Body

Name Type Description
permissions array An array of permissions.
permissions.[] string A permission.
paging object Metadata about the current list of elements.
paging.count integer The total number of elements for the entire query (not just the given page).
paging.offset integer The current start index of the returned element list.
get
https://api.smartcar.com/v1.0/vehicles/{id}/permissions
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/permissions
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "permissions": [
    "read_vehicle_info"
  ]
}

post Charge Port

Open the charge port.

Required Permissions

control_charge_port, control_charge_port:open, control_charge_port:close

Request Body

Name Type Required Description
action string true The action to take on the charge port.
Options: OPEN CLOSE

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/ports/charge
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/ports/charge
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'
Example Response
{
  "status": "success"
}

get Security

Returns whether the vehicle is locked or unlocked.

Required Permissions

read_security

Response Body

Name Type Description
isLocked boolean Indicates whether the vehicle is locked/unlocked.
get
https://api.smartcar.com/v1.0/vehicles/{id}/security
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/security
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "isLocked": true
}

post Security

Lock or unlock the vehicle.

Required Permissions

control_security, control_security:unlock, control_security:lock

Request Body

Name Type Required Description
action string true The action to take on the security system.
Options: LOCK UNLOCK

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/security
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/security
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "LOCK"}'
Example Response
{
  "status": "success"
}

get Speedometer

Returns the vehicle's current speed.

Required Permissions

read_speedometer

Response Body

Name Type Description
speed number The vehicle ' s current speed (in kilometers/hour by default or in miles/hour using the sc-unit-system ).
get
https://api.smartcar.com/v1.0/vehicles/{id}/speedometer
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/speedometer
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "speed": 104.32
}

get Steering Wheel

Returns the location and orientation of the steering wheel.

Required Permissions

read_steering_wheel

Response Body

Name Type Description
location string Position of the steering wheel relative to the vehicle.
turnPercent number The turn orientation of the vehicle. A value of 0 indicates the vehicle is pointed directly ahead. A value of -1 indicates the vehicle is turned fully to the left. A value of 1 indicates the vehicle is turned fully to the right (in percent).
get
https://api.smartcar.com/v1.0/vehicles/{id}/steering_wheel
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/steering_wheel
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "location": "LEFT",
  "turnPercent": 0.25
}

get Sunroof

Returns the state of the vehicle's sunroof.

Required Permissions

read_sunroof

Response Body

Name Type Description
state string Indicates the current state of the vehicle ' s sunroof.
percentOpen number Indicates how far the sunroof is open. This is meaningful only when the sunroof ' s state is ' OPEN ' . If the state is ' VENTED ' or ' CLOSED ' , this will always be 0. Note that a ' VENTED ' sunroof will be slightly ajar (in percent).
get
https://api.smartcar.com/v1.0/vehicles/{id}/sunroof
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/sunroof
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "percentOpen": 0.25,
  "state": "CLOSED"
}

post Sunroof

Control the vehicle's sunroof.

Required Permissions

control_sunroof, control_sunroof:open, control_sunroof:close, control_sunroof:vent

Request Body

Name Type Required Description
action string true The action to take on the sunroof.
Options: OPEN VENT CLOSE
percentOpen number false Indicates how far the sunroof should be opened. Can only be used in conjunction with the ' OPEN ' action. By default, the sunroof will fully open (in percent).

Response Body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/sunroof
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/sunroof
-H "Authorization: Bearer {token}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'
Example Response
{
  "status": "success"
}

get Outside Temperature

Returns the current reading of the vehicle's exterior temperature sensor.

Required Permissions

read_exterior_thermistor

Response Body

Name Type Description
temperature number Temperature (in celsius by default or in fahrenheit using the sc-unit-system ).
get
https://api.smartcar.com/v1.0/vehicles/{id}/thermistors/exterior
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/thermistors/exterior
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "temperature": 35.2
}

get Inside Temperature

Returns the current reading of the vehicle's interior temperature sensor.

Required Permissions

read_interior_thermistor

Response Body

Name Type Description
temperature number Temperature (in celsius by default or in fahrenheit using the sc-unit-system ).
get
https://api.smartcar.com/v1.0/vehicles/{id}/thermistors/interior
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/thermistors/interior
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "temperature": 35.2
}

get Transmission

Returns the vehicle's transmission type and its current state.

Required Permissions

read_transmission

Response Body

Name Type Description
type string The type of engine.
state string The current state of the vehicle.
get
https://api.smartcar.com/v1.0/vehicles/{id}/transmission
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/transmission
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "state": "PARK",
  "type": "MANUAL"
}

get Front Trunk

Returns the state of the vehicle's front trunk.

Required Permissions

read_front_trunk

Response Body

Name Type Description
isOpen boolean Indicates whether the front trunk is currently open.
get
https://api.smartcar.com/v1.0/vehicles/{id}/trunks/front
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/trunks/front
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "isOpen": false
}

get Rear Trunk

Returns the state of the vehicle's rear trunk.

Required Permissions

read_rear_trunk

Response Body

Name Type Description
isOpen boolean Indicates whether the rear trunk is currently open.
get
https://api.smartcar.com/v1.0/vehicles/{id}/trunks/rear
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/trunks/rear
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "isOpen": false
}

get VIN

Returns the vehicle's manufacturer identifier.

Required Permissions

read_vin

Response Body

Name Type Description
vin string The manufacturer unique identifier.
get
https://api.smartcar.com/v1.0/vehicles/{id}/vin
Example Request
curl https://api.smartcar.com/v{version}/vehicles/{id}/vin
-H "Authorization: Bearer {token}"
-X "GET"
Example Response
{
  "vin": "1234A67Q90F2T4567"
}
Show examples in: