Volvo On Call (VOC) API

Hi!

This subject is something that really interests me, its an awesome technology that has many prospects for the future. So, Of course I would like to know how it works.

Before you continue reading, I would like you to know that the information written below is for education purpose only. Using the things explained below (for what ever reason) might (most likely) be breaking the Swedish law (since the volvo on call server is located in Göteborg (Gothenburg)). Contacting and use data from the Volvo on call API might be seen as data trespassing, which Sweden has a law against (Describes as “Dataintrång” defined as crime in 4 chapter 9 § of the crime code (brottsbalken)).

Update:

According to the license agreement you agree when creating your VOC account, you are not allowed to “Decompile, reverse-engineer, try to extract source-code, change or re-create the service”. Hence you are not allowed to make your own VOC app. Which is also the reason why I have done none of the above.

End update.

So, here we go.

Next week I am going to get my V60 MY12 and I already downloaded the Volvo On Call app. I thought, if possible I’ll write my own app where I not only can set a timer, but also can set a schedulation and also might be able to export journal information. So, I went to work.

It took me a few hours last night to figure everything out, but I think I got it now. Since I have no Volvo on call account yet, I can’t give any full details just yet.

So, how does it work?

The VOC service

I am not going through any details on how the VOC service works, but from what I understand it, its being run using a cellular connection to post data to the vehicle from a centralized server/service (based upon Wirelesscar.com services I believe). You as user use the service by sending command to an API which in its turn contact the service, which connects to the car.

So, I installed Wireshark and tried to figure some stuff out. I shared the network on my MacBook and connected my iPhone to this network. Then I started listening for packages as I tried to register for an account in the app.

Decrypting

Unfortunate for me, the fine people at Volvo (and maybe some at Mobiento as well(?)) thought of that and took the natural way of setting up the server with a Rapid SSL certificate; thereby encrypting the connection between the client and server… impossible for me to decrypt unless I have the private key (which I’ll never have!). So, I couldn’t find out much more than that the API is located at https://vocapi.wirelesscar.net (wirelesscar.net is owned by Volvo in Göteborg, and host to an IP address in the same city; hence the legal note above!). But, visiting that URL only give me a forbidden page from Apache 2.2.3 web server on a Red Hat server. Dammed! Stuck!

Fortunate for me is that the client (VOC app) doesn’t make any certificate verification and trusts that if the certificate is “trusted” by the system, it must be OK. So, after searching a bit I found the OS X App called “Charles“. Charles is a web-debugging proxy. This means that you can make a proxy for debugging purposes ect. Also, Charles lets me setup an SSL proxy, which is just what I needed. Charles shares the private certificate it uses, so I could import it on my iPhone so my Phone would trust it.

Now I setup my proxy, removed the internet sharing and changed the wireless settings on my phone to connect to the internet using a proxy… my MBP using Charles. Suddenly, when trying to register in the app I actually could figure out where the API is located, which is https://vocapi.wirelesscar.net/customerapi/rest/v2.0/. Since I now possess the private key, Charles automatically decrypts the connection and I could read the data in clear text. Awesome! So I tried it out in the browser….

Dammed! HTTP-Authentication!

Here I got stuck for quite a while… whatever I did, I could not figure out the login. None of the logs, neither in Wireshark or Charles ever displayed any HTTP-Auth. If they would, it would be a piece of cake, since HTTP-Basic auth is nothing more than a Base64 encoding of the login string (username@password).

I sat with it an hour yesterday evening and it suddenly hit me… how can the app get data back, when it doesn’t have to login? Well, that’s because the register page doesn’t require any login. So I tried the register account page. So I looked a bit closer, and as you do in a Rest-full API, when setting data you either POST it (new data) or PUT it (update data). The app was Posting.

So I installed the FireFox addon HTTP Resource Test and voila.. it worked! I could re-create the request on my mac.

So now I could figure out why I couldn’t access the other pages. Since I made the request manually now, I could see in Charles that the basic auth was actually the login I would create when creating a real account.

Stuck, till next week

So, for now I am stuck here, since I do not have my VOC pin code yet, which I guess I’ll set with the dealer next week. I will then try to figure out the API and see if it is of any use for what I want to do.

Why do I want to know all this?

