├── .gitignore ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── api ├── CHANGELOG.md ├── README.md ├── api │ └── v3 │ │ ├── README.md │ │ ├── auth │ │ ├── README.md │ │ ├── access_token.md │ │ └── auth.md │ │ ├── cars │ │ ├── README.md │ │ ├── car_id.md │ │ ├── locations-geojson.md │ │ ├── locations.md │ │ ├── signals.md │ │ ├── signals_list.md │ │ ├── stats │ │ │ ├── mileage.md │ │ │ └── usedtime.md │ │ ├── status.md │ │ └── trips.md │ │ ├── devices │ │ ├── README.md │ │ ├── associate_car.md │ │ ├── associate_user.md │ │ └── dissociate.md │ │ ├── trips │ │ ├── README.md │ │ ├── locations-geojson.md │ │ ├── locations.md │ │ ├── signals.md │ │ ├── trip_id.md │ │ └── trip_id │ │ │ ├── stats.md │ │ │ └── stats │ │ │ ├── mileage.md │ │ │ └── usedtime.md │ │ └── users │ │ ├── README.md │ │ ├── cars.md │ │ ├── cars_create.md │ │ ├── me.md │ │ ├── me │ │ └── cars.md │ │ └── user_id.md └── compat │ ├── v1 │ ├── README.md │ ├── cardb │ │ ├── README.md │ │ └── cardbId.md │ └── ktype │ │ ├── README.md │ │ └── ktype.md │ └── v3 │ ├── README.md │ ├── brands.md │ ├── cardb.md │ ├── ktype.md │ ├── models.md │ ├── versions.md │ └── versionsByPlateNumber.md └── setup ├── README.md └── scopes.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .idea 3 | xee-documentation.iml -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | #Contributing 2 | 3 | Please observe our contribution guidelines before creating a pull request: 4 | 5 | * Open an issue first. 6 | * Expain what you want to do about the documentation, we'll discuss that with you (*Note that this documentation is intended to be a short and concise*). 7 | * If the issue is validated, fork the repository and make a **pull request** 8 | 9 | ## Issue titles 10 | 11 | Any issue title must follow the pattern 12 | `[Group] root : Issue` 13 | 14 | - `Group` is where you found the issue. For example in the *android* doc, `group` will be `Android`. 15 | - `root` is the *file* or the *end point* where the problem is. 16 | - And finally, `issue` is what is wrong. Or what you want. 17 | 18 | >For example, in the `cars` api, the field `deviceId` as the wrong type. The issue should be : 19 | >`[Cars] cars : deviceId should be a serial number` 20 | 21 | ## Commit messages and Pull requests 22 | 23 | Before any **pull request**, please [`rebase`](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) your commits to make them easy to read. 24 | 25 | - If the **PR** fixes an issue, the title must be 26 | `Fixes #issueNumber : Title of issue` 27 | - Else, the title must looks like: 28 | `[Group] Type : Description` where type is the kind of thing done (*Feat*, *Update*, *Delete*, *Style*) 29 | 30 | #Licence 31 | 32 | [Creative Commons Licence](LICENSE.md) 33 | 34 | Xee Documentation by the Xee Tech team is licensed under a Creative Commons Attribution 4.0 International Licence. 35 | 36 | Based on a work at [https://github.com/xee-lab/documentation](https://github.com/xee-lab/documentation) 37 | 38 | > The licence must remain in all derivatives of this work. -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Editorial contents of the Xee Documentation are released as [Creative Commons Attribution-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-sa/4.0/legalcode). 2 | 3 | ![by icon](http://mirrors.creativecommons.org/presskit/icons/by.svg) 4 | ![sa icon](http://mirrors.creativecommons.org/presskit/icons/sa.svg) 5 | 6 | This means you can use them on your own derived works, in part or completely, as long as you also adopt the same license. You find the complete text of the license here. 7 | 8 | Xee brand, Xee logo, design of the website and design of the boards are copyright of Eliocity SAS and cannot be used without formal permission. For informations about the right way to use them, please write to [contact@xee.com](mailto:contact@xee.com) -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Xee Developer Documentation 2 | 3 | This is the official documentation for the Xee Platform, written by the [Xee tech team](https://twitter.com/@Xee_ENG) with community contributions. 4 | 5 | ## Contents 6 | 7 | - [Setup / Quickstart](setup/README.md) 8 | - Getting started with the Xee environment 9 | - [Rest API](api/README.md) 10 | - Start your first app connected with Xee 11 | 12 | ## Official SDKs 13 | 14 | |Language|Author|Link|License| 15 | |---|---|---|---| 16 | |Android|[xee-lab](https://github.com/xee-lab)|[xee-sdk-android](https://github.com/xee-lab/xee-sdk-android)|![License Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-brightgreen.svg)| 17 | |iOS|[xee-lab](https://github.com/xee-lab)|[xee-sdk-ios](https://github.com/xee-lab/xee-sdk-ios)|![License Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-brightgreen.svg)| 18 | 19 | ## Third party SDKs 20 | 21 | As the API is open, it's up to you to create an SDK for the platform. 22 | 23 | Here is the list of SDK from community: 24 | 25 | > If you want your SDK to be here, please open an _**issue**_ with a **title** like 26 | > `[SDK] Add : SDK for {lang}` _(for example: `[SDK] Add : SDK for .NET`)_ and a **description** that contains: 27 | > 28 | > * Link to the repo 29 | > * License 30 | > * Any shield link 31 | 32 | |Language|Author|Link|License|Shields| 33 | |---|---|---|---|---| 34 | |[Golang](https://golang.org/)|[laibulle](https://github.com/laibulle/)|[go-xee](https://github.com/laibulle/go-xee)|![MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)|[![Build Status](https://travis-ci.org/laibulle/go-xee.svg?branch=master)](https://travis-ci.org/laibulle/go-xee)
[![Coverage Status](http://codecov.io/github/laibulle/go-xee/coverage.svg?branch=master)](http://codecov.io/github/laibulle/go-xee?branch=master)| 35 | |[Python](https://www.python.org/)|[quentin7b](https://github.com/quentin7b/)|[xee-sdk-python](https://github.com/quentin7b/xee-sdk-python)|![Apache 2](https://img.shields.io/badge/License-Apache%202.0-brightgreen.svg)|[![Build Status](https://travis-ci.org/quentin7b/xee-sdk-python.svg?branch=master)](https://travis-ci.org/laibulle/go-xee)
[![Coverage Status](http://codecov.io/github/quentin7b/xee-sdk-python/coverage.svg?branch=master)](http://codecov.io/github/quentin7b/xee-sdk-python?branch=master)| 36 | 37 | ## Live status of the endpoints 38 | 39 | [![API V3 status](https://status.xee.com/component/15/shield)](https://status.xee.com) 40 | [![Storage Service status](https://status.xee.com/component/5/shield)](https://status.xee.com) 41 | [![Trip Service status](https://status.xee.com/component/6/shield)](https://status.xee.com) 42 | [![XeeDev status](https://status.xee.com/component/7/shield)](https://status.xee.com) 43 | 44 | All incidents are reported on the [Xee Status Page](https://status.xee.com) 45 | 46 | ## Contributions 47 | 48 | If you see any mistake or details to add, first [file an issue](http://github.com/xee-lab/documentation/issues) on GitHub to see if it is likely to be accepted, then file a pull request with your change (one PR per issue). 49 | See our [contributing policy](CONTRIBUTING.md). 50 | -------------------------------------------------------------------------------- /api/CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## v3 4 | 5 | |Date|Type|Description|Link| 6 | |---|---|---|---| 7 | |2016-10-25|UPDATE|Add a new signal `ComputedFuelLevel`|[`/cars/signals_list`](api/v3/cars/signals_list.md)| 8 | |2016-09-13|UPDATE|Remove unpossible errors|[`/users/me/cars`](api/v3/users/me/cars.md)| 9 | |2016-09-13|UPDATE|Update the list of signals|[`/cars/signals_list`](api/v3/cars/signals_list.md)| 10 | |2016-09-05|ADD|Add trip statistics|[`/trips/{tripId}/stats`](api/v3/trips/trip_id/stats.md),
[`/trips/{tripId}/stats/mileage`](api/v3/trips/trip_id/stats/mileage.md),
[`/trips/{tripId}/stats/usedtime`](api/v3/trips/trip_id/stats/usedtime.md)| 11 | |2016-09-05|UPDATE|Fixes a typo (issue #38)|[`/users/{userId}`](api/v3/users/user_id.md),
[`/users/me`](api/v3/users/me.md)| 12 | |2016-08-25|UPDATE|The parameter `inservice` was replaced by `in_service`|[`/ktype/{ktype}`](compat/v1/ktype/ktype.md) 13 | |2016-08-01|ADD|Add compatibility API|[`/compat/v1`](compat/v1/README.md)| 14 | |2016-07-27|UPDATE|Typo in stats|[`/cars/{carId}/stats/usedtime`](api/v3/cars/stats/usedtime.md)| 15 | |2016-07-25|UPDATE|Fixes a typo (issue #26)|[README](api/v3/README.md)| 16 | |2016-07-15|ADD|Add `cars` stats|[`/cars/{carId}/stats/mileage`](api/v3/cars/stats/mileage.md),
[`/cars/{carId}/stats/usedtime`](api/v3/cars/stats/usedtime.md)| 17 | |2016-07-07|UPDATE|Update `trips` responses|[`/cars/{carId}/trips`](api/v3/cars/trips.md),
[`/trips/{tripId}`](api/v3/trips/trip_id.md)| 18 | |2016-06-27|ADD|We've added *sandbox* APIs on specified routes|[`/users/{userId}`](api/v3/users/user_id.md),
[`/cars/{carId}`](api/v3/cars/car_id.md),
[`/cars/{carId}/locations`](api/v3/cars/locations.md),
[`/cars/{carId}/locations.geojson`](api/v3/cars/locations-geojson.md),
[`/cars/{carId}/signals`](api/v3/cars/signals.md),
[`/cars/{carId}/status`](api/v3/cars/status.md),
[`/cars/{carId}/trips`](api/v3/cars/trips.md),
[`/trips/{tripId}`](api/v3/trips/trip_id.md),
[`/trips/{tripId}/locations`](api/v3/trips/locations.md),
[`/trips/{tripId}/locations.geojson`](api/v3/trips/locations-geojson.md),
[`/trips/{tripId}/signals`](api/v3/trips/signals.md)| 19 | |2016-05-23|UPDATE|The parameters `redirect_uri` and `scope` are not mandatory anymore|[`/auth/auth`](api/v3/auth/auth.md)| 20 | |2016-05-22|UPDATE|Complement error cases|[`Authentication README`](api/v3/auth/README.md) 21 | |2016-05-12|ADD|We've added a `/users/me/cars` route|[`/users/me/cars`](api/v3/users/me/cars.md)| 22 | |2016-05-12|ADD|We've added a `/users/me/cars` route|[`/users/me/cars`](api/v3/users/me/cars.md)| 23 | |2016-05-12|UPDATE|The field `deviceId` in *cars* entity is now a `string`|[`/users/{userId}/cars`](api/v3/users/cars.md),
[`/cars/{carId}`](api/v3/cars/car_id.md)| 24 | -------------------------------------------------------------------------------- /api/README.md: -------------------------------------------------------------------------------- 1 | # Rest API 2 | 3 | How do we talk together ? 4 | 5 | > See the changes we made in the [Changelog](CHANGELOG.md) file 6 | 7 | ## Format 8 | 9 | Our API are [REST](https://fr.wikipedia.org/wiki/Representational_State_Transfer) and the format of the data we use is [JSON](https://fr.wikipedia.org/wiki/JavaScript_Object_Notation) 10 | 11 | ## Host and version 12 | 13 | All our API are bellow `https://cloud.xee.com`, as we're in the third version, all the API starts with `https://cloud.xee.com/v3/` 14 | 15 | > If there is a special case with a legacy API, it'll be explained in the description of the route. 16 | 17 | ## Mocking 18 | 19 | From the third version of our API, there is a **sandbox API** exposing *fake data*, you can reach it by using `https://sandbox.xee.com/v3/` 20 | 21 | ## API 22 | 23 | - See our [API v3 Documentation](api/v3/README.md) 24 | - See our [Compat v1 Documentation](compat/v1/README.md) -------------------------------------------------------------------------------- /api/api/v3/README.md: -------------------------------------------------------------------------------- 1 | # v3 2 | 3 | The third version of Xee API 4 | 5 | ## Why ? 6 | 7 | The `v2` of our API was good in terms of content, but there were some *ugly* things. 8 | 9 | - Dates were not the same everywhere 10 | - Errors were not the same everywhere 11 | - Sometimes it was v1, sometimes v2 12 | 13 | So we decided to build a `v3` to get a new begining. The goal is to be *simple*, *easy*. 14 | 15 | - Dates are `RFC3339` 16 | - Errors look the same everytime 17 | 18 | ## Authentication 19 | 20 | > The authentication is a *special* case. 21 | 22 | We can't provide a REST API for *authentication* for a simple reason: *User passwords would be known from every single app* 23 | 24 | So the authentication is handled by us, in a web page for now (that might change one day for mobiles). 25 | 26 | The process is quite simple, don't be afraid! 27 | 28 | > Have a look at [auth readme](auth/README.md) for the auth documentation and the **errors it can throw** 29 | 30 | |API|Description| 31 | |---|---| 32 | |[`GET /auth/auth`](auth/auth.md)|For the authentication page| 33 | |[`POST /auth/access_token`](auth/access_token.md)|For the *access token* API| 34 | 35 | ## API 36 | 37 | All the **routes** are bellow `https://cloud.xee.com/v3`. 38 | 39 | > Note if you need **sandbox APIs** for testing purpose or starting, you can do it by using `https://sandbox.xee.com/v3` as route host. 40 | 41 | ### Users 42 | 43 | This is the first route of our API, from this, you can get the logged in user data 44 | 45 | > [Users API](users/README.md) Get the user information, his *id*, his *last name*, *first name*, even his *cars*. 46 | 47 | |API|Description| 48 | |---|---| 49 | |[`GET /users/me`](users/me.md)|Get the connected user| 50 | |[`GET /users/me/cars`](users/me/cars.md)|Get all the cars for the connected user| 51 | |[`GET /users/{userId}`](users/user_id.md)|Get a specific user| 52 | |[`GET /users/{userId}/cars`](users/cars.md)|Get all the cars from a user| 53 | |[`POST /users/{userId}/cars`](users/cars_create.md)|Create a car for this user| 54 | 55 | ### Cars 56 | 57 | This is the second route of our API, from this, you can get all the *raw* car data 58 | 59 | > [Cars API](cars/README.md) Get the car data, its *id*, its *locations*, even its *trips*. 60 | 61 | |API|Description| 62 | |---|---| 63 | |[`GET /cars/{carId}`](cars/car_id.md)|Get a specific car from its *id*| 64 | |[`GET /cars/{carId}/status`](cars/status.md)|Get car *status*| 65 | |[`GET /cars/{carId}/locations`](cars/locations.md)|Get car *locations* history| 66 | |[`GET /cars/{carId}/locations.geojson`](cars/locations-geojson.md)|Get car *locations* history in a [geojson](http://geojson.org/) format| 67 | |[`GET /cars/{carId}/signals`](cars/signals.md)|Get car *signals* history| 68 | |[`GET /cars/{carId}/trips`](cars/trips.md)|Get car *trips*| 69 | |[`GET /cars/{carId}/stats/mileage`](cars/stats/mileage.md)|Get car *mileage* statistic| 70 | |[`GET /cars/{carId}/stats/usedtime`](cars/stats/usedtime.md)|Get car *used time* statistic| 71 | 72 | ### Trips 73 | 74 | This is the third route of our API, from this, you can get all the *trips related* car data 75 | 76 | > [Trips API](trips/README.md) Get the *trip* data, its *id*, its *locations*, ... 77 | 78 | |API|Description| 79 | |---|---| 80 | |[`GET /trips/{tripId}`](trips/trip_id.md)|Get a specific *trip* from its *id*| 81 | |[`GET /trips/{tripId}/locations`](trips/locations.md)|Get all locations from a *car* during a specific *trip*| 82 | |[`GET /trips/{tripId}/locations.geojson`](trips/locations-geojson.md)|Get all locations from a *car* during a specific *trip* in a [geojson](http://geojson.org/) format| 83 | |[`GET /trips/{tripId}/signals`](trips/signals.md)|Get all signals from a *car* during a specific *trip*| 84 | |[`GET /trips/{tripId}/stats`](trips/trip_id/stats.md)|Get a specific *trip* statistics| 85 | |[`GET /trips/{tripId}/stats/mileage`](trips/trip_id/stats/mileage.md)|Get a specific *trip* mileage| 86 | |[`GET /trips/{tripId}/stats/usedtime`](trips/trip_id/stats/usedtime.md)|Get a specific *trip* duration| 87 | 88 | ### Devices 89 | 90 | This is the fourth route of our API, from this, you can manage your associated devices. 91 | These routes are quite private, and the required scope to call them is not accessible to all the applications. 92 | 93 | > [Devices API](devices/README.md) Associate devices to an given user, to a given car ... 94 | 95 | |API|Description| 96 | |---|---| 97 | |[`POST /devices/{deviceId}/associate?carId={carId}`](devices/associate_car.md)|Associate a car to the given device| 98 | |[`POST /devices/{deviceId}/associate?pin={pin}`](devices/associate_user.md)|Associate a user to the given device| 99 | |[`POST /devices/{deviceId}/dissociate`](devices/dissociate.md)|Dissociate the given device from it's car| 100 | 101 | ## Errors 102 | 103 | All the errors we throw are mapped on [HTTP Errors codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) 104 | 105 | ### Body 106 | 107 | *Except legacy API*, our **errors body** looks like this: 108 | 109 | > For legacy API, the errors are explained in the content of the description 110 | 111 | ```javascript 112 | [ 113 | { 114 | "type": "ERROR_TYPE", 115 | "message": "Message on the error", 116 | "tip": "How to fix the error" 117 | } 118 | ] 119 | ``` 120 | 121 | ### List of types 122 | 123 | |Type|Description| 124 | |---|---| 125 | |`AUTHENTICATION_ERROR`|Issue with the `Authorization` Header, see more in [Auth README](auth/README.md)| 126 | |`AUTHORIZATION_ERROR`|Issue with the *rights* to access some resources| 127 | |`PARAMETERS_ERROR`|Issue with the *parameters* given in the *API*| 128 | -------------------------------------------------------------------------------- /api/api/v3/auth/README.md: -------------------------------------------------------------------------------- 1 | # Auth 2 | 3 | This is the authentication route of our API. 4 | It is mandatory to go with them in order to get the user data. 5 | 6 | |API|Description| 7 | |---|---| 8 | |[`auth/auth`](auth.md)|For the authentication page| 9 | |[`auth/access_token`](access_token.md)|For the *access token* API| 10 | 11 | 12 | ## Error cases 13 | 14 | The *authentication* gives you the `access_token` needed to access any resource with our API. 15 | 16 | As you'll notice, this `access_token` should be provided with a specific *header*: the `Authorization` Header. 17 | 18 | In almost all our *resource* API, you'll have to specify this *header* 19 | 20 | `Authorization: Bearer HAzsa..AZN` 21 | 22 | There are 3 kind of errors with the `access_token`: 23 | 24 | - It is *missing* 25 | - It is *malformed* 26 | - It is *invalid* 27 | 28 | 29 | |Reason|Status Code|Type|Message|Tip| 30 | |---|---|---|---|---| 31 | |Missing header|`401`|`AUTHENTICATION_ERROR`|Authorization is missing|Add the Authorization header with a valid access_token| 32 | |Malformed Token|`401`|`AUTHENTICATION_ERROR`|Authorization is malformed|Add the Authorization header with a valid access_token| 33 | |Invalid Token|`401`|`AUTHENTICATION_ERROR`|Invalid token|Try to refresh access_token or ask the user to sign-in again| 34 | |Missing scope|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the {neededScope} scope to your app scopes and reconnect the user| 35 | |Expired Token|`403`|`AUTHORIZATION_ERROR`|Token has expired|Refresh the access token and then retry| 36 | |Revoked Token|`403`|`AUTHORIZATION_ERROR`|Token has been revoked|Create a new access token and then retry| -------------------------------------------------------------------------------- /api/api/v3/auth/access_token.md: -------------------------------------------------------------------------------- 1 | # /auth/access_token 2 | 3 | The `access token` route is used to deal with access tokens. You can: 4 | 5 | - Obtain one 6 | - Refresh one 7 | 8 | ## Basics 9 | 10 | `[POST] https://cloud.xee.com/v3/auth/access_token` 11 | 12 | Secured by **Basic** Authorization. 13 | 14 | ## Obtain a fresh token 15 | 16 | ### Headers 17 | 18 | |Header name|Header value|Mandatory| 19 | |---|---|---| 20 | |Authorization|`Basic base64(clientId:clientSecret)` with your client information|YES| 21 | |Content-Type|`application/x-www-form-urlencoded`|YES| 22 | 23 | ### Parameters 24 | 25 | For this request, you'll need *2 POST* parameters. 26 | 27 | |Parameter name|Parameter value| 28 | |---|---| 29 | |`grant_type`|`authorization_code `| 30 | |`code`|The code you've obtained with the [redirect uri](auth.md)| 31 | 32 | 33 | And then `POST` it 34 | 35 | ### Success Response 36 | 37 | - Status Code: `200` 38 | - Body: 39 | 40 | ```javascript 41 | { 42 | "access_token": "22fe0c13e995da4a44a63a7ff549badb5d337a42bf80f17424482e35d4cca91a", 43 | "expires_at": 1382962374, 44 | "expires_in": 3600, 45 | "refresh_token": "8eb667707535655f2d9e14fc6491a59f6e06f2e73170761259907d8de186b6a1", 46 | "token_type": "bearer" 47 | } 48 | ``` 49 | 50 | |Property|Type|Comment| 51 | |---|---|---| 52 | |access_token|string|This is the token you will use to consume our APIs| 53 | |expires_at|date|At this date, the `access_token` won't be useful anymore, you'll need to *refresh it* (see bellow)| 54 | |expires_in|long|This is the life duration of the `access_token` in seconds| 55 | |refresh_token|string|This is very important, it will be used to generate a new `access_token` later| 56 | |token_type|string|The type of the token| 57 | 58 | 59 | ### Errors 60 | 61 | > See how errors are formed in [v3 Readme](../README.md) 62 | 63 | - Reason: If you forgot the `grant_type` or the `code` in the body of the *request* 64 | - Status Code: `400` 65 | - Content 66 | 67 | ```javascript 68 | [ 69 | { 70 | "type": "PARAMETERS_ERROR", 71 | "message": "Missing parameter", 72 | "tip": "Check you've set the grant_type and the code" 73 | } 74 | ] 75 | ``` 76 | --- 77 | - Reason: The `code` you sent in the *request* is not valid 78 | - Status Code: `403` 79 | - Content 80 | 81 | ```javascript 82 | { 83 | "message": "Invalid authentication" 84 | } 85 | ``` 86 | 87 | ## Refreshing a token 88 | 89 | When an `access_token` is not valid anymore, you can *refresh it*. 90 | The system is very similar to the one used to get a token for the first time. 91 | 92 | > The URL is the same 93 | 94 | ### Headers 95 | 96 | |Header name|Header value|Mandatory| 97 | |---|---|---| 98 | |Authorization|`Basic base64(clientId:clientSecret)` with the client information|YES| 99 | |Content-Type|`application/x-www-form-urlencoded`|YES| 100 | 101 | ### Parameters 102 | 103 | For this request, you'll need *2 POST* parameters. 104 | 105 | |Parameter name|Parameter value| 106 | |---|---| 107 | |`grant_type`|`refresh_token`| 108 | |`refresh_token`|The *refresh_token* you saved from the last time you asked one| 109 | 110 | And then `POST` it 111 | 112 | ### Success Response 113 | 114 | - Status Code: `200` 115 | - Body: 116 | 117 | ```javascript 118 | { 119 | "access_token": "22fe0c13e995da4a44a63a7ff549badb5d337a42bf80f17424482e35d4cca91a", 120 | "expires_at": 1382962374, 121 | "expires_in": 3600, 122 | "refresh_token": "8eb667707535655f2d9e14fc6491a59f6e06f2e73170761259907d8de186b6a1", 123 | "token_type": "bearer" 124 | } 125 | ``` 126 | 127 | |Property|Type|Comment| 128 | |---|---|---| 129 | |access_token|string|This is the token you will use to consume our APIs| 130 | |expires_at|date|At this date, the `access_token` won't be useful anymore, you'll need to *refresh it* (see bellow)| 131 | |expires_in|long|This is the life duration of the `access_token` in seconds| 132 | |refresh_token|string|This is very important, it will be used to generate a new `access_token` later| 133 | |token_type|string|The type of the token| 134 | 135 | 136 | ### Errors 137 | 138 | - Reason: If you forgot the `grant_type` or the `code` in the body of the *request* 139 | - Status Code: `400` 140 | - Content 141 | 142 | ```javascript 143 | [ 144 | { 145 | "type": "PARAMETERS_ERROR", 146 | "message": "Missing parameter", 147 | "tip": "Check you've set the grant_type and the refresh_token" 148 | } 149 | ] 150 | ``` 151 | --- 152 | - Reason: The `refresh_token` you sent in the *request* is not valid 153 | - Status Code: `403` 154 | - Content 155 | 156 | ```javascript 157 | { 158 | "message": "Invalid authentication" 159 | } 160 | ``` 161 | ``` 162 | -------------------------------------------------------------------------------- /api/api/v3/auth/auth.md: -------------------------------------------------------------------------------- 1 | # /auth/auth 2 | 3 | This API is used to show the user a webview to sign in. 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/auth/auth?client_id={client_id}&scope={scope}&redirect_uri={redirect_uri}&state={state}` 8 | 9 | Secured by **Nothing** 10 | 11 | ## How it works 12 | 13 | ### Headers 14 | 15 | No headers needed here 16 | 17 | ### Query parameters 18 | 19 | |Parameter name|Parameter value|Mandatory| 20 | |---|---|---| 21 | |`client_id`|The `client id` of your application|YES| 22 | |`scope`|The list of `scopes`, split by a *space* and *url encoded*|NO| 23 | |`redirect_uri`|The `uri` our server will *redirect* to once the user has entered its credentials|NO| 24 | |`state`|An optional state to identify the user from your side|NO| 25 | 26 | 27 | ### Example 28 | 29 | `[GET] https://cloud.xee.com/v3/auth/auth?client_id=azerty&scope=users_read+cars_read` 30 | 31 | This is the *url* to call when your client: 32 | 33 | - Has `azerty` for the client id 34 | - Wants to access `users_read` and `cars_read` scopes 35 | - Has no `redirect URI` 36 | - Has no `state` 37 | 38 | Once the user clicks *Connect*, we will check the user/password and then redirect to **the redirect uri you've specified in developer space** with a `code` 39 | 40 | We'll do thing by setting a `Location` header, for example: 41 | 42 | `Location: [YOUR REDIRECT URI]?code=theawesomecode` 43 | 44 | Or, if you have set multiple `redirect_uri` in the developer space, and you want a specific one to be called: 45 | 46 | `[GET] https://cloud.xee.com/v3/auth/auth?client_id=azerty&redirect_uri=https%3A%2F%2Fexample.com%2Fxee%2Foauth` 47 | 48 | It will do the same but with 49 | 50 | - `https://example.com/xee/oauth` as the `redirect uri` 51 | 52 | ### The redirect uri 53 | 54 | The redirect uri should be owned by you (so either a domain name you own, where you can put some code, either localhost). 55 | 56 | When the redirect uri is called, we'll provide you an `access code`, via the parameter `code`. 57 | 58 | This code will help you to obtain the first `access token` for the user who signed in. 59 | 60 | So keep this code in hand, and then refer to the [access_token](access_token.md) page. 61 | 62 | ### Errors 63 | 64 | If the `client_id` is wrong, or the `redirect_uri` is set but does not match any specified in the [developer space](https://dev.xee.com), we'll throw a `404` 65 | 66 | - Reason: `client_id` does not exist or `redirect_uri` is set but does not match 67 | - Status Code: `404` 68 | - Body: An HTML body with 69 | -------------------------------------------------------------------------------- /api/api/v3/cars/README.md: -------------------------------------------------------------------------------- 1 | # Cars 2 | 3 | Get car data, signals, locations, trips... 4 | 5 | > Don't forget the *signals_read*, *accelerometers_read*, *trips_read*, *locations_read* and *status_read* scopes. 6 | 7 | |API|Description| 8 | |---|---| 9 | |[`/cars/{carId}`](car_id.md)|Get a specific car from its *id*| 10 | |[`/cars/{carId}/status`](status.md)|Get the last status of the car| 11 | |[`/cars/{carId}/locations`](locations.md)|Get raw locations history of the car| 12 | |[`/cars/{carId}/locations.geojson`](locations-geojson.md)|Get car *locations* history in a [geojson](http://geojson.org/) format| 13 | |[`/cars/{carId}/signals`](signals.md)|Get raw signals history of the car| 14 | |[`/cars/{carId}/trips`](trips.md)|Get the car *trips*| 15 | |[`/cars/{carId}/stats/mileage`](stats/mileage.md)|Get car *mileage* statistic| 16 | |[`/cars/{carId}/stats/usedtime`](stats/usedtime.md)|Get car *used time* statistic| 17 | 18 | ## Signals list 19 | 20 | For the `signals` API, you might want to specify some filters. 21 | See [The list of available signals](signals_list.md) -------------------------------------------------------------------------------- /api/api/v3/cars/car_id.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId} 2 | 3 | Get a specific *car* from its `id` 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}` 8 | 9 | > You'll need the *cars_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`carId`|The `id` of the car you are looking for|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "id": 1337, 44 | "name": "Mark-42", 45 | "make": "Mark", 46 | "model": "42", 47 | "year": 2014, 48 | "numberPlate": "M-42-TS", 49 | "deviceId": "E133742015", 50 | "cardbId": 210, 51 | "creationDate": "2014-09-23T12:49:48+00:00", 52 | "lastUpdateDate": "2016-02-19T08:41:58+00:00" 53 | } 54 | ``` 55 | 56 | |Property|Type|Comment| 57 | |---|---|---| 58 | |id|integer|| 59 | |name|string|| 60 | |make|string|Might be `generic`| 61 | |model|string|Might be `null`| 62 | |year|integer|Might be `0`| 63 | |numberPlate|string|Might be `null`| 64 | |deviceId|string|The `serial number` of the device. Might be `null` if the car has no device associated| 65 | |cardbId|integer|Represents the type of the *car* from our point of view, that's how we speak to them| 66 | |creationDate|date|| 67 | |lastUpdateDate|date|| 68 | 69 | ## Errors 70 | 71 | > See how errors are formed in [v3 Readme](../README.md) 72 | 73 | > Be aware of [authentication errors](../auth/README.md) 74 | 75 | |Reason|Status Code|Type|Message|Tip| 76 | |---|---|---|---|---| 77 | |Scope `cars_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the cars_read scope to your app scopes and reconnect the user| 78 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 79 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/cars/locations-geojson.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/locations.geojson 2 | 3 | Get the locations history from a specific *car* as an array of [Geojson points](http://geojson.org/geojson-spec.html#id2) 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/locations.geojson?limit={limit}&begin={begin}&end={end}` 8 | 9 | > You'll need the *locations_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the *locations*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`limit`|The maximum number of locations you want in return|NO| 43 | |`begin`|The start of the interval when you want the *locations*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 44 | |`end`|The end of the interval when you want the *locations*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 45 | 46 | ## Success Response 47 | 48 | - Status Code: `200` 49 | - Body: 50 | 51 | ```javascript 52 | [ 53 | { 54 | "type": "Point", 55 | "coordinates": [ 56 | 3.0508652, 50.68075 57 | ] 58 | } 59 | ] 60 | ``` 61 | 62 | |Property|Type|Comment| 63 | |---|---|---| 64 | |type|string|The type of the Geojson object| 65 | |coordinates|array|Array of Points of the trip (longitude, latitude| 66 | 67 | ## Errors 68 | 69 | > See how errors are formed in [v3 Readme](../README.md) 70 | 71 | > Be aware of [authentication errors](../auth/README.md) 72 | 73 | |Reason|Status Code|Type|Message|Tip| 74 | |---|---|---|---|---| 75 | |The limit parameter is wrong|`400`|`PARAMETERS_ERROR`|Limit can't be less than 0|The limit in parameter must ben a positive integer| 76 | |Scope `locations_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the locations_read scope to your app scopes and reconnect the user| 77 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 78 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 79 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 80 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/cars/locations.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/locations 2 | 3 | Get the locations history from a specific *car* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/locations?limit={limit}&begin={begin}&end={end}` 8 | 9 | > You'll need the *locations_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the *locations*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`limit`|The maximum number of locations you want in return|NO| 43 | |`begin`|The start of the interval when you want the *locations*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 44 | |`end`|The end of the interval when you want the *locations*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 45 | 46 | ## Success Response 47 | 48 | - Status Code: `200` 49 | - Body: 50 | 51 | ```javascript 52 | [ 53 | { 54 | "latitude": 50.67815, 55 | "longitude": 3.208155, 56 | "altitude": 31.8, 57 | "satellites": 4, 58 | "heading": 167, 59 | "date": "2016-03-01T02:24:20.000000+00:00" 60 | }, 61 | { 62 | ... 63 | } 64 | ] 65 | ``` 66 | 67 | |Property|Type|Comment| 68 | |---|---|---| 69 | |latitude|float|| 70 | |longitude|float|| 71 | |altitude|float|| 72 | |satellites|integer|Number of satellites used to determine location| 73 | |heading|integer|direction| 74 | |date|date|the date when the location has been found| 75 | 76 | ## Errors 77 | 78 | > See how errors are formed in [v3 Readme](../README.md) 79 | 80 | > Be aware of [authentication errors](../auth/README.md) 81 | 82 | |Reason|Status Code|Type|Message|Tip| 83 | |---|---|---|---|---| 84 | |The limit parameter is wrong|`400`|`PARAMETERS_ERROR`|Limit can't be less than 0|The limit in parameter must ben a positive integer| 85 | |Scope `locations_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the locations_read scope to your app scopes and reconnect the user| 86 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 87 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 88 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 89 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/cars/signals.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/signals 2 | 3 | Get all signals (data) history from a specific *car* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/signals?limit={limit}&begin={begin}&end={end}&name={name1},{etc...}` 8 | 9 | > You'll need the *signals_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max interval per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the *signals*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`limit`|The maximum number of signals you want in return|NO| 43 | |`begin`|The start of the interval when you want the *signals*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 44 | |`end`|The end of the interval when you want the *signals*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 45 | |`name`|The list of *signals* you want, for example, if you want `LockSts` and `Odometer`, you'll have `name=LockSts,Odometer`, by default, all the signals available are sent back. You can see the [full list here](signals_list.md)|NO| 46 | 47 | ## Success Response 48 | 49 | - Status Code: `200` 50 | - Body: 51 | 52 | ```javascript 53 | [ 54 | { 55 | "name": "LockSts", 56 | "value": 0, 57 | "date": "2016-03-01T02:24:24.000000+00:00" 58 | }, 59 | { 60 | "name": "Odometer", 61 | "value": 34512.1, 62 | "date": "2016-03-01T02:24:27.116000+00:00" 63 | }, 64 | { 65 | ... 66 | } 67 | ] 68 | ``` 69 | 70 | |Property|Type|Comment| 71 | |---|---|---| 72 | |name|string|The name of the signal| 73 | |value|float|The value of the signal| 74 | |date|date|the date when the signal has been updated| 75 | 76 | 77 | ## Errors 78 | 79 | > See how errors are formed in [v3 Readme](../README.md) 80 | 81 | > Be aware of [authentication errors](../auth/README.md) 82 | 83 | |Reason|Status Code|Type|Message|Tip| 84 | |---|---|---|---|---| 85 | |The limit parameter is wrong|`400`|`PARAMETERS_ERROR`|Limit can't be less than 0|The limit in parameter must ben a positive integer| 86 | |Any signal in parameter is a valid signal name|`400`|`PARAMETERS_ERROR`|Wrong signal name|Can't find any signals with those names| 87 | |Scope `signals_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the signals_read scope to your app scopes and reconnect the user| 88 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 89 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 90 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 91 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/cars/signals_list.md: -------------------------------------------------------------------------------- 1 | # Signals list 2 | 3 | All the *signals* you can access via the [signals API](signals.md) 4 | 5 | > All the *signals* ending by `Sts` are *status signals*, it means that their value is `0` or `1` like `booleans` 6 | 7 | ## Standard Signals 8 | 9 | > See the human readable list in [https://dev.xee.com/signals](https://dev.xee.com/signals) 10 | > 11 | > The list here represents the *Standard Signals* 12 | 13 | |Signal name|Signal description|Comment| 14 | |---|---|---| 15 | |**_XeeCONNECT_**||| 16 | |`BatteryVoltage`|Represents the **Battery Voltage** value|Value is in `V`| 17 | |**_Lights_**||| 18 | |`FrontFogLightSts`|Represents the **Front fog lights** status|`0` = `off`,
`1` = `on`| 19 | |`RearFogLightSts`|Represents the **Rear fog lights** status|`0` = `off`,
`1` = `on`| 20 | |`HazardSts`|Represents the **Warnings** status|`0` = `off`,
`1` = `on`| 21 | |`HeadLightSts`|Represents the **Head Lights** status|`0` = `off`,
`1` = `on`| 22 | |`HighBeamSts`|Represents the **High Beams** status|`0` = `off`,
`1` = `on`| 23 | |`LowBeamSts`|Represents the **Low Beams** status|`0` = `off`,
`1` = `on`| 24 | |`LeftIndicatorSts`|Represents the **Left indicator** status|`0` = `off`,
`1` = `on`| 25 | |`RightIndicatorSts`|Represents the **Right indicator** status|`0` = `off`,
`1` = `on`| 26 | |**_Misc_**||| 27 | |`FuelLevel`|Represents the amout of **Fuel** in the tank|Value is in `L`| 28 | |`IgnitionSts`|Represents the **Ignition** status|`0` = `off`,
`1` = `on`| 29 | |`Odometer`|Represents the **Odometer** value|Value is in `km`| 30 | |`LockSts`|Represents the **Lock** status of the car|`0` = `unlocked`,
`1` = `locked`| 31 | |**_Wipers_**||| 32 | |`IntermittentWiperSts`|Represents the **Intermittent Wipers** status|`0` = `off`,
`1` = `on`| 33 | |`ManualWiperSts`|Represents the **Manual Wipers** status|`0` = `off`,
`1` = `on`| 34 | |`LowSpeedWiperSts`|Represents the **Low speed Wipers** status|`0` = `off`,
`1` = `on`| 35 | |`HighSpeedWiperSts`|Represents the **High speed Wipers** status|`0` = `off`,
`1` = `on`| 36 | |`AutoWiperSts`|Represents the **Auto automatic Wipers activation ** status|`0` = `off`,
`1` = `on`| 37 | |`RearWiperSts`|Represents the **Rear Wipers** status|`0` = `off`,
`1` = `on`| 38 | |**_Speed_**||| 39 | |`EngineSpeed`|Represents the **Engine speed**|Value is in `rpm`| 40 | |`VehiculeSpeed`|Represents the **Vehicle speed**|Value is in `km/h`| 41 | |**_Computed_**||| 42 | |`ComputedFuelLevel`|A smoothed value of the `FuelLevel` computed by *XeeCLOUD* [see notes](https://medium.com/@XeeTech/f2a227780f78)|Value is in `L`| 43 | 44 | ## Advanced Signals 45 | 46 | > See the human readable list in [https://dev.xee.com/signals](https://dev.xee.com/signals) 47 | > 48 | > The list here represents the *Advanced Signals*, note that **THEY ARE NOT AVAILABLE BY DEFAULT** 49 | 50 | |Signal name|Signal description|Comment| 51 | |---|---|---| 52 | |**_Air Conditioning_**||| 53 | |`AirCondSwitchSts`|Represents the **Air conditioning** status|`0` = `off`,
`1` = `on`| 54 | |`CoolantPressure`|Represents the **Coolant Pressure**|Value is in `bar`| 55 | |`OutdoorTemp`|Represents the **Outdoor temperature**|Value is in `° C`| 56 | |`VentilationSts`|Represents the **Ventilation** status |`0` = `off`,
`1` = `on`| 57 | |**_Binnacle_**||| 58 | |`CruiseControlSts`|Represents the **Cruise control** status|`0` = `off`,
`1` = `on`| 59 | |`KeySts`|Represents the **Key presence** status|`0` = `absent`,
`1` = `present`| 60 | |`ReverseGearSts`|Represents the **Reverse Gear** status |`0` = `off`,
`1` = `on`| 61 | |**_Doors and Caps_**||| 62 | |`FrontLeftDoorSts`|Represents the **Front left door** status |`0` = `closed`,
`1` = `open`| 63 | |`HoodSts`|Represents the **Hood** status |`0` = `closed`,
`1` = `open`| 64 | |`FrontRightDoorSts`|Represents the **Front right door** status |`0` = `closed`,
`1` = `open`| 65 | |`RearLeftDoorSts`|Represents the **Rear Left door** status |`0` = `closed `,
`1` = `open`| 66 | |`RearRightDoorSts`|Represents the **Rear Right door** status |`0` = `closed`,
`1` = `open`| 67 | |`TrunkSts`|Represents the **Trunk** status |`0` = `closed`,
`1` = `open`| 68 | |**_Electrical Vehicle_**||| 69 | |`EVBatterySOC`|Represents the **Battery charge** state|Value is in `%`| 70 | |`EVBatteryVoltage`|Represents the **Battery voltage**|Value is in `V`| 71 | |`EVBatteryHealth`|Represents the **Battery health** state|Value is in `%`| 72 | |`EVChargerSts`|Represents the **Charger** status|`0` = `unplugged`,
`1` = `plugged`| 73 | |`EVChargingSts`|Represents the **Charging** status|`0` = `not charging`,
`1` = `charging`| 74 | |`EVRemainingChargeTime`|Represents the **Remaining charge time**|Value is in `min`| 75 | |`EVRemainingRange`|Represents the **Remaining range** distrance|Value is in `km`| 76 | |**_Pedals_**||| 77 | |`BrakePedalSts`|Represents the **Brake Pedal** status |`0` = `released`,
`1` = `pressed`| 78 | |`BrakePedalPosition`|Represents the **Brake Pedal** position|Value is in `%`
(*0%* = *released*, *100%* = *fully pressed*)| 79 | |`ClutchPedalSts`|Represents the **Clutch Pedal** status |`0` = `released`,
`1` = `pressed`| 80 | |`ClutchPedalPosition`|Represents the **Clutch Pedal** position |Value is in `%`
(*0%* = *released*, *100%* = *fully pressed*)| 81 | |`HandBrakeSts`|Represents the **Hand Brake** status|`0` = `released`,
`1` = `engaged`| 82 | |`ThrottlePedalSts`|Represents the **Throttle Pedal** status |`0` = `released`,
`1` = `pressed`
(*0%* = *released*, *100%* = *fully pressed*)| 83 | |`ThrottlePedalPosition`|Represents the **Throttle Pedal** position |Value is in `%`
(*0%* = *released*, *100%* = *fully pressed*)| 84 | |**_Safety_**||| 85 | |`FrontLeftSeatBeltSts`|Represents the **Front Left Seat belt** status |`0` = `unfasten`,
`1` = `fasten`| 86 | |`FrontRightSeatBeltSts`|Represents the **Front Right seat belt** status |`0` = `unfasten`,
`1` = `fasten`| 87 | |`PassAirbagSts`|Represents the **Passenger's Airbag** status |`0` = `activated`,
`1` = `disabled`| 88 | |**_Steering Wheel_**||| 89 | |`SteeringWheelAngle`|Represents the **Steering Wheel Angle** |Value is in `°`
(from *0°* to *???°* depends on vehicle)| 90 | |`SteeringWheelSide`|Represents the **Steering Wheel Side** |`0` = `left`,
`1` = `right`| 91 | |**_Windows_**||| 92 | |`FrontLeftWindowSts`|Represents the **Front Left Window** status |`0` = `closed`,
`1` = `open`| 93 | |`FrontLeftWindowPosition`|Represents the **Front Left Window** position |Value is in `%`
(of opening *0%* = *closed*, *100%* = *fully open*)| 94 | |`FrontRightWindowSts`|Represents the **Front Right Window** status |`0` = `closed `,
`1` = `closed`| 95 | |`FrontRightWindowPosition`|Represents the **Front Right Window** position |Value is in `%`
(of opening *0%* = *closed*, *100%* = *fully open*)| 96 | |`RearLeftWindowSts`|Represents the **Rear Left Window** status |`0` = `closed`,
`1` = `open`| 97 | |`RearLeftWindowPosition`|Represents the **Rear Left Window** position |Value is in `%`
(of opening *0%* = *closed*, *100%* = *fully open*)| 98 | |`RearRightWindowSts`|Represents the **Rear Right Window** status |`0` = `closed`,
`1` = `open`| 99 | |`RearRightWindowPosition`|Represents the **Rear Right Window** position |Value is in `%`
(of opening *0%* = *closed*, *100%* = *fully open*)| 100 | |`WindowsLockSts`|Represents the **Windows Lock** status |`0` = `released`,
`1` = `locked`| 101 | |**_Speed_**||| 102 | |`FrontLeftWheelSpeed`|Represents the **Front Left Wheel** speed |Value is in `km/h`| 103 | |`FrontRightWheelSpeed `|Represents the **Front Right Wheel** speed |Value is in `km/h`| 104 | |`RearLeftWheelSpeed `|Represents the **Rear Left Wheel** speed |Value is in `km/h`| 105 | |`RearRightWheelSpeed `|Represents the **Rear Right Wheel** speed |Value is in `km/h`| 106 | -------------------------------------------------------------------------------- /api/api/v3/cars/stats/mileage.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/stats/mileage 2 | 3 | Get the *mileage* value for a specific *car* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/stats/mileage?begin={begin}&end={end}&initialValue={initialValue}` 8 | 9 | > You'll need the *signals_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max interval per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the *mileage*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`begin`|The start of the interval when you want the *mileage* to be computed, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 43 | |`end`|The end of the interval when you want the *mileage* to be computed, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 44 | |`initialValue`|An offset to add to the mileage stat. Default value is **0**|NO| 45 | 46 | ## Success Response 47 | 48 | - Status Code: `200` 49 | - Body: 50 | 51 | ```javascript 52 | { 53 | "beginDate": "2016-07-01T00:00:00Z", 54 | "endDate": "2016-07-15T12:34:30.447653854Z", 55 | "type": "MILEAGE", 56 | "value": 4.2 57 | } 58 | ``` 59 | 60 | |Property|Type|Comment| 61 | |---|---|---| 62 | |beginDate|date|the date when the mileage compute has started| 63 | |endDate|date|the date when the mileage compute has ended| 64 | |type|string|the type of stat, here `MILEAGE`| 65 | |value|double|the *mileage* in *km* between the dates (plus optional initial value)| 66 | 67 | ## Errors 68 | 69 | > See how errors are formed in [v3 Readme](../../README.md) 70 | 71 | > Be aware of [authentication errors](../../auth/README.md) 72 | 73 | |Reason|Status Code|Type|Message|Tip| 74 | |---|---|---|---|---| 75 | |Scope `signals_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the signals_read scope to your app scopes and reconnect the user| 76 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 77 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 78 | |The statistic does not exist|`404`|`PARAMETERS_ERROR`|Statistics not found|Please check that the car exists and data are present, looks like it does not| 79 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 80 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/cars/stats/usedtime.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/stats/usedtime 2 | 3 | Get the *used time* value for a specific *car* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/stats/usedtime?begin={begin}&end={end}&initialValue={initialValue}` 8 | 9 | > You'll need the *signals_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max interval per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the *used time*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`begin`|The start of the interval when you want the *used time* to be computed, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 43 | |`end`|The end of the interval when you want the *used time* to be computed, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 44 | |`initialValue`|An offset to add to the used time stat (in *seconds*). Default value is **0**|NO| 45 | 46 | ## Success Response 47 | 48 | - Status Code: `200` 49 | - Body: 50 | 51 | ```javascript 52 | { 53 | "beginDate": "2016-07-01T00:00:00Z", 54 | "endDate": "2016-07-15T12:34:30.447653854Z", 55 | "type": "USED_TIME", 56 | "value": 4200 57 | } 58 | ``` 59 | 60 | |Property|Type|Comment| 61 | |---|---|---| 62 | |beginDate|date|the date when the used time compute has started| 63 | |endDate|date|the date when the used time compute has ended| 64 | |type|string|the type of stat, here `USED_TIME`| 65 | |value|double|the *used time* in *seconds* between the dates (plus optional initial value)| 66 | 67 | ## Errors 68 | 69 | > See how errors are formed in [v3 Readme](../../README.md) 70 | 71 | > Be aware of [authentication errors](../../auth/README.md) 72 | 73 | |Reason|Status Code|Type|Message|Tip| 74 | |---|---|---|---|---| 75 | |Scope `signals_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the signals_read scope to your app scopes and reconnect the user| 76 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 77 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 78 | |The statistic does not exist|`404`|`PARAMETERS_ERROR`|Statistics not found|Please check that the car exists and data are present, looks like it does not| 79 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 80 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/cars/status.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/status 2 | 3 | Get the current *status* of a specific car 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/status` 8 | 9 | > You'll need the *status_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`carId`|The `id` of the car you are looking for the *status*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "accelerometer": { 44 | "x": -768, 45 | "y": 240, 46 | "z": 4032, 47 | "date": "2016-03-01T02:24:20.000000+00:00" 48 | }, 49 | "location": { 50 | "latitude": 50.67815, 51 | "longitude": 3.208155, 52 | "altitude": 31.8, 53 | "satellites": 4, 54 | "heading": 167, 55 | "date": "2016-03-01T02:24:20.000000+00:00" 56 | }, 57 | "signals": [ 58 | { 59 | "name": "LockSts", 60 | "value": 0, 61 | "date": "2016-03-01T02:24:24.000000+00:00" 62 | }, 63 | { 64 | "name": "Odometer", 65 | "value": 34512.1, 66 | "date": "2016-03-01T02:24:27.116000+00:00" 67 | }, 68 | ... 69 | ] 70 | } 71 | ``` 72 | 73 | |Property|Type|Comment| 74 | |---|---|---| 75 | |location|location|More on [Locations API page](locations.md)| 76 | |accelerometer|accelerometer|| 77 | |signals|signal|More on [Signals API page](signals.md)| 78 | 79 | ## Errors 80 | 81 | > See how errors are formed in [v3 Readme](../README.md) 82 | 83 | > Be aware of [authentication errors](../auth/README.md) 84 | 85 | |Reason|Status Code|Type|Message|Tip| 86 | |---|---|---|---|---| 87 | |Scope `status_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the status_read scope to your app scopes and reconnect the user| 88 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 89 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 90 | 91 | -------------------------------------------------------------------------------- /api/api/v3/cars/trips.md: -------------------------------------------------------------------------------- 1 | # /cars/{carId}/trips 2 | 3 | Get the trips history from a specific *car* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/cars/{carId}/trips?begin={begin}&end={end}` 8 | 9 | > You'll need the *trips_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | > Be aware you can only request one month max interval per request 14 | 15 | ## Request 16 | 17 | ### Environment 18 | 19 | The `env` variable as the host of the route can be changed for testing purpose. 20 | 21 | |Value|Comment| 22 | |---|---| 23 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 24 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 25 | 26 | ### Headers 27 | 28 | |Header name|Header value|Mandatory| 29 | |---|---|---| 30 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 31 | 32 | ### Url Parameters 33 | 34 | |Parameter name|Parameter value|Mandatory| 35 | |---|---|---| 36 | |`carId`|The `id` of the car you are looking for the * trips*|YES| 37 | 38 | ### Query Parameters 39 | 40 | |Parameter name|Parameter value|Mandatory| 41 | |---|---|---| 42 | |`begin`|The start of the interval when you want the *trips*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **First day of month at 00:00:00+00:00**|NO| 43 | |`end`|The end of the interval when you want the *trips*, Format is `2016-04-20T13:37:42Z(+/-HH:mm)` default value is **Current moment when you send request**|NO| 44 | |`inclusive`|If set to `true`, all the trips started __or__ ended between `begin` and `end` will be returned. If set to `false` (*default value*), only the trips started __and__ ended between `begin` and `end` will be returned.|NO 45 | 46 | 47 | ## Success Response 48 | 49 | - Status Code: `200` 50 | - Body: 51 | 52 | ```javascript 53 | [ 54 | { 55 | "id": "56b43a4f051f29071f14218d", 56 | "beginLocation": { 57 | "latitude": 50.6817, 58 | "longitude": 3.08202, 59 | "altitude": 2, 60 | "heading": 0, 61 | "satellites": 1, 62 | "date": "2016-01-29T18:36:17Z" 63 | }, 64 | "endLocation": { 65 | "latitude": 50.6817, 66 | "longitude": 3.08202, 67 | "altitude": 2, 68 | "heading": 0, 69 | "satellites": 1, 70 | "date": "2016-01-29T18:36:17Z" 71 | }, 72 | "beginDate": "2016-01-29T18:39:17Z", 73 | "endDate": "2016-01-29T19:15:15Z" 74 | }, 75 | { 76 | ... 77 | } 78 | ] 79 | ``` 80 | 81 | |Property|Type|Comment| 82 | |---|---|---| 83 | |id|string|An id for the trip| 84 | |beginLocation|location|The first *location* of the trip| 85 | |endLocation|location|The last *location* of the trip| 86 | |beginDate|date|the date when the trip has started| 87 | |endDate|date|the date when the trip has stoped| 88 | 89 | ## Errors 90 | 91 | > See how errors are formed in [v3 Readme](../README.md) 92 | 93 | > Be aware of [authentication errors](../auth/README.md) 94 | 95 | |Reason|Status Code|Type|Message|Tip| 96 | |---|---|---|---|---| 97 | |Scope `trips_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the trips_read scope to your app scopes and reconnect the user| 98 | |The token does not have access to this car|`403`|`AUTHORIZATION_ERROR`|Token can't access this car|Make sure the token belongs to the user owning the car you're asking for| 99 | |The car does not exist|`404`|`PARAMETERS_ERROR`|Car not found|Please check that the car exists, looks like it does not| 100 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 101 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/devices/README.md: -------------------------------------------------------------------------------- 1 | # Devices 2 | 3 | Interact with device. These routes are quite private, and the required scope to call them is not accessible to all the applications. 4 | 5 | > Don't forget the *devices_management* scope. 6 | 7 | |API|Description| 8 | |---|---| 9 | |[`POST /devices/{deviceId}/associate?carId={carId}`](associate_car.md)|Associate a car to the given device| 10 | |[`POST /devices/{deviceId}/associate?pin={pin}`](associate_user.md)|Associate a user to the given device| 11 | |[`POST /devices/{deviceId}/dissociate`](dissociate.md)|Dissociate the given device from it's car| 12 | -------------------------------------------------------------------------------- /api/api/v3/devices/associate_car.md: -------------------------------------------------------------------------------- 1 | # POST /devices/{xeeId}/associate?carId={carId} 2 | 3 | Associate a car and a device specified by its `deviceId` 4 | 5 | ## Basics 6 | 7 | `[POST] https://{env}.xee.com/v3/devices/{deviceId}/associate?carId={carId}` 8 | 9 | > You'll need the *devices_management* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`deviceId`|The `id` of the device you want to associate|YES| 35 | 36 | ### Query Parameters 37 | 38 | |Parameter name|Parameter value|Mandatory| 39 | |---|---|---| 40 | |`carId`|The id of the car you want to associate with the current user|YES| 41 | 42 | 43 | ### Body 44 | 45 | No body expected. 46 | 47 | ## Success Response 48 | 49 | - Status Code: `204` 50 | 51 | ## Errors 52 | 53 | > See how errors are formed in [v3 Readme](../README.md) 54 | 55 | > Be aware of [authentication errors](../auth/README.md) 56 | 57 | |Reason|Status Code|Type|Message|Tip| 58 | |---|---|---|---|---| 59 | |Wrong device id format, or wrong carId format, or wrong carId|`400`|`PARAMETER_ERROR`||Check the device id, or the car id| 60 | |Scope `devices_management` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the devices_management scope to your app scopes and reconnect the user| 61 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the user is accessible with this token| 62 | |Device or car or user does not exist|`404`|`NOT_FOUND`|Device or car or user not found|Please check that the device exists, looks like it does not| 63 | |Device already associated|`409`|`CONFLICT`|The box is not already associated to a user|| 64 | -------------------------------------------------------------------------------- /api/api/v3/devices/associate_user.md: -------------------------------------------------------------------------------- 1 | # POST /devices/{xeeId}/associate?pin={pin} 2 | 3 | Associate a user and a device specified by its `deviceId` 4 | 5 | ## Basics 6 | 7 | `[POST] https://{env}.xee.com/v3/devices/{deviceId}/associate?pin={pin}` 8 | 9 | > You'll need the *devices_management* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`deviceId`|The `id` of the device you want to associate|YES| 35 | 36 | ### Query Parameters 37 | 38 | |Parameter name|Parameter value|Mandatory| 39 | |---|---|---| 40 | |`pin`|The pin code of the device to associate with the current user|YES| 41 | 42 | 43 | ### Body 44 | 45 | No body expected. 46 | 47 | ## Success Response 48 | 49 | - Status Code: `204` 50 | 51 | ## Errors 52 | 53 | > See how errors are formed in [v3 Readme](../README.md) 54 | 55 | > Be aware of [authentication errors](../auth/README.md) 56 | 57 | |Reason|Status Code|Type|Message|Tip| 58 | |---|---|---|---|---| 59 | |Wrong device id format, or wrong pin format, or wrong pin code|`400`|`PARAMETER_ERROR`||Check the device id and the pin| 60 | |Scope `devices_management` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the devices_management scope to your app scopes and reconnect the user| 61 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the user is accessible with this token| 62 | |Too many association attempts|`403`|`AUTHORIZATION_ERROR`|The box association already failed 3 times|| 63 | |Device or user does not exist|`404`|`NOT_FOUND`|Device or user not found|Please check that the device exists, looks like it does not| 64 | |Device already associated|`409`|`CONFLICT`|Device already associated to another user|| 65 | -------------------------------------------------------------------------------- /api/api/v3/devices/dissociate.md: -------------------------------------------------------------------------------- 1 | # POST /devices/{xeeId}/dissociate 2 | 3 | Dissociate the device specified by its `deviceId` and the car 4 | 5 | ## Basics 6 | 7 | `[POST] https://{env}.xee.com/v3/devices/{deviceId}/dissociate` 8 | 9 | > You'll need the *devices_management* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`deviceId`|The `id` of the device you want to dissociate|YES| 35 | 36 | ### Body 37 | 38 | No body expected. 39 | 40 | ## Success Response 41 | 42 | - Status Code: `204` 43 | 44 | ## Errors 45 | 46 | > See how errors are formed in [v3 Readme](../README.md) 47 | 48 | > Be aware of [authentication errors](../auth/README.md) 49 | 50 | |Reason|Status Code|Type|Message|Tip| 51 | |---|---|---|---|---| 52 | |Wrong device id format|`400`|`PARAMETER_ERROR`||Check the device id| 53 | |Scope `devices_management` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the devices_management scope to your app scopes and reconnect the user| 54 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the user is accessible with this token| 55 | |Device or car does not exist|`404`|`NOT_FOUND`|Device or car not found|Please check that the device exists, looks like it does not| 56 | |Device not associated|`409`|`CONFLICT`|The box is not already associated to a user|| 57 | -------------------------------------------------------------------------------- /api/api/v3/trips/README.md: -------------------------------------------------------------------------------- 1 | # Trips 2 | 3 | Get the trips data, signals, locations, trips... 4 | 5 | > Don't forget the *signals_read*, *locations_read* and *trips_read* scopes. 6 | 7 | |API|Information| 8 | |---|---| 9 | |[`/trips/{tripId}`](trip_id.md)|Get a specific *trip*| 10 | |[`/trips/{tripId}/locations`](locations.md)|Get a specific *trip* locations collection| 11 | |[`/trips/{tripId}/locations.geojson`](locations-geojson.md)|Get all locations from a *car* during a specific *trip* in a [geojson](http://geojson.org/) format| 12 | |[`/trips/{tripId}/signals`](signals.md)|Get a specific *trip* signals history| 13 | |[`/trips/{tripId}/stats`](trip_id/stats.md)|Get a specific *trip* statistics| 14 | |[`/trips/{tripId}/stats/mileage`](trip_id/stats/mileage.md)|Get a specific *trip* mileage| 15 | |[`/trips/{tripId}/stats/usedtime`](trip_id/stats/usedtime.md)|Get a specific *trip* duration| 16 | 17 | ## Signals list 18 | 19 | For the `signals` API, you might want to specify some filters. 20 | See [The list of available signals](../cars/signals_list.md) -------------------------------------------------------------------------------- /api/api/v3/trips/locations-geojson.md: -------------------------------------------------------------------------------- 1 | # /trips/{tripId}/locations.geojson 2 | 3 | Get the locations history from a specific *trip as a [Geojson LineString](http://geojson.org/geojson-spec.html#id3)* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/locations.geojson` 8 | 9 | > You'll need the, *trips_read* and *locations_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the *trip* you are looking for the *locations*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "type": "LineString", 44 | "coordinates":[ 45 | [3.0580485, 50.632244] 46 | ] 47 | } 48 | ``` 49 | 50 | 51 | 52 | |Property|Type|Comment| 53 | |---|---|---| 54 | |type|string|The type of the Geojson object| 55 | |coordinates|array|Array of Array of Points of the trip (longitude, latitude)| 56 | 57 | ## Errors 58 | 59 | > See how errors are formed in [v3 Readme](../README.md) 60 | 61 | > Be aware of [authentication errors](../auth/README.md) 62 | 63 | |Reason|Status Code|Type|Message|Tip| 64 | |---|---|---|---|---| 65 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the trip belongs to the user you've got the token from| 66 | |Trip does not exist|`404`|`PARAMETERS_ERROR`|Trip not found|Please check that the trip exists, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/trips/locations.md: -------------------------------------------------------------------------------- 1 | # /trips/{tripId}/locations 2 | 3 | Get the locations history from a specific *trip* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/locations` 8 | 9 | > You'll need the, *trips_read* and *locations_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the *trip* you are looking for the *locations*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | [ 43 | { 44 | "latitude": 50.67815, 45 | "longitude": 3.208155, 46 | "altitude": 31.8, 47 | "satellites": 4, 48 | "heading": 167, 49 | "date": "2016-03-01T02:24:20.000000+00:00" 50 | }, 51 | { 52 | ... 53 | } 54 | ] 55 | ``` 56 | 57 | |Property|Type|Comment| 58 | |---|---|---| 59 | |latitude|float|| 60 | |longitude|float|| 61 | |altitude|float|| 62 | |satCount|integer|Number of satellites used to determine location| 63 | |heading|integer|Direction| 64 | |date|date|the date when the location has been found| 65 | 66 | 67 | ## Errors 68 | 69 | > See how errors are formed in [v3 Readme](../README.md) 70 | 71 | > Be aware of [authentication errors](../auth/README.md) 72 | 73 | > It uses [location API](../cars/locations.md) with pre filled parameters 74 | 75 | |Reason|Status Code|Type|Message|Tip| 76 | |---|---|---|---|---| 77 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the trip belongs to the user you've got the token from| 78 | |Trip does not exist|`404`|`PARAMETERS_ERROR`|Trip not found|Please check that the trip exists, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/trips/signals.md: -------------------------------------------------------------------------------- 1 | # /trips/{tripId}/signals 2 | 3 | Get all signals history from a specific *trip* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/signals?name={name1},{etc...}` 8 | 9 | > You'll need the *trips_read*, *signals_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the *trip* you are looking for the * signals*|YES| 35 | 36 | ### Query Parameters 37 | 38 | |Parameter name|Parameter value|Mandatory| 39 | |---|---|---| 40 | |`name`|The list of *signals* you want, for example, if you want `ComputedFuelLevel` and `Odometer`, you'll have `?name=ComputedFuelLevel,Odometer`, by default, all the signals available are sent back. You can see the [full list here](../cars/signals_list.md)|NO| 41 | 42 | ## Success Response 43 | 44 | - Status Code: `200` 45 | - Body: 46 | 47 | ```javascript 48 | [ 49 | { 50 | "name": "ComputedFuelLevel", 51 | "value": 25, 52 | "date": "2016-03-01T02:24:24.000000+00:00" 53 | }, 54 | { 55 | "name": "Odometer", 56 | "value": 34512.1, 57 | "date": "2016-03-01T02:24:27.116000+00:00" 58 | }, 59 | ... 60 | ] 61 | ``` 62 | 63 | |Property|Type|Comment| 64 | |---|---|---| 65 | |name|string|The name of the signal| 66 | |value|float|The value of the signal| 67 | |date|date|the date when the signal has been updated| 68 | 69 | ## Errors 70 | 71 | > See how errors are formed in [v3 Readme](../README.md) 72 | 73 | > Be aware of [authentication errors](../auth/README.md) 74 | 75 | > It uses [signals API](../cars/signals.md) with pre filled parameters 76 | 77 | |Reason|Status Code|Type|Message|Tip| 78 | |---|---|---|---|---| 79 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the trip belongs to the user you've got the token from| 80 | |Trip does not exist|`404`|`PARAMETERS_ERROR`|Trip not found|Please check that the trip exists, looks like it does not| 81 | -------------------------------------------------------------------------------- /api/api/v3/trips/trip_id.md: -------------------------------------------------------------------------------- 1 | # /trips/{tripId} 2 | 3 | Get a specific trip 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}` 8 | 9 | > You'll need the *trips_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the trip you are looking for|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "id": "56b43a4f051f29071f14218d", 44 | "beginLocation": { 45 | "latitude": 50.6817, 46 | "longitude": 3.08202, 47 | "altitude": 2, 48 | "heading": 0, 49 | "satellites": 1, 50 | "date": "2016-01-29T18:36:17Z" 51 | }, 52 | "endLocation": { 53 | "latitude": 50.6817, 54 | "longitude": 3.08202, 55 | "altitude": 2, 56 | "heading": 0, 57 | "satellites": 1, 58 | "date": "2016-01-29T18:36:17Z" 59 | }, 60 | "beginDate": "2016-01-29T18:39:17Z", 61 | "endDate": "2016-01-29T19:15:15Z", 62 | "mileage": 21.67, 63 | "usedTime": 1908 64 | } 65 | ``` 66 | 67 | |Property|Type|Comment| 68 | |---|---|---| 69 | |id|string|The id of the trip| 70 | |beginLocation|location|The first *location* of the trip| 71 | |endLocation|location|The last *location* of the trip| 72 | |beginDate|date|the date when the trip has started| 73 | |endDate|date|the date when the trip has stoped| 74 | |mileage|double|the distance of the trip in kilometers| 75 | |usedTime|integer|the total time of the trip| 76 | 77 | ## Errors 78 | 79 | > See how errors are formed in [v3 Readme](../README.md) 80 | 81 | > Be aware of [authentication errors](../auth/README.md) 82 | 83 | |Reason|Status Code|Type|Message|Tip| 84 | |---|---|---|---|---| 85 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the trip belongs to the user you've got the token from| 86 | |Trip does not exist|`404`|`PARAMETERS_ERROR`|Trip not found|Please check that the trip exists, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/trips/trip_id/stats.md: -------------------------------------------------------------------------------- 1 | # /trips/{tripId}/stats 2 | 3 | Get the *statistics* for a specific *trip* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/stats` 8 | 9 | > You'll need the *trips_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the trip you are looking for the *stats*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | [ 43 | { 44 | "type": "MILEAGE", 45 | "value": 5.800642496450446 46 | }, 47 | { 48 | "type": "USED_TIME", 49 | "value": 980 50 | } 51 | ] 52 | ``` 53 | 54 | |Property|Type|Comment| 55 | |---|---|---| 56 | |type|string|the type of stat| 57 | |value|double|the *value*| 58 | 59 | > Mileage stat is in `km`, usedtime stat is in `sec` 60 | 61 | ## Errors 62 | 63 | > See how errors are formed in [v3 Readme](../../README.md) 64 | 65 | > Be aware of [authentication errors](../../auth/README.md) 66 | 67 | |Reason|Status Code|Type|Message|Tip| 68 | |---|---|---|---|---| 69 | |Scope `trips_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the trips_read scope to your app scopes and reconnect the user| 70 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the token belongs to the user owning the trip you're asking for| 71 | |The trip does not exist|`404`|`PARAMETERS_ERROR`|Trip not found|Please check that the trip exists, looks like it does not| 72 | |The statistic does not exist|`404`|`PARAMETERS_ERROR`|Statistics not found|Please check that the trip exists and data are present, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/trips/trip_id/stats/mileage.md: -------------------------------------------------------------------------------- 1 | # /trip/{tripId}/stats/mileage 2 | 3 | Get the *mileage* value for a specific *trip* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/stats/mileage` 8 | 9 | > You'll need the *trips_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the trip you are looking for the *mileage*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "type": "MILEAGE", 44 | "value": 4.2 45 | } 46 | ``` 47 | 48 | |Property|Type|Comment| 49 | |---|---|---| 50 | |type|string|the type of stat, here `MILEAGE`| 51 | |value|double|the *mileage* in *km*| 52 | 53 | ## Errors 54 | 55 | > See how errors are formed in [v3 Readme](../../../README.md) 56 | 57 | > Be aware of [authentication errors](../../../auth/README.md) 58 | 59 | |Reason|Status Code|Type|Message|Tip| 60 | |---|---|---|---|---| 61 | |Scope `trips_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the trips_read scope to your app scopes and reconnect the user| 62 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the token belongs to the user owning the trip you're asking for| 63 | |The trip does not exist|`404`|`PARAMETERS_ERROR`|trip not found|Please check that the trip exists, looks like it does not| 64 | |The statistic does not exist|`404`|`PARAMETERS_ERROR`|Statistics not found|Please check that the trip exists and data are present, looks like it does not| 65 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 66 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/trips/trip_id/stats/usedtime.md: -------------------------------------------------------------------------------- 1 | # /trip/{tripId}/stats/usedtime 2 | 3 | Get the *used time* value for a specific *trip* 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/trips/{tripId}/stats/usedtime` 8 | 9 | > You'll need the *trips_read* scope. 10 | 11 | Secured by **OAuth 2** access token 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`tripId`|The `id` of the trip you are looking for the *used time* (duration)|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "type": "USED_TIME", 44 | "value": 1271 45 | } 46 | ``` 47 | 48 | |Property|Type|Comment| 49 | |---|---|---| 50 | |type|string|the type of stat, here `USED_TIME`| 51 | |value|double|the *used time* in *sec*| 52 | 53 | ## Errors 54 | 55 | > See how errors are formed in [v3 Readme](../../../README.md) 56 | 57 | > Be aware of [authentication errors](../../../auth/README.md) 58 | 59 | |Reason|Status Code|Type|Message|Tip| 60 | |---|---|---|---|---| 61 | |Scope `trips_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the trips_read scope to your app scopes and reconnect the user| 62 | |The token does not have access to this trip|`403`|`AUTHORIZATION_ERROR`|Token can't access this trip|Make sure the token belongs to the user owning the trip you're asking for| 63 | |The trip does not exist|`404`|`PARAMETERS_ERROR`|trip not found|Please check that the trip exists, looks like it does not| 64 | |The statistic does not exist|`404`|`PARAMETERS_ERROR`|Statistics not found|Please check that the trip exists and data are present, looks like it does not| 65 | |Order of dates is wrong|`416`|`PARAMETERS_ERROR`|Range issue in dates|Please check the dates you've set in parameters are correct and begin is before end| 66 | |You asked for more than the month|`416`|`PARAMETERS_ERROR`|Range issue in dates|You can only request 1 month max per request| -------------------------------------------------------------------------------- /api/api/v3/users/README.md: -------------------------------------------------------------------------------- 1 | # Users 2 | 3 | Get the logged in user information. 4 | 5 | > Don't forget the *users_read* and the *cars_read* scopes. 6 | 7 | |Method|API|Description| 8 | |---|---|---| 9 | |GET|[`/users/me`](me.md)|Get the connected user| 10 | |GET|[`/users/me/cars`](me/cars.md)|Get all the cars for the connected user| 11 | |GET|[`/users/{userId}`](user_id.md)|Get a specific user| 12 | |GET|[`/users/{userId}/cars`](cars.md)|Get all the cars from a user| 13 | |POST|[`/users/{userId}/cars`](cars_create.md)|Create a car for this user| 14 | -------------------------------------------------------------------------------- /api/api/v3/users/cars.md: -------------------------------------------------------------------------------- 1 | # GET /users/{userId}/cars 2 | 3 | Get all *cars* from a specific *user* by its `id` 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/users/{userId}/cars` 8 | 9 | > You'll need the *cars_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`userId`|The `id` of the user you are looking for the *cars*|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | [ 43 | { 44 | "id": 1337, 45 | "name": "Mark-42", 46 | "make": "Mark", 47 | "model": "42", 48 | "year": 2014, 49 | "numberPlate": "M-42-TS", 50 | "deviceId": "E133742015", 51 | "cardbId": 210, 52 | "creationDate": "2014-09-23T12:49:48+00:00", 53 | "lastUpdateDate": "2016-02-19T08:41:58+00:00" 54 | }, 55 | { 56 | ... 57 | } 58 | ] 59 | ``` 60 | 61 | |Property|Type|Comment| 62 | |---|---|---| 63 | |id|integer|| 64 | |name|string|| 65 | |make|string|Might be `generic`| 66 | |model|string|Might be `null`| 67 | |year|integer|Might be `0`| 68 | |numberPlate|string|Might be `null`| 69 | |deviceId|string|The `serial number` of the device. Might be `null` if the car has no device associated| 70 | |cardbId|integer|Represents the type of the *car* from our point of view, that's how we speak to them| 71 | |creationDate|date|| 72 | |lastUpdateDate|date|| 73 | 74 | ## Errors 75 | 76 | > See how errors are formed in [v3 Readme](../README.md) 77 | 78 | > Be aware of [authentication errors](../auth/README.md) 79 | 80 | |Reason|Status Code|Type|Message|Tip| 81 | |---|---|---|---|---| 82 | |Scope `cars_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the cars_read scope to your app scopes and reconnect the user| 83 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the user is accessible with this token| 84 | |User does not exist|`404`|`PARAMETERS_ERROR`|User not found|Please check that the user exists, looks like it does not| -------------------------------------------------------------------------------- /api/api/v3/users/cars_create.md: -------------------------------------------------------------------------------- 1 | # POST /users/{userId}/cars 2 | 3 | Create a car for a *user* specified by its `id` 4 | 5 | ## Basics 6 | 7 | `[POST] https://{env}.xee.com/v3/users/{userId}/cars` 8 | 9 | > You'll need the *cars_write* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`userId`|The `id` of the user you are looking for the *cars*|YES| 35 | 36 | ### Body 37 | 38 | |Parameter name|Type|Description|Mandatory|Rules| 39 | |---|---|---|---|---| 40 | |name|string|The car name|false|length(0,64)| 41 | |make|string|The car manufacturer name|true|length(3,64)| 42 | |model|string|The car model|true|length(1,64)| 43 | |year|integer|The year of production of the car|false|-| 44 | |numberPlate|string|The numberplate of the car|false|length(0,64)| 45 | |timezone|string|The timezone of the country where this car is located|false, default to Europe/Paris|Timezone exists| 46 | 47 | ## Success Response 48 | 49 | - Status Code: `201` 50 | - Body: 51 | 52 | ```json 53 | { 54 | "id": 1337, 55 | "userId": 1234, 56 | "name": "Mark-42", 57 | "make": "Mark", 58 | "model": "42", 59 | "year": 2014, 60 | "numberPlate": "M-42-TS", 61 | "timezone": "Europe/Paris", 62 | "deviceId": null, 63 | "cardbId": 210, 64 | "creationDate": "2014-09-23T12:49:48+00:00", 65 | "lastUpdateDate": "2016-02-19T08:41:58+00:00" 66 | } 67 | ``` 68 | 69 | |Property|Type|Comment| 70 | |---|---|---| 71 | |id|integer|| 72 | |userId|integer|| 73 | |name|string|| 74 | |make|string|Might be `generic`| 75 | |model|string|Might be `null`| 76 | |year|integer|Might be `0`| 77 | |numberPlate|string|Might be `null`| 78 | |timezone|string|Default value to Europe/Paris| 79 | |deviceId|string|The `serial number` of the device. Might be `null` if the car has no device associated| 80 | |cardbId|integer|Represents the type of the *car* from our point of view, that's how we speak to them| 81 | |creationDate|date|| 82 | |lastUpdateDate|date|| 83 | 84 | ## Errors 85 | 86 | > See how errors are formed in [v3 Readme](../README.md) 87 | 88 | > Be aware of [authentication errors](../auth/README.md) 89 | 90 | |Reason|Status Code|Type|Message|Tip| 91 | |---|---|---|---|---| 92 | |Scope `cars_write` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the cars_write scope to your app scopes and reconnect the user| 93 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the user is accessible with this token| 94 | |User does not exist|`404`|`PARAMETERS_ERROR`|User not found|Please check that the user exists, looks like it does not| 95 | -------------------------------------------------------------------------------- /api/api/v3/users/me.md: -------------------------------------------------------------------------------- 1 | # /users/me 2 | 3 | Get user from an `access_token` 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/users/me` 8 | 9 | > You'll need the *users_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Headers 16 | 17 | |Header name|Header value|Mandatory| 18 | |---|---|---| 19 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 20 | 21 | ### Parameters 22 | 23 | There is *no parameter* for this API 24 | 25 | ## Success Response 26 | 27 | - Status Code: `200` 28 | - Body: 29 | 30 | ```javascript 31 | { 32 | "id": 42, 33 | "lastName": "Doe", 34 | "firstName": "John", 35 | "nickName": "Johny", 36 | "gender": "MALE", 37 | "birthDate": "2016-01-11T00:00:00+00:00", 38 | "licenceDeliveryDate": "2014-08-13T00:00:00+00:00", 39 | "role": "dev", 40 | "isLocationEnabled": true, 41 | "creationDate": "2014-08-13T15:20:58+00:00", 42 | "lastUpdateDate": "2016-02-12T09:07:47+00:00", 43 | } 44 | ``` 45 | 46 | |Property|Type|Comment| 47 | |---|---|---| 48 | |id|integer|| 49 | |lastName|string|| 50 | |firstName|string|| 51 | |nickName|string|Might be `null`| 52 | |gender|enum (as string)|`MALE`, `FEMALE`| 53 | |birthDate|date|Might be `null`| 54 | |licenceDeliveryDate|date|Might be `null`| 55 | |role|enum (as string)|`user`, `dev`, others| 56 | |isLocationEnabled|boolean|`true` if the user has authorized us to retrieve the Xee's locations, `false` otherwise| 57 | |creationDate|date|| 58 | | lastUpdateDate|date|| 59 | 60 | ## Errors 61 | 62 | > See how errors are formed in [v3 Readme](../README.md) 63 | 64 | > Be aware of [authentication errors](../auth/README.md) 65 | 66 | |Reason|Status Code|Type|Message|Tip| 67 | |---|---|---|---|---| 68 | |Scope `users_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the users_read scope to your app scopes and reconnect the user| -------------------------------------------------------------------------------- /api/api/v3/users/me/cars.md: -------------------------------------------------------------------------------- 1 | # /users/me/cars 2 | 3 | Get all *cars* from the connected user 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/users/me/cars` 8 | 9 | > You'll need the *cars_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Headers 16 | 17 | |Header name|Header value|Mandatory| 18 | |---|---|---| 19 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 20 | 21 | ### Url Parameters 22 | 23 | There is no parameter for this API 24 | 25 | ## Success Response 26 | 27 | - Status Code: `200` 28 | - Body: 29 | 30 | ```javascript 31 | [ 32 | { 33 | "id": 1337, 34 | "name": "Mark-42", 35 | "make": "Mark", 36 | "model": "42", 37 | "year": 2014, 38 | "numberPlate": "M-42-TS", 39 | "deviceId": "E133742015", 40 | "cardbId": 210, 41 | "creationDate": "2014-09-23T12:49:48+00:00", 42 | "lastUpdateDate": "2016-02-19T08:41:58+00:00" 43 | }, 44 | { 45 | ... 46 | } 47 | ] 48 | ``` 49 | 50 | |Property|Type|Comment| 51 | |---|---|---| 52 | |id|integer|| 53 | |name|string|| 54 | |make|string|Might be `generic`| 55 | |model|string|Might be `null`| 56 | |year|integer|Might be `0`| 57 | |numberPlate|string|Might be `null`| 58 | |deviceId|string|The `serial number` of the device. Might be `null` if the car has no device associated| 59 | |cardbId|integer|Represents the type of the *car* from our point of view, that's how we speak to them| 60 | |creationDate|date|| 61 | |lastUpdateDate|date|| 62 | 63 | ## Errors 64 | 65 | > See how errors are formed in [v3 Readme](../../README.md) 66 | 67 | > Be aware of [authentication errors](../../auth/README.md) 68 | 69 | |Reason|Status Code|Type|Message|Tip| 70 | |---|---|---|---|---| 71 | |Scope `cars_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the cars_read scope to your app scopes and reconnect the user| -------------------------------------------------------------------------------- /api/api/v3/users/user_id.md: -------------------------------------------------------------------------------- 1 | # /users/{userId} 2 | 3 | Get a user from its `id` 4 | 5 | ## Basics 6 | 7 | `[GET] https://{env}.xee.com/v3/users/{userId}` 8 | 9 | > You'll need the *users_read* scope. 10 | 11 | Secured by **OAuth 2** access token. 12 | 13 | ## Request 14 | 15 | ### Environment 16 | 17 | The `env` variable as the host of the route can be changed for testing purpose. 18 | 19 | |Value|Comment| 20 | |---|---| 21 | |`cloud`|**production** environment (*real* client data, `Authorization` needed)| 22 | |`sandbox`|**sandbox** environment (*fake* data, **no** `Authorization` needed)| 23 | 24 | ### Headers 25 | 26 | |Header name|Header value|Mandatory| 27 | |---|---|---| 28 | |Authorization|`Bearer` with the *OAuth2* access token|YES| 29 | 30 | ### Url Parameters 31 | 32 | |Parameter name|Parameter value|Mandatory| 33 | |---|---|---| 34 | |`userId`|The `id` of the user you are looking for|YES| 35 | 36 | ## Success Response 37 | 38 | - Status Code: `200` 39 | - Body: 40 | 41 | ```javascript 42 | { 43 | "id": 42, 44 | "lastName": "Doe", 45 | "firstName": "John", 46 | "nickName": "Johny", 47 | "gender": "MALE", 48 | "birthDate": "2016-01-11T00:00:00+00:00", 49 | "licenceDeliveryDate": "2014-08-13T00:00:00+00:00", 50 | "role": "dev", 51 | "isLocationEnabled": true, 52 | "creationDate": "2014-08-13T15:20:58+00:00", 53 | "lastUpdateDate": "2016-02-12T09:07:47+00:00", 54 | "email": "foo@bar.com" 55 | } 56 | ``` 57 | 58 | |Property|Type|Comment| 59 | |---|---|---| 60 | |id|integer|| 61 | |lastName|string|| 62 | |firstName|string|| 63 | |nickName|string|Might be `null`| 64 | |gender|enum (as string)|`MALE`, `FEMALE`| 65 | |birthDate|date|Might be `null`| 66 | |licenceDeliveryDate|date|Might be `null`| 67 | |role|enum (as string)|`user`, `dev`, others| 68 | |isLocationEnabled|boolean|`true` if the user has authorized us to retrieve the Xee's locations, `false` otherwise| 69 | |creationDate|date|| 70 | |lastUpdateDate|date|| 71 | |email|string|Email address of the user| 72 | 73 | ## Errors 74 | 75 | > See how errors are formed in [v3 Readme](../README.md) 76 | 77 | > Be aware of [authentication errors](../auth/README.md) 78 | 79 | |Reason|Status Code|Type|Message|Tip| 80 | |---|---|---|---|---| 81 | |Scope `users_read` is missing|`403`|`AUTHORIZATION_ERROR`|Token does not have the required scope|Add the users_read scope to your app scopes and reconnect the user| 82 | |The token does not have access to this user|`403`|`AUTHORIZATION_ERROR`|Token can't access this user|Make sure the trip belongs to the user you asked for| 83 | |User does not exist|`404`|`PARAMETERS_ERROR`|User not found|Please check that the user exists, looks like it does not| -------------------------------------------------------------------------------- /api/compat/v1/README.md: -------------------------------------------------------------------------------- 1 | # v1 (DEPRECATED) 2 | 3 | The first version of Xee Compatibility API (*DEPRECATED*) 4 | 5 | ## Authentication 6 | 7 | The authentication is based on `Basic`. 8 | When you register on [dev space](https://dev.xee.com) and create an application, you get a `clientId` and a `clientSecret`. 9 | 10 | Then, with all the request, provide an `Authorization` header with the following value: 11 | `Basic base64(clientId:clientSecret)` 12 | 13 | For example: *Basic ZlV5YlhtVG......RDdjeU1................LaUdwUU9MRlFpUko=* 14 | 15 | ## API 16 | 17 | ### Ktype 18 | 19 | This is the first route of our API, from this, you can get compatibility from a **Ktype** 20 | > [Ktype API](ktype/README.md) 21 | 22 | |API|Description| 23 | |---|---| 24 | |[`/ktype/{ktype}`](ktype/ktype.md)|Get compatibility from a *ktype*| 25 | 26 | ### Cardb 27 | 28 | This is the second route of our API, from this, you can get compatibility from a **cardb** 29 | > [Cardb API](cardb/README.md) 30 | 31 | |API|Description| 32 | |---|---| 33 | |[`/cardb/{cardbId}`](cardb/cardbId.md)|Get compatibility from a *cardb Id*| 34 | 35 | ## Errors 36 | 37 | Specific authentication errors here 38 | 39 | |Reason|Status Code|Type|Message|Tip| 40 | |---|---|---|---|---| 41 | |Missing `Authorization` header|`401`|`AUTHENTICATION_ERROR`|Authorization header is not valid|Make sure that the header has a valid format| 42 | 43 | -------------------------------------------------------------------------------- /api/compat/v1/cardb/README.md: -------------------------------------------------------------------------------- 1 | # Cardb *DEPRECATED* 2 | 3 | |API|Description| 4 | |---|---| 5 | |[`/cardb/{cardbId}`](cardbId.md)|Get compatibility from a *cardbId* (*DEPRECATED*)| 6 | -------------------------------------------------------------------------------- /api/compat/v1/cardb/cardbId.md: -------------------------------------------------------------------------------- 1 | # /cardb/{cardbId} (*DEPRECATED*) 2 | 3 | Get a compatibility from a *cardbId* 4 | 5 | ## Basics 6 | 7 | `[GET] https://compat.xee.com/v1/cardb/{cardbId}` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | 19 | ### Url Parameters 20 | 21 | |Parameter name|Parameter value|Mandatory| 22 | |---|---|---| 23 | |`cardbId`|The `cardbId` you want the compatibility|YES| 24 | 25 | ## Success Response 26 | 27 | - Status Code: `200` 28 | - Body: 29 | 30 | ```javascript 31 | { 32 | "signalsAvailable": [ 33 | { 34 | "name": "Odometer", 35 | "reliability": null, // DEPRECATED will be removed in a futur version 36 | "confidence": true, 37 | "evolution": null 38 | }, 39 | { 40 | "name": "FuelLevel", 41 | "reliability": "incremental", // DEPRECATED will be removed in a futur version 42 | "confidence": false, 43 | "evolution": "incremental" 44 | } 45 | ], 46 | "signalsUnavailable": [ 47 | { 48 | "name": "VehiculeSpeed", 49 | "reliability": null, // DEPRECATED will be removed in a futur version 50 | "confidence": null, 51 | "evolution": null 52 | }, 53 | { 54 | "name": "EngineSpeed", 55 | "reliability": null, // DEPRECATED will be removed in a futur version 56 | "confidence": null, 57 | "evolution": null 58 | } 59 | ] 60 | } 61 | ``` 62 | 63 | |Property|Type|Comment| 64 | |---|---|---| 65 | |signalsAvailable|array|contains *signals*| 66 | |signalsUnavailable|array|contains *signals*| 67 | 68 | #### Signal 69 | 70 | |Property|Type|Comment| 71 | |---|---|---| 72 | |name|string|| 73 | |reliability|enum (as string)|**DEPRECATED** This field is just use for the FuelLevel signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail)| 74 | |confidence|boolean|This field represents the confidence we have on the reliability for this signal. If `true`, the signal is considered as reliable. If `false`, you should not use this signal, unless you checked the `evolution` field before and know what you are doing| 75 | |evolution|enum (as string)|This field is a represents the evolution of the signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail). This field is mainly used when the field `confidence` is set to false.| 76 | 77 | ## Errors 78 | 79 | > See how errors are formed in [API v3 Readme](https://github.com/xee-lab/xee-api-docs/tree/master/api/api/v3#errors) 80 | 81 | |Reason|Status Code|Type|Message|Tip| 82 | |---|---|---|---|---| 83 | |`carDb` not correct|`400`|`PARAMETERS_ERROR`|Unable to parse cardb parameter|Please check if carDb parameter you have set is a int| 84 | |`carDb` not found|`404`|`NOT_FOUND`|CarDb not found|The carDb associated with KType doesn't exist. Please try with an other KType.| 85 | -------------------------------------------------------------------------------- /api/compat/v1/ktype/README.md: -------------------------------------------------------------------------------- 1 | # Ktype *DEPRECATED* 2 | 3 | |API|Description| 4 | |---|---| 5 | |[`/ktype/{ktype}`](ktype.md)|Get compatibility from a *ktype* (*DEPRECATED*)| 6 | -------------------------------------------------------------------------------- /api/compat/v1/ktype/ktype.md: -------------------------------------------------------------------------------- 1 | # /ktype/{ktype} (*DEPRECATED*) 2 | 3 | Get a compatibility from a *ktype* 4 | 5 | ## Basics 6 | 7 | `[GET] https://compat.xee.com/v1/ktype/{ktype}?in_service={in_service}` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | 19 | ### Url Parameters 20 | 21 | |Parameter name|Parameter value|Mandatory| 22 | |---|---|---| 23 | |`ktype `|The `ktype` you want the compatibility|YES| 24 | 25 | ### Query Parameters 26 | 27 | |Parameter name|Parameter value|Mandatory| 28 | |---|---|---| 29 | |`in_service`|The `date` of the first time the car was used. Format is `yyyy-mm` (`2016-04`)|NO| 30 | 31 | ## Success Response 32 | 33 | - Status Code: `200` 34 | - Body: 35 | 36 | ```javascript 37 | { 38 | "signalsAvailable": [ 39 | { 40 | "name": "Odometer", 41 | "reliability": null, // DEPRECATED will be removed in a futur version 42 | "confidence": true, 43 | "evolution": null 44 | }, 45 | { 46 | "name": "FuelLevel", 47 | "reliability": "incremental", // DEPRECATED will be removed in a futur version 48 | "confidence": false, 49 | "evolution": "incremental" 50 | } 51 | ], 52 | "signalsUnavailable": [ 53 | { 54 | "name": "VehiculeSpeed", 55 | "reliability": null, // DEPRECATED will be removed in a futur version 56 | "confidence": null, 57 | "evolution": null 58 | }, 59 | { 60 | "name": "EngineSpeed", 61 | "reliability": null, // DEPRECATED will be removed in a futur version 62 | "confidence": null, 63 | "evolution": null 64 | } 65 | ] 66 | } 67 | ``` 68 | 69 | |Property|Type|Comment| 70 | |---|---|---| 71 | |signalsAvailable|array|contains *signals*| 72 | |signalsUnavailable|array|contains *signals*| 73 | 74 | #### Signal 75 | 76 | |Property|Type|Comment| 77 | |---|---|---| 78 | |name|string|| 79 | |reliability|enum (as string)|**DEPRECATED** This field is just use for the FuelLevel signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail)| 80 | |confidence|boolean|This field represents the confidence we have on the reliability for this signal. If `true`, the signal is considered as reliable. If `false`, you should not use this signal, unless you checked the `evolution` field before and know what you are doing| 81 | |evolution|enum (as string)|This field is a represents the evolution of the signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail). This field is mainly used when the field `confidence` is set to false.| 82 | 83 | ## Errors 84 | 85 | > See how errors are formed in [API v3 Readme](https://github.com/xee-lab/xee-api-docs/tree/master/api/api/v3#errors) 86 | 87 | |Reason|Status Code|Type|Message|Tip| 88 | |---|---|---|---|---| 89 | |`ktype` not correct|`400`|`PARAMETERS_ERROR`|Unable to parse KType parameter|Please check if KType parameter you have set is a int| 90 | |`in_service` date not correct|`400`|`PARAMETERS_ERROR`|Unable to parse date|Please check the dates you have set in parameters are correct format `yyyy-mm` (`2016-04`)| 91 | |`ktype` does not exists in Xee|`404`|`NOT_FOUND`|KType not found|Please try with an other KType or specify/change the in_service date.| 92 | -------------------------------------------------------------------------------- /api/compat/v3/README.md: -------------------------------------------------------------------------------- 1 | # v3 2 | 3 | New Xee Compatibility API 4 | 5 | ## Authentication 6 | 7 | The authentication is based on `Basic`. 8 | When you register on [dev space](https://dev.xee.com) and create an application, you get a `clientId` and a `clientSecret`. 9 | 10 | Then, for each request, provide an `Authorization` header with the following value: 11 | `Basic base64(clientId:clientSecret)` 12 | 13 | For example: *Basic ZlV5YlhtVG......RDdjeU1................LaUdwUU9MRlFpUko=* 14 | 15 | ## API 16 | 17 | |API|Description| 18 | |---|---| 19 | |[`/brands`](brands.md)|Get brands list| 20 | |[`/brands/{brandId}/models`](models.md)|Get models for a *brand Id*| 21 | |[`/brands/{brandId}/models/versions?model=modelString`](versions.md)|Get versions for a *brand Id* and a *model* string| 22 | |[`/ktypes?plateNumber=aa123aa&captchaResponse=xxx`](versionsByPlateNumber.md)|Get versions from a *plateNumber*. This API is protected by a Captcha.| 23 | |[`/ktype/{ktype}`](ktype.md)|*DEPRECATED* Get compatibility from a *ktype*| 24 | |[`/ktypes/{ktype}`](ktype.md)|Get compatibility from a *ktype*| 25 | |[`/cardb/{cardbId}`](cardb.md)|Get compatibility from a *cardb Id*| 26 | 27 | ## Errors 28 | 29 | Specific authentication errors here 30 | 31 | |Reason|Status Code|Type|Message|Tip| 32 | |---|---|---|---|---| 33 | |Missing `Authorization` header|`401`|`AUTHENTICATION_ERROR`|Authorization header is not valid|Make sure that the header has a valid format| 34 | 35 | -------------------------------------------------------------------------------- /api/compat/v3/brands.md: -------------------------------------------------------------------------------- 1 | # /brands 2 | 3 | Get the list of all brands 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/brands` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | 19 | ## Success Response 20 | 21 | - Status Code: `200` 22 | - Body: 23 | 24 | ```javascript 25 | [ 26 | { 27 | "id": 467, 28 | "name": "ABARTH", 29 | "displayName": "ABARTH" 30 | }, 31 | { 32 | "id": 1, 33 | "name": "AC", 34 | "displayName": "AC" 35 | }, 36 | ... 37 | ] 38 | ``` 39 | 40 | The response is an array of brands. 41 | 42 | ### brand model object 43 | 44 | |Property|Type|Comment| 45 | |---|---|---| 46 | |id|int|The identifier of the brand| 47 | |name|string|The default name of the brand| 48 | |displayName|string|The comprehensive name of the brand. For example displayName is `VOLKSWAGEN` for brand with name `VW`| 49 | -------------------------------------------------------------------------------- /api/compat/v3/cardb.md: -------------------------------------------------------------------------------- 1 | # /cardb/{cardbId} 2 | 3 | Get a compatibility from a *cardb id* 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/cardb/{cardbId}` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | |Accept-Language|The language in which you want to get the mounting manual link. Available languages are: fr,de,en,es,it,nl,pt|NO : default value is fr| 19 | 20 | ### Url Parameters 21 | 22 | |Parameter name|Parameter value|Mandatory| 23 | |---|---|---| 24 | |`cardbId`|The `cardbId` you want the compatibility|YES| 25 | 26 | ## Success Response 27 | 28 | - Status Code: `200` 29 | - Body: 30 | 31 | ```javascript 32 | { 33 | "signalsAvailable": [ 34 | { 35 | "name": "GPS", 36 | "confidence": true, 37 | "evolution": null 38 | }, 39 | { 40 | "name": "Odometer", 41 | "confidence": true, 42 | "evolution": null 43 | }, 44 | { 45 | "name": "FuelLevel", 46 | "confidence": false, 47 | "evolution": "incremental" 48 | } 49 | ], 50 | "signalsUnavailable": [ 51 | { 52 | "name": "VehiculeSpeed", 53 | "confidence": null, 54 | "evolution": null 55 | }, 56 | { 57 | "name": "EngineSpeed", 58 | "confidence": null, 59 | "evolution": null 60 | } 61 | ] 62 | } 63 | ``` 64 | 65 | |Property|Type|Comment| 66 | |---|---|---| 67 | |signalsAvailable|array|Contains all the available *signal* objects for this cardb id| 68 | |signalsUnavailable|array|Contains all the unavailable *signal* objects for this cardb id| 69 | 70 | #### Signal 71 | 72 | |Property|Type|Comment| 73 | |---|---|---| 74 | |name|string|| 75 | |confidence|boolean|This field represents the confidence we have on the reliability for this signal. If `true`, the signal is considered as reliable. If `false`, you should not use this signal, unless you checked the `evolution` field before and know what you are doing| 76 | |evolution|enum (as string)|This field is a represents the evolution of the signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail). This field is mainly used when the field `confidence` is set to false.| 77 | 78 | ## Errors 79 | 80 | > See how errors are formed in [API v3 Readme](https://github.com/xee-lab/xee-api-docs/tree/master/api/api/v3#errors) 81 | 82 | |Reason|Status Code|Type|Message|Tip| 83 | |---|---|---|---|---| 84 | |`carDb` not correct|`400`|`PARAMETERS_ERROR`|Unable to parse cardb parameter|Please check if carDb parameter you have set is a int| 85 | |`carDb` not found|`404`|`NOT_FOUND`|CarDb not found|The carDb associated with KType doesn't exist. Please try with an other KType.| 86 | -------------------------------------------------------------------------------- /api/compat/v3/ktype.md: -------------------------------------------------------------------------------- 1 | # /ktype/{ktype} 2 | 3 | Get a compatibility from a *ktype* 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/ktypes/{ktype}` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | |Accept-Language|The language in which you want to get the mounting manual link. Available languages are: fr,de,en,es,it,nl,pt|NO : default value is fr| 19 | 20 | ### Url Parameters 21 | 22 | |Parameter name|Parameter value|Mandatory| 23 | |---|---|---| 24 | |`ktype`|The `ktype` you want the compatibility|YES| 25 | 26 | ## Success Response 27 | 28 | - Status Code: `200` 29 | - Body: 30 | 31 | ```javascript 32 | { 33 | "signalsAvailable": [{ 34 | "name": "GPS", 35 | "confidence": true, 36 | "evolution": null 37 | }, 38 | { 39 | "name": "Odometer", 40 | "confidence": true, 41 | "evolution": null 42 | }, 43 | { 44 | "name": "FuelLevel", 45 | "confidence": false, 46 | "evolution": "incremental" 47 | } 48 | ], 49 | "signalsUnavailable": [{ 50 | "name": "VehiculeSpeed", 51 | "confidence": null, 52 | "evolution": null 53 | }, 54 | { 55 | "name": "EngineSpeed", 56 | "confidence": null, 57 | "evolution": null 58 | } 59 | ], 60 | "mounting": { 61 | "analyzed": true, 62 | "can": true, 63 | "connection": [{ 64 | "type": "wired", 65 | "link": null 66 | }, 67 | { 68 | "type": "plugandgo", 69 | "link": null 70 | } 71 | ], 72 | "manualURL": "https://cloud.xee.com/v3/compat/manual?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IJ9.eyJleHBpcmVfYXQiOjE1MDkwMmlkIjoiMEIxdVNRSlhqUTBtMlNVMTJVbWxxZDNGV1pHcyJ9.0X7RDgUIO-1NeUnWCiwN6LsrqmqrAJ71Bun" 73 | } 74 | } 75 | ``` 76 | 77 | |Property|Type|Comment| 78 | |---|---|---| 79 | |signalsAvailable|array|Contains all the available *signal* objects for this ktype| 80 | |signalsUnavailable|array|Contains all the unavailable *signal* objects for this ktype| 81 | |mounting|mounting|Contains mounting information| 82 | 83 | #### signal object 84 | 85 | |Property|Type|Comment| 86 | |---|---|---| 87 | |name|string|| 88 | |confidence|boolean|This field represents the confidence we have on the reliability for this signal. If `true`, the signal is considered as reliable. If `false`, you should not use this signal, unless you checked the `evolution` field before and know what you are doing| 89 | |evolution|enum (as string)|This field is a represents the evolution of the signal. Might be null, possible values : `continuous`, `incremental`, `wtf` (**W**ill **T**emporatily **F**ail). This field is mainly used when the field `confidence` is set to false.| 90 | 91 | 92 | ### mounting object 93 | 94 | |Property|Type|Comment| 95 | |---|---|---| 96 | |analyzed|boolean|`true` if this ktype has been analyzed| 97 | |can|boolean|`true` if the ktype has can| 98 | |connection|array(connection)|The available mounting connections for XeeCONNECT for this ktype| 99 | |manualURL|string|The URL to download the manual detailing how to mount a XeeCONNECT for this ktype. You have to call this URL by giving the Basic `Authorization` header as for this request. If you want to get the manual in a different language, you can use the `Accept-Language` header as describe above. The given link is valid for 10 minutes, after what you need to ask a new token for this manual.| 100 | 101 | 102 | ### connection object 103 | 104 | |Property|Type|Comment| 105 | |---|---|---| 106 | |type|enum(plugandgo\|wired)|The mounting type for this model. `plugandgo` means "On Board Diagnostics" plug compatible, and `wired` means that hidden mounting is mandatory for this model| 107 | 108 | 109 | ## Errors 110 | 111 | > See how errors are formed in [API v3 Readme](https://github.com/xee-lab/xee-api-docs/tree/master/api/api/v3#errors) 112 | 113 | |Reason|Status Code|Type|Message|Tip| 114 | |---|---|---|---|---| 115 | |`carDb` not correct|`400`|`PARAMETERS_ERROR`|Unable to parse ktype parameter|Please check if ktype parameter you have set is an int| 116 | |`carDb` not found|`404`|`NOT_FOUND`|`ktype` not found|Please try with an other KType.| 117 | -------------------------------------------------------------------------------- /api/compat/v3/models.md: -------------------------------------------------------------------------------- 1 | # /brands/{brandId}/models 2 | 3 | Get the models list for a *brand Id* 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/brands/{brandId}/models` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | 19 | ### Url Parameters 20 | 21 | |Parameter name|Parameter value|Mandatory| 22 | |---|---|---| 23 | |`brandId`|The brand id field|YES| 24 | 25 | ## Success Response 26 | 27 | - Status Code: `200` 28 | - Body: 29 | 30 | ```javascript 31 | [ 32 | { 33 | "brandId": 467, 34 | "model": "124 Spider (348_)", 35 | "minStartDate": "2016-03-01T00:00:00Z", 36 | "maxEndDate": null, 37 | "cardbid": 426, 38 | "connection": [{ 39 | "type": "wired", 40 | "link": null 41 | }, 42 | { 43 | "type": "plugandgo", 44 | "link": null 45 | } 46 | ], 47 | "category": "124" 48 | }, 49 | { 50 | "brandId": 467, 51 | "model": "500 / 595 (312_)", 52 | "minStartDate": "2008-08-01T00:00:00Z", 53 | "maxEndDate": null, 54 | "cardbid": null, 55 | "connection": null, 56 | "category": "500" 57 | }, 58 | ... 59 | { 60 | "brandId": 467, 61 | "model": "GRANDE PUNTO (199_)", 62 | "minStartDate": "2007-12-01T00:00:00Z", 63 | "maxEndDate": "2012-12-01T00:00:00Z", 64 | "cardbid": 140, 65 | "connection": [{ 66 | "type": "plugandgo", 67 | "link": null 68 | }], 69 | "category": "GRANDE" 70 | }, 71 | ... 72 | ] 73 | ``` 74 | 75 | The response is an array of models. 76 | 77 | ### model object 78 | 79 | |Property|Type|Comment| 80 | |---|---|---| 81 | |brandId|int|The identifier of the brand| 82 | |model|string|The model string of the model| 83 | |minStartDate|date|The minimum start date within all the versions for this model| 84 | |maxEndDate|date|The maximum end date within all the versions for this model| 85 | |cardbid|int|The cardb id for this model. **/!\\** This field will be populated *only* if *all the versions* of this model have the same cardb id. So if this field is `null` you will have to look for your exact version to get the cardb id.| 86 | |connection|array(connection)|The available mounting connections for XeeCONNECT for this model. **/!\\** This field will be populated *only* if *all the versions* of this model have common mounting connection informations. So if this field is `null` you will have to look for your exact version to get the cardb id.| 87 | |category|string|The model category, if you want to group all the models with the same category. For example all the BMW 1 models will have the same category "Série 1"| 88 | 89 | ### connection object 90 | 91 | |Property|Type|Comment| 92 | |---|---|---| 93 | |type|enum(plugandgo\|wired)|The mounting type for this model. `plugandgo` means "On Board Diagnostics" plug compatible, and `wired` means that hidden mounting is mandatory for this model| 94 | |link|string|The URL to the mounting manual for this model. For now this property will always be `null`| 95 | 96 | 97 | -------------------------------------------------------------------------------- /api/compat/v3/versions.md: -------------------------------------------------------------------------------- 1 | # /brands/{brandId}/models/version?model=modelString 2 | 3 | Get the models list for a *brand Id* 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/brands/{brandId}/models` 8 | 9 | Secured by **Basic** auth. 10 | 11 | ## Request 12 | 13 | ### Headers 14 | 15 | |Header name|Header value|Mandatory| 16 | |---|---|---| 17 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 18 | 19 | ### Url Parameters 20 | 21 | |Parameter name|Parameter value|Mandatory| 22 | |---|---|---| 23 | |`brandId`|The brand id field|YES| 24 | 25 | ### Query Parameters 26 | 27 | |Parameter name|Parameter value|Mandatory| 28 | |---|---|---| 29 | |`model`|The model you want to get the versions|YES| 30 | 31 | ## Success Response 32 | 33 | - Status Code: `200` 34 | - Body: 35 | 36 | ```javascript 37 | [ 38 | { 39 | "ktype": 16982, 40 | "engineCapacity": "1198", 41 | "enginePower": 85, 42 | "fiscalHorsepower": 115, 43 | "startDate": "2012-03-01T00:00:00Z", 44 | "endDate": null, 45 | "brandId": 353, 46 | "model": "MEGANE III 3/5 portes (BZ0_)", 47 | "body": "3/5 portes", 48 | "version": "1.2 TCe", 49 | "fuel": "Essence", 50 | "cardbid": 100 51 | }, 52 | { 53 | "ktype": 29953, 54 | "engineCapacity": "1397", 55 | "enginePower": 96, 56 | "fiscalHorsepower": 130, 57 | "startDate": "2009-04-01T00:00:00Z", 58 | "endDate": null, 59 | "brandId": 353, 60 | "model": "MEGANE III 3/5 portes (BZ0_)", 61 | "body": "3/5 portes", 62 | "version": "1.4 TCe (BZ0F, BZ1V)", 63 | "fuel": "Essence", 64 | "cardbid": 100 65 | }, 66 | ... 67 | ] 68 | ``` 69 | 70 | The response is an array of versions. 71 | 72 | ### version object 73 | 74 | |Property|Type|Comment| 75 | |---|---|---| 76 | |brandId|int|The identifier of the brand| 77 | |model|string|The model string of the model| 78 | |startDate|date|The start date for this version| 79 | |endDate|date|The end date for this version| 80 | |cardbid|int|The cardb id for this version| 81 | |body|string|The body of the version| 82 | |version|string|The version| 83 | |fuel|string|The fuel for this version. For the list of possible values, see below| 84 | |ktype|int|The ktype| 85 | |engineCapacity|string|The engine capacity (unit: cm3)| 86 | |enginePower|int|The engine power (unit: kW)| 87 | |fiscalHorsepower|int|The engine power (unit: CV)| 88 | 89 | 90 | ### fuel field 91 | 92 | The fuel field is directly mapped from tecdoc, so it is not possible to ensure you the full list of possible values. 93 | 94 | By the way, this is the full list of values extracted on 05/11/2017: 95 | 96 | ```javascript 97 | [ 98 | "Alcool", 99 | "Bifuel", 100 | "Diesel", 101 | "Diesel/électrique", 102 | "éléctrique", 103 | "Essence / gaz combustible liquéfié (GPL)", 104 | "Essence / éthanol / gaz", 105 | "Essence / éthanol / électrique", 106 | "Essence / éthanol", 107 | "Essence /gaz naturel (CNG)", 108 | "Essence", 109 | "Essence/électrique", 110 | "Flexfuel", 111 | "Flexfuel/éléctrique", 112 | "GNC", 113 | "Hydrogène", 114 | "LPG", 115 | "Mélange" 116 | ] 117 | ``` 118 | -------------------------------------------------------------------------------- /api/compat/v3/versionsByPlateNumber.md: -------------------------------------------------------------------------------- 1 | # /ktypes?plateNumber=aa123aa&captchaResponse=xxx 2 | 3 | Get versions and ktypes from a *plateNumber* 4 | 5 | ## Basics 6 | 7 | `[GET] https://cloud.xee.com/v3/compat/ktypes?plateNumber=aa123aa&captchaResponse=xxx` 8 | 9 | Secured by **Basic** auth. 10 | 11 | 12 | ## Captcha 13 | 14 | This API is secured by a reCAPTCHA verification. 15 | 16 | You MUST add this captcha to your website if you want to use this API. 17 | 18 | The documentation of reCAPTCHA for client-side implementation can be found here: https://developers.google.com/recaptcha/docs/display 19 | 20 | Once you got the `recaptcha-response`, you will have to pass it to this API to be able to perform the search. 21 | 22 | For us to be able to make the captcha verification, you will need to use OUR reCAPTCHA site key : `6Ld4nSUUAAAAAH1onUr4ql7UBuYqdLLzmonyo_R0` 23 | 24 | *IMPORTANT*: Since this captcha usage is restricted to certain domains names, to enable the captcha on your website, please contact `support[@]xee.com` in order to whitelist your domain name. 25 | 26 | 27 | ## Request 28 | 29 | ### Headers 30 | 31 | |Header name|Header value|Mandatory| 32 | |---|---|---| 33 | |Authorization|`Basic` with the `base64` of your `clientId` and `clientSecret `|YES| 34 | 35 | ### Query Parameters 36 | 37 | |Parameter name|Parameter value|Mandatory| 38 | |---|---|---| 39 | |`plateNumber`|The plate number to search|YES| 40 | |`captchaResponse`|The recaptcha response|YES| 41 | 42 | ## Success Response 43 | 44 | This API can return multiple versions, since sometimes a given plate number is associated to multiple ktypes. 45 | 46 | - Status Code: `200` 47 | - Body: 48 | 49 | ```javascript 50 | [ 51 | { 52 | "ktype": 16982, 53 | "engineCapacity": "1198", 54 | "enginePower": 85, 55 | "fiscalHorsepower": 115, 56 | "startDate": "2012-03-01T00:00:00Z", 57 | "endDate": null, 58 | "brandId": 353, 59 | "model": "MEGANE III 3/5 portes (BZ0_)", 60 | "body": "3/5 portes", 61 | "version": "1.2 TCe", 62 | "fuel": "Essence", 63 | "cardbid": 100 64 | }, 65 | { 66 | "ktype": 29953, 67 | "engineCapacity": "1397", 68 | "enginePower": 96, 69 | "fiscalHorsepower": 130, 70 | "startDate": "2009-04-01T00:00:00Z", 71 | "endDate": null, 72 | "brandId": 353, 73 | "model": "MEGANE III 3/5 portes (BZ0_)", 74 | "body": "3/5 portes", 75 | "version": "1.4 TCe (BZ0F, BZ1V)", 76 | "fuel": "Essence", 77 | "cardbid": 100 78 | }, 79 | ... 80 | ] 81 | ``` 82 | 83 | The response is an array of versions. 84 | 85 | ### version object 86 | 87 | |Property|Type|Comment| 88 | |---|---|---| 89 | |brandId|int|The identifier of the brand| 90 | |model|string|The model string of the model| 91 | |startDate|date|The start date for this version| 92 | |endDate|date|The end date for this version| 93 | |cardbid|int|The cardb id for this version| 94 | |body|string|The body of the version| 95 | |version|string|The version| 96 | |fuel|string|The fuel for this version. For the list of possible values, see below| 97 | |ktype|int|The ktype| 98 | |engineCapacity|string|The engine capacity (unit: cm3)| 99 | |enginePower|int|The engine power (unit: kW)| 100 | |fiscalHorsepower|int|The engine power (unit: CV)| 101 | 102 | 103 | ### fuel field 104 | 105 | The fuel field is directly mapped from tecdoc, so it is not possible to ensure you the full list of possible values. 106 | 107 | By the way, this is the full list of values extracted on 05/11/2017: 108 | 109 | ```javascript 110 | [ 111 | "Alcool", 112 | "Bifuel", 113 | "Diesel", 114 | "Diesel/électrique", 115 | "éléctrique", 116 | "Essence / gaz combustible liquéfié (GPL)", 117 | "Essence / éthanol / gaz", 118 | "Essence / éthanol / électrique", 119 | "Essence / éthanol", 120 | "Essence /gaz naturel (CNG)", 121 | "Essence", 122 | "Essence/électrique", 123 | "Flexfuel", 124 | "Flexfuel/éléctrique", 125 | "GNC", 126 | "Hydrogène", 127 | "LPG", 128 | "Mélange" 129 | ] 130 | ``` 131 | -------------------------------------------------------------------------------- /setup/README.md: -------------------------------------------------------------------------------- 1 | # Setup 2 | 3 | A guide to setting up your Xee environment 4 | 5 | ## Create a dev account 6 | 7 | In order to create a *developer account*, please go to our [developer space, XeeDEV](https://dev.xee.com) and: 8 | 9 | - [Sign in](https://dev.xee.com/login) with your Xee account if you have one 10 | - [Create a Xee account](https://dev.xee.com/register) if you have not 11 | 12 | **As simple as that !** 13 | 14 | ## Create a client for the platform 15 | 16 | Once you're connected to our developer space, you can manage your **clients**. 17 | 18 | > A client is an "application" that can access our API, it is like a key to the platform. 19 | 20 | To get a client, you'll have to fill a form with some basic information: 21 | 22 | - Your app name 23 | - An app description 24 | - At least a *redirect_uri* (the URL we'll trigger for the login) 25 | - A logo url 26 | - The [scopes](scopes.md) you want 27 | 28 | You'll get: 29 | 30 | - A *client id* which will identify your application on Xee's platform 31 | - A *client secret* which is like the password of your application, keep it safe, we can't get it twice. 32 | 33 | And you'll be ready to go :) 34 | 35 | ## Think about what to do ? 36 | 37 | Once you've created your client on the platform, you can go on dealing with our API. 38 | But what is the best to do as we have: 39 | 40 | - API 41 | - Android SDK 42 | - iOS SDK 43 | 44 | Well, see there 45 | 46 | ### I want a web app (at least) 47 | 48 | In this case, you'll deal with our API directly, you can enjoy our [API Documentation](../api/README.md). 49 | 50 | > Note: Be aware of the **redirect_uri** you gave, it should match your domain's name. 51 | 52 | 53 | ### I want a mobile app 54 | 55 | Well, thats a good point, but, not an end, the thing is: 56 | 57 | *Do you need a third party server ?* 58 | 59 | We'll, if you do not know, this is simple, here some example to help you decide: 60 | 61 | - if your app will be on more than a system, and you want sync between your servers, then you'll need a third party server. 62 | - if you want to deal with your service on the mobile (not xee's one directly), then you'll need a third party server. 63 | - in fact, as soon as you want the Xee data to be out of the mobile app, you'll need a third party server. 64 | 65 | #### I need a third party server 66 | 67 | Nice, in this case, this is the same thing for *web app* so you'll deal with our API directly, you can enjoy our [API Documentation](../api/README.md). 68 | 69 | > Note: Be aware of the **redirect_uri** you gave, it should match your domain's name. 70 | 71 | #### I'll go directly with Xee's API on mobile 72 | 73 | ##### I'll do this on Android 74 | 75 | Great, you'll can either deal with our [API](../api/README.md). 76 | Or you can use the [Android SDK we made for you](../android/README.md)! 77 | 78 | > Note: Be aware of the **redirect_uri** you gave, it must be `http://localhost`. 79 | 80 | ##### I'll do this on iOS 81 | 82 | Fantastic, you'll can either deal with our [API](../api/README.md). 83 | Or you can use the [iOS SDK we made for you](../ios/README.md)! 84 | 85 | > Note: Be aware of the **redirect_uri** you gave, it must be `http://localhost`. 86 | -------------------------------------------------------------------------------- /setup/scopes.md: -------------------------------------------------------------------------------- 1 | # Scopes 2 | 3 | Make a whish, get a scope 4 | 5 | ## What is a scope 6 | 7 | A *scope* is like an authorization to get a *specific resource*. 8 | 9 | For example, at Xee we provide different things: 10 | 11 | - User info 12 | - Car info 13 | - Signals data (from a Car) 14 | - Trips 15 | - Locations 16 | - ... A lot more 17 | 18 | If you build an app that does not need to access *trips*, then, why should you need to access it ? 19 | You just don't. So we wont provide your app the resource, even if you try to *call the API* 20 | 21 | Right, at this point, some of you might be like: 22 | 23 | > Wait, why wouldn't I ask for every scopes ? I does not cost anything, even if I don't call the API 24 | 25 | You're right.. You might, but be aware our authentication system will **show the user** every *scope* you're asking for. So, asking more than needed might not be the right thing to do. 26 | 27 | ## What are the scopes provided by Xee 28 | 29 | | Data you want | API that provide | scope needed | 30 | |---|---|---| 31 | |Read user info| [`/users/me`](../api/api/v3/users/me.md)
[`/users/{userId}`](../api/api/v3/users/user_id.md) | *users_read* | 32 | |Read car info| [`/users/{userId}/cars`](../api/api/v3/users/cars.md)
[`/cars/{carId}`](../api/api/v3/cars/car_id.md) | *cars_read*| 33 | |Get car trips| [`/cars/{carId}/trips`](../api/api/v3/cars/trips.md)
[`/trips/{tripId}`](../api/api/v3/trips/trip_id.md) | *trips_read*| 34 | |Get signals from car| [`/cars/{carId}/signals`](../api/api/v3/cars/signals.md)
[`/trips/{tripId}/signals`](../api/api/v3/trips/signals.md) | *signals_read*| 35 | |Get locations from car| [`/cars/{carId}/locations`](../api/api/v3/cars/locations.md)
[`/trips/{tripId}/locations`](../api/api/v3/trips/locations.md) | *locations_read*| 36 | |Get status of a car| [`/cars/{carId}/status`](../api/api/v3/cars/status.md) | *status_read*| 37 | 38 | 39 | --------------------------------------------------------------------------------