Cars Truecost | Climes API

---

This endpoint provides the truecost value for cars (upto 10 cars per request).

Request Parameters

Request Schema

This is the schema for the cars truecost api. Each request payload requires queries

Queries Schema

Each queries object has a cars array which requires individual car object.

Name Description	Type	Optional
cars	This is an array of individual cars whose truecost needs to be calculated.	array	required

Cars Schema

Name Description	Type	Optional
car_id	This field has to generated and sent from your end. This has to be unique in order to map each car truecost data to its original request for tallying purposes.	unique string	required
body_type	The body type for this car, must be one of hatchback , sedan , suv , luxury_suv , luxury_sedan	string	required
fuel_type	The fuel type of this car, must be one of petrol , diesel , cng , petrol_cng , electric	string	required
registration_year	The year of registration of the car in YYYY format	number	required
mileage	The mileage of the car as a number	number	required
distance_travelled	The distance the car has travelled so far	number	required

Endpoint

/v3/cars

Method

POST

Headers

{
    'x-api-key': 'API_KEY',
    'Content-Type': 'application/json'
}

Payload

{
    "queries": {
        "cars": [
            {
                "car_id": "10363087788",
                "body_type": "suv",
                "fuel_type": "diesel",
                "registration_year": 2022,
                "mileage": 20,
                "distance_travelled": 10956
            },
            {
                "car_id": "16977138789",
                "body_type": "hatchback",
                "fuel_type": "petrol",
                "registration_year": 2017,
                "mileage": 27.39,
                "distance_travelled": 34976
            }
        ]
    }
}

caution

The length of the cars array should not be more than 10 individual objects per request.

Response Parameters

Response Schema

Name	Description	Type
message	A human readable string describing response for the given request.	string
truecost	This object contains the calculated truecost values in tonnes CO2e for the request.	object
car_id	The car_id that was sent during the request for each object request	string
truecost	Calculated truecost value in tonnes CO2e for that object of request	number
trees_planted	The comparable value for trees planted for the truecost value for this object	number

caution

The error message is for your information, not the end users.
Please use the status codes and communicate the error to user accordingly
The API returns the first validation error that is encountered even if there are multiple errors with the request

Status Code

200

Response Data

{
    "message": "Truecost calculated successfully",
    "truecost": [
        {
            "car_id": "10363087788",
            "truecost": 14886.5,
            "trees_planted": 676.6590909090909
        },
        {
            "car_id": "16977138789",
            "truecost": 12711.75976633808,
            "trees_planted": 577.8072621062764
        }
    ]
}

tip

Here the response will be in the same order as the request values.

Sample Request

cURL

curl --location --request POST 'BASE_URL/v3/cars'  
--header 'x-api-key: API_KEY'  
--header 'Content-Type: application/json'  
--data-raw '{
    "queries": {
        "cars": [
            {
                "car_id": "10363087788",
                "body_type": "suv",
                "fuel_type": "diesel",
                "registration_year": 2022,
                "mileage": 20,
                "distance_travelled": 10956
            },
            {
                "car_id": "16977138789",
                "body_type": "hatchback",
                "fuel_type": "petrol",
                "registration_year": 2017,
                "mileage": 27.39,
                "distance_travelled": 34976
            }
        ]
    }
}'

NodeJs

const fetch = require('node-fetch');

const url = 'BASE_URL/v3/cars';
const apiKey = 'API_KEY';

const headers = {
  'x-api-key': apiKey,
  'Content-Type': 'application/json'
};

const body = JSON.stringify({
    "queries": {
        "cars": [
            {
                "car_id": "10363087788",
                "body_type": "suv",
                "fuel_type": "diesel",
                "registration_year": 2022,
                "mileage": 20,
                "distance_travelled": 10956
            },
            {
                "car_id": "16977138789",
                "body_type": "hatchback",
                "fuel_type": "petrol",
                "registration_year": 2017,
                "mileage": 27.39,
                "distance_travelled": 34976
            }
        ]
    }
});

const options = {
  method: 'POST',
  headers: headers,
  body: body
};

fetch(url, options)
  .then(response => response.text())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Axios

var axios = require('axios');

var data = JSON.stringify({
  "queries": {
    "cars": [
      {
        "car_id": "10363087788",
        "body_type": "suv",
        "fuel_type": "diesel",
        "registration_year": 2022,
        "mileage": 20,
        "distance_travelled": 10956
      },
      {
        "car_id": "16977138789",
        "body_type": "hatchback",
        "fuel_type": "petrol",
        "registration_year": 2017,
        "mileage": 27.39,
        "distance_travelled": 34976
      }
    ]
  }
});

var config = {
  method: 'post',
  url: 'BASE_URL/v3/cars',
  headers: { 
    'x-api-key': 'API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
import json

url = "BASE_URL/v3/cars"

payload = json.dumps({
  "queries": {
    "cars": [
      {
        "car_id": "10363087788",
        "body_type": "suv",
        "fuel_type": "diesel",
        "registration_year": 2022,
        "mileage": 20,
        "distance_travelled": 10956
      },
      {
        "car_id": "16977138789",
        "body_type": "hatchback",
        "fuel_type": "petrol",
        "registration_year": 2017,
        "mileage": 27.39,
        "distance_travelled": 34976
      }
    ]
  }
})
headers = {
  'x-api-key': 'API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Php

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('BASE_URL/v3/cars');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'x-api-key' => 'API_KEY',
  'Content-Type' => 'application/json'
));
$request->setBody('{
    "queries": {
        "cars": [
            {
                "car_id": "10363087788",
                "body_type": "suv",
                "fuel_type": "diesel",
                "registration_year": 2022,
                "mileage": 20,
                "distance_travelled": 10956
            },
            {
                "car_id": "16977138789",
                "body_type": "hatchback",
                "fuel_type": "petrol",
                "registration_year": 2017,
                "mileage": 27.39,
                "distance_travelled": 34976
            }
        ]
    }
}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

Below are sample responses for the above request.

Responses

Success - 200

{
  "message": "Truecost calculated successfully",
  "truecost": [
    {
      "car_id": "10363087788",
      "truecost": 14886.5,
      "trees_planed": 676.6590909090909
    },
    {
      "car_id": "16977138789",
      "truecost": 12711.75976633808,
      "trees_planed": 577.8072621062764
    }
  ]
}

Failure - 400

{
  "message": "Bad Request! Please send all the variables properly."
}

Failure - 500

{
  "message": "Server Error! Failed to get Cars Truecost."
}