Well, even though Mobiento AB made a fine app, I believe some things are missing.
Do not misunderstand me me, I do like Mobiento. They are (just as every other App company in Stockholm), the best App agency (even though they don’t want to call themselves that).

What I am missing is the possibility to set a schedulation for the heating timer. I would like the app to automagically send the command to the car that the timer must be set for X o’clock tomorrow morning. It doesn’t seem that the app has this support.

There are (at least) two ways of doing this:

1) By an external server, having the values and sending them to the API when appropriate

2) By setting local push notification and inform the user it has to set the timer (which opens the app, shows a button and sets the timer).

Also, I would like the export the journal data to e.g. CSV file so I can use it in e.g. Excel.

Last but not least, I am a little bothered by that Mobiento didn’t add iPhone 5 support AND that the they chose to divert just a little bit from traditional iOS GUI. Somehow, something feels wrong in the app. For instance (in demo mode), the tabs. They give a illusion that the wrong tab is chosen.. the colors should be the other way around (active/in-active tab). I think I actually can make a better looking app… if I only get the time.

Updates

So, when I’ll get my car… will I update this page with the API information?

Well, I don’t know just yet. I gave you in wide ranges the recipe above on how to figure it out yourself, so you could do it yourself. However, given that you actually need an account in order to test your application or to find out how the API looks… I think its best not to share the API information. Maybe I’ll just share some method to prove that I actually figured it out.

Summary

The volvo on call (VOC) API is located here: https://vocapi.wirelesscar.net/customerapi/rest/v2.0/
It uses HTTP Basic Authentication for login, based upon the users credentials.
It uses a Rapid-SSL signed certificate for encryption
Request and Respone data are in JSON format, UTF-8 encoded
The VOC server is located in Göteborg, hence Swedish law applies (regardless from where you connect)
The VOC server runs on Apache 2.2.3 on a Red Hat server.
The official app is developed by Mobiento in Stockholm

Hope you have any use for it. Remember, for education purposes only!

Update #1, 2013-02-14

So I got my car on monday, one day early (Go Upplands Motor!) =) and got VOC installed. Now I have had the change the test the VOC app properly and it does work great. Still there are some UX misses/bugs but the app itself works great. It crashed once or twice, but thats OK for me.

I tested out my theory above and got it confirmed. When having an account for VOC it works great. The downside though is there are no help pages available for the api, not to my knowledge anyways. Which means that in order to find out which methods are available, you (or I) need to call ever method from the current app and use Charles to figure out the data. That means that there could be more functionality which is not yet exposed. Also, it means that current methods could accept more data are give different result (e.g. flash and horn, maybe there’s a “flash only” parameter?).

For now, I have asked @VolvoCarsGlobal on twitter to get in touch with the project leader for VOC, We’ll see what happens there.

Update #2, 2013-12-11

A week or two ago Volvo released a new app. Unfortunately the app is a bit worse then the last one. However, it now uses the Volvo ID. This gives hopes for an open API, but I am not sure about it. I asked @VolvoSverige and they asked their IT department. Hopefully they’ll get back to me.

Cheers,
Paul

