This tutorial is for developers who are:
- Already familiar with REST
- Are looking for the shortest path to a pcode (DTC) definition or any related diagnostic information
- Are looking to test diagnostic APIs
- Are looking to offer an ‘on-demand’ type service with a need for an immediate diagnostic response
Use Cases
Testing the diagnostic APIs: Developer wishes to include a diagnostic service within their application. Developer wishes to test the response time and data coverage of CarMD diagnostic APIs. And wishes to test them quickly and avoid complex setup/integration.
Looking to offer an ‘on-demand’ type service with a need for an immediate diagnostic response: The developer is building an application where when their End-User’s check engine light turns on the End-User would check the developer’s platform for information. The platform would provide information concerning the pcode (DTC), description and cost of the repair, and possible causes. The end-user only uses CarMD’s diagnostic services and no other CarMD service.
Design pattern
The above usage does not follow a typical fleet model. In fleets all vehicles remain active in order to provide real time fleet-wide analytical data. In this use case, the user only accesses services when needed and there is no need to keep a user active all the time.
Pathway
- User gets a check engine light
- User gets a text, email, or otherwise accesses platform
- User taps link or button leading to accessing CarMD service
- On the backend: Platform adds/activates this vehicle on CarMD
- On the backend: Use CreateReport, the response is full diagnostic data
- On the backend: Once user is done viewing contents, platform deactivates vehicle
In this setup, the vehicle is only added/activated when the service is being used. Then after the end-user is done, the vehicle is deactivated. This method ensures that charges are only applied when an end-user is actively using CarMD services.
Detailed walkthrough (Important)
Step 1: Upgrade your account
If you are using a free account, you will not be able to use the CreateReport method. You will need to upgrade your account to a paid tier.
With an upgraded account, your service will allow up to 100 activated vehicles of your choice and the ability to use any of the CarMD services for those 100 vehicles.
Step 2: Add a vehicle
You may use any of the pre-set vehicles or add your own for testing. For those who wish to test their own vehicles, you will need to use a fleetID. Your account already has one so you do not need to create a new one.
Using the http://api2.carmd.com/v2.0/fleet endpoint, use the snippet below to fetch the fleetID.
fleetID = resp[‘data’][0][‘fleetID’]Or you may add your own fleet.
Fleets are containers for vehicles – added to assist developers in organizing their customers. If your end-users are primarily consumers, you may place all vehicles in a single fleet. If your end-users are businesses, you may want to create separate fleets.
Why use or don’t use fleets? Several features have an option of operating on a fleet level allowing one to pull all the information on an entire fleet using a single request. This is valuable to a fleet manager who wishes to see the overall health of their fleet or if there are any particular outliers to address.
POST Add vehicle
You will need the following information:
- fleetID – fetched above
- VIN – vehicle identification number
Mileage is a required entry. For testing purposes, it can be entered as ‘zero’. However in your application it is recommended to submit the real odometer reading if possible. Once the vehicle has been added correctly, it should automatically be activated and ready to use. Save the vehicleID from the response.
Step 3 POST CreateReport
This endpoint takes in vehicle data and provides diagnostic data in return.
Required fields
data[‘vehicleID’] – the result of step2, this identifies which vehicle this data is for.
data[‘formattedData’][‘codes’][‘pwrPrimary’] – This code is the main cause of the check engine light, aka the primary code. If the check engine light is on, the vehicle will have one and only one primary code. Some dongles provide the primary code, some only provide a list of codes and does not make a distinction which may be the primary code. If you are retrieving a list of codes, selecting the 1st one is your best bet, however it is not guaranteed to be the correct primary code. Since fixes differ greatly between DTCs, it is best to provide the correct DTC. Please review your dongle / application specs or contact your manufacturer.
See Example with formatted Data under Request Data for reference.
Responses
Response information includes but not limited to:
- Definition of the code – the technical meaning of the code
- Laymen definition of code – the definition of the code in terms understandable by regular people
- The Fix – repair needed for the vehicle
- Cost of repair – and cost of elements that make up that repair such as parts costs, labor duration
- Severity – a score of 1-3 of how severe this code is, where 1 is something that can be ignored for a bit and 3 is something that should be repaired asap.