Posted in Charles, Development, Hacking, iPhone, Mac, Objective-c, Tutorials, VOC, Volvo, Web, Wireshark Tagged with: , , , , , , , , , , , , , , ,
13 comments on “Volvo On Call (VOC) API
  1. Andre Pen says:

    Paul, I used bought my XC60 today with Volvo On call and i like to read some data from the car to integrate in our own Geotrack system.

    Please keep me updated.

  2. Paul Peelen says:

    With regards to the license agreement one signes when creating a VOC account, I am not allowed to “Decompile, reverse-engineer, try to extract source-code, change or re-create the service”. Hence I cannot show you any api-data. However, I can imagine you can retrieve quite some data from the API which you use in your Geotrack system.

    A week or two ago Volvo released a new version which uses the Volvo ID instead. I can imagine the old solution still works but I haven’t had any time yet to dissect the API. Have a go on it using the recipe above and check if you can use it, its easier than you imagine 😉

    Good luck!

  3. Victor says:

    Did you hear back from Volvo? I am interested in more info :). If you have can you send it to me?

    Thanks!

  4. Paul Peelen says:

    Not more that “Sorry, we can not assist you at the moment”. However, I have a few contacts inside Volvo, which I later found out, which in their turn told me that Volvo is Nazi secure when it comes to open products. If it is not directly proven to be first and foremost safe and secondly “useful”, it is dismissed. Which also is the reason why we will never get an open API from Volvo.

    Today, the API has been updated to new API:s, but (I believe) it can still be reached. I have not had the time to digg deeper through it… however, I will at some point. You’ll need an VOC account in order to get access to hidden features… but there are a lot of features which we will not know about until you own that specific car model. Things such as “Subscription is ending” or a certain warning light, or AC hot/cold (Cold is not included for MY11/MY12 cars, such as mine).

    One thing is for sure, Volvo knows who I am and I hope I’ll have the possibility to work with them on a more professional level in the future. Hell, maybe they might like to have a better app in the future 🙂

    I hope you figure more out.

    Cheers!

  5. Marcus says:

    This is some info from the demo vehicle, replace host and remove demo in url API 3.0
    I don’t have VOC yet so I can’t test it with the real car. Logininfo is email and password.

    URL to test on real API (EU):
    * https://vocapi.wirelesscar.net/customerapi/rest/v3.0/vehicles/ (should contain folderinfo with car name in system)
    * https://vocapi.wirelesscar.net/customerapi/rest/v3.0/vehicles// (shows avaible attributes, status and relations urls)
    * https://vocapi.wirelesscar.net/customerapi/rest/v3.0/vehicles//status
    * https://vocapi.wirelesscar.net/customerapi/rest/v3.0/vehicles//attributes

    * https://vocapi.wirelesscar.net/customerapi/rest/v3.0/customeraccounts/

    DEMO VEHICLE API (EU):

    https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicles/demovehicle/
    {
    “attributes”: “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicles/demovehicle/attributes”,
    “status”: “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicles/demovehicle/status”,
    “vehicleAccountRelations”: [
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/100”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/101”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/102”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/103”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/104”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/105”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/106”,
    “https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicle-account-relations/107”
    ]
    }

    https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicles/demovehicle/attributes
    {
    “VIN”: “3301CF093301CF09A”,
    “engineCode”: “3301CF09”,
    “engineStartSupported”: true,
    “exteriorCode”: “330111NB”,
    “interiorCode”: “33011078”,
    “tyreDimensionCode”: “3301R535”,
    “tyreInflationPreassureLightCode”: “3301YT19”,
    “tyreInflationPreassureHeavyCode”: “3301YX07”,
    “gearboxCode”: “3301DB04”,
    “fuelType”: “Diesel”,
    “fuelTankVolume”: 70,
    “grossWeight”: 2505,
    “modelYear”: 2012,
    “vehicleType”: “S60”,
    “vehicleTypeCode”: “3301AA09”,
    “numberOfDoors”: 5,
    “country”: {
    “iso2”: “SE”
    },
    “registrationNumber”: “ABC123”,
    “bCallAssistanceNumber”: “+460000001”,
    “carLocatorSupported”: true,
    “honkAndBlinkSupported”: true,
    “remoteHeaterSupported”: true,
    “unlockSupported”: true,
    “lockSupported”: true,
    “journalLogSupported”: true,
    “journalLogEnabled”: true,
    “unlockTimeFrame”: 60,
    “timeFullyAccessible”: 4320,
    “timePartiallyAccessible”: 20160,
    “subscriptionType”: “PREMIUM”,
    “subscriptionStartDate”: “2014-04-07T14:20:00+0000”,
    “subscriptionEndDate”: “2016-04-07T14:20:00+0000”
    }

    https://preproduction-voc.wirelesscar.net/demo/customerapi/rest/v3.0/vehicles/demovehicle/status
    {
    “odometer”: 965000,
    “odometerTimestamp”: “2012-11-25T14:18:23+0000”,
    “tripMeter1”: 2956,
    “tripMeter1Timestamp”: “2012-11-25T14:18:23+0000”,
    “tripMeter2”: 1350,
    “tripMeter2Timestamp”: “2012-11-25T14:18:23+0000”,
    “averageSpeed”: 47,
    “averageSpeedTimestamp”: “2012-11-25T14:18:23+0000”,
    “distanceToEmpty”: 1256,
    “distanceToEmptyTimestamp”: “2012-11-25T14:18:23+0000”,
    “averageFuelConsumption”: 43,
    “averageFuelConsumptionTimestamp”: “2012-11-25T14:18:23+0000”,
    “fuelAmount”: 54,
    “fuelAmountTimestamp”: “2012-11-25T14:18:23+0000”,
    “fuelAmountLevel”: 71,
    “fuelAmountLevelTimestamp”: “2012-11-25T14:18:23+0000”,
    “serviceWarningStatus”: “Normal”,
    “serviceWarningStatusTimestamp”: “2012-11-25T14:18:23+0000”,
    “bulbFailures”: [

    ],
    “bulbFailuresTimestamp”: “2012-11-25T14:18:23+0000”,
    “brakeFluid”: “Normal”,
    “brakeFluidTimestamp”: “2012-11-25T14:18:23+0000”,
    “washerFluidLevel”: “Normal”,
    “washerFluidLevelTimestamp”: “2012-11-25T14:18:23+0000”,
    “tyrePressure”: {
    “frontLeftTyrePressure”: “Normal”,
    “frontRightTyrePressure”: “Normal”,
    “timestamp”: “2012-11-25T14:18:23+0000”,
    “rearLeftTyrePressure”: “Normal”,
    “rearRightTyrePressure”: “Normal”
    },
    “carLocked”: false,
    “carLockedTimestamp”: “2012-11-25T14:18:23+0000”,
    “externalTemp”: “10”,
    “externalTempTimestamp”: “2012-11-25T14:18:23+0000”,
    “internalTemp”: “10”,
    “internalTempTimestamp”: “2012-11-25T14:18:23+0000”,
    “heater”: {
    “timestamp”: “2012-11-25T14:18:23+0000”,
    “timer1”: {
    “time”: “07:30”,
    “state”: true
    },
    “timer2”: {
    “time”: “09:45”,
    “state”: false
    }
    },
    “windows”: {
    “frontLeftWindowOpen”: true,
    “frontRightWindowOpen”: false,
    “timestamp”: “2012-11-25T14:18:23+0000”,
    “rearLeftWindowOpen”: false,
    “rearRightWindowOpen”: false
    },
    “doors”: {
    “frontLeftDoorOpen”: false,
    “frontRightDoorOpen”: false,
    “timestamp”: “2012-11-25T14:18:23+0000”,
    “rearLeftDoorOpen”: false,
    “rearRightDoorOpen”: false,
    “tailgateOpen”: false,
    “engineHoodOpen”: false
    }
    }

  6. Michael Parment says:

    Have you find out any more?

    I want to integrate MyVolvo into OpenHAB.

    /Mike

  7. Paul Peelen says:

    Yes and no; What I have found out, I am legally not allowed to share (see the terms and conditions of VOC), however… using the above, its quite easy figuring it out 😉

  8. Paul Peelen says:

    Thanks @Marcus! Nice find!

  9. Sjoerd says:

    Hi,

    Beginning this month I was able to open link https://vocapi.wirelesscar.net/customerapi/rest/v3.0/vehicles/

    Then I was asked for userid + pw

    Now I get an “HTTP Status 500 – InvalidInputCriteria” error

    Does anyone have an idea if something has been changed and if there is a work around?

  10. Paul Peelen says:

    By the look of the error message, it expects certain GET or POST parameters. Try making the request with your app using charles in between and check the headers that are being send. It will tell you what you are missing. Hint: Check the User Agent as well.

  11. Nika Gerson Lohman says:

    Hi all,

    I found a python repository that allows to easily query status. I tried adding the post into it, but couldn’t get it to work. Anyone with Python experience? Any thoughts why using a simple post won’t work?

    https://github.com/molobrakos/volvooncall

    Regards,

    Nika.

  12. Nika Gerson Lohman says:

    Btw, the reason to send the post is that I want to turn on the heater (based on domotica events, for instance when I turn on the light in the morning and the temperature is <10 degrees). In the following thread I found the command (…/heater/start):
    https://community.openhab.org/t/help-with-sending-command/7046

    Regards,

    Nika.

  13. Nika Gerson Lohman says:

    I figured it out, turns out I was trying to post a heat command whereas my V60 only supports a preclimatization command 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

*

 

Categories