# Charging cost calculation

REST API, Service version 1.0.0

> API reference: [`POST /chargingcost/1.0`](https://benomad.com/dev/doc/bemap-api/api/electric-mobility/chargingcost.md)

Compute an estimated charging cost and time, based on vehicle, connector power, charge need, and tariffs.
The tariffs can be retrieved from the Tariffs service or Charging Station service.
The time-zone can be retrieved from the Charging Station service.

See the [tutorial of the full services process](https://benomad.com/dev/doc/bemap-api/guides/tutorials/chargingcost-from-charging-station-tariffs.md) to build a request from the Charging Station and Tariffs services.

## Summary
1. Request
 1. Parameters
2. Response
 1. Details of fields
 2. Response samples

## Request
The request must be sent with the HTTP method `POST` and the HTTP header `Content-Type` set to `application/json`.

Sample:
URI: `/bgis/service/chargingcost/1.0`

POST data:
```javascript
{
  "geoserver": "here",
  "vehicle": "d729502b-12ba-4adb-89bd-cff6a2d00919",
  "temperature": 20,
  "cur": "EUR",
  "charges": [
    {
      "curBatLvl": 23,
      "toBatLvl": 80,
      "duration": 3600,
      "currentType": "DC",
      "power": 50,
      "cnnTypeId": 39,
      "currency": "EUR",
      "tariffs": [
        {
          "prices": [
            {
              "type": "PARKING_TIME",
              "unit": "PER_HOUR",
              "price": 1,
              "vat": 20,
              "minAmount": 1
            },
            {
              "type": "ENERGY",
              "unit": "PER_KWH",
              "price": 0.5,
              "vat": 20,
              "minAmount": 1
            }
          ]
        }
      ]
    }
  ]
}
```

### Parameters

- `vehicle` (string, required): Model of vehicle (key).
- `temperature` (integer (int32), required): Temperature in Celsius.
- `charges` (ChargingCostCharge[], required): List of charging features.
  - `curBatLvl` (number (double), required): Current level of battery (in percent), Range between 0% to 100% for a full battery charge.
  - `power` (number (double), required): Nominal power of connector (in kW). For a charging station can deliver 50 kW, set the value to 50.
  - `cnnTypeId` (integer (int32), required): Connector type ID.
  - `currency` (string, required): Defined the currency used for costs calculation. Currency ISO 4217 Code.
  - `tariffs` (ChargingTariffItemFront[], required): List of tariff.
    - `prices` (ChargingPrice[], required): List of price.
      - `type` (enum, required): Type of price dimension.
        - `FLAT`: flat fee, no unit.
        - `PARKING_TIME`: time not charging, defined in hours.
        - `ENERGY`: defined in kWh.
        - `TIME`: time charging, defined in hours.
      - `price` (number (float), required): Price per unit (excluding VAT) for this tariff dimension.
      - `unit` (enum): Unit of price.
        - `NA`
        - `PER_HOUR`
        - `PER_KWH`
      - `vat` (number (float)): Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.
      - `minAmount` (number (float)): Minimum amount to be billed.
    - `restriction` (ChargingPriceRestriction): Restriction information of prices.
      - `startTime` (string): Start time of day (hh:mm).
      - `endTime` (string): End time of day (hh:mm).
      - `startDate` (string): Start date (AAAA-MM-DD).
      - `endDate` (string): End date (AAAA-MM-DD).
      - `minKwh` (number (float)): Minimum used energy in kWh for this tariff to be valid.
      - `maxKwh` (number (float)): Maximum used energy in kWh for this tariff to be valid.
      - `minPower` (number (double)): Minimum power in kW for this tariff to be valid.
      - `maxPower` (number (double)): Maximum power in kW for this tariff to be valid.
      - `minDuration` (integer (int32)): Minimum duration in seconds for this tariff to be valid.
      - `maxDuration` (integer (int32)): Maximum duration in seconds for this tariff to be valid.
      - `dayOfWeek` (enum[]): List of day of the week for this tariff to be valid. Values can be MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
        - `MONDAY`
        - `TUESDAY`
        - `WEDNESDAY`
        - `THURSDAY`
        - `FRIDAY`
        - `SATURDAY`
        - `SUNDAY`
  - `minPrice` (ChargingPriceTaxFront): Minimum price for a charging session with this tariff.
    - `excludeTax` (number (float), required): Represents the price of a charge without a tax.
    - `includeTax` (number (float), required): Represents the price of a charge with tax. The amount of money of this tax that is due.
    - `name` (string): The name of the tax. The intention is that Parties use short names where possible, e.g. VAT.
  - `maxPrice` (ChargingPriceTaxFront): Maximum price for a charging session with this tariff.
    - `excludeTax` (number (float), required): Represents the price of a charge without a tax.
    - `includeTax` (number (float), required): Represents the price of a charge with tax. The amount of money of this tax that is due.
    - `name` (string): The name of the tax. The intention is that Parties use short names where possible, e.g. VAT.
  - `toBatLvl` (number (double)): Desired level of battery after charging (in percent), 100% for a full battery charge. For a full charge, set the value to 100. For a charge to 80% of battery capacity set the value to 80.
  - `duration` (integer (int64)): Maximum desired time spent to the charge (in seconds).
  - `currentType` (enum): Current type (AC/DC).
    - `NA`: Not available (NA).
    - `AC`: Alternating current (AC), but the number of phases is not available.
    - `AC_SINGLE_PHASE`: Alternating current (AC), single phase.
    - `AC_THREE_PHASES`: Alternating current (AC), three phases.
    - `DC`: Direct current (DC).
  - `startDateTime` (string): The time when this tariff becomes active, in UTC, the time_zone field of the Location can be used to convert to local time. Typically used for a new tariff already given with the location, before it becomes active.
  - `endDateTime` (string): The time after which this tariff is no longer valid, in UTC, time_zone field if the Location can be used to convert to local time. Typically used when this tariff is going to be replaced with a different tariff soon.
  - `timeZone` (string): Time zone. The value must come from the Pool `timeZone` field. One of IANA tzdata's TZ-values representing the time zone of the location. Examples: "Europe/Oslo", "Europe/Zurich". (http://www.iana.org/time-zones)
- `geoserver` (string): Geoserver name.
- `swidx` (integer (int32), deprecated): Switch index.
- `time` (integer (int64)): Time stamp (in milliseconds). Defines the date and time will be used to apply the price restrictions.
- `cur` (string): Defined the currency used for costs calculation. Currency ISO 4217 Code.

See the [Currency Codes](https://benomad.com/dev/doc/bemap-api/guides/services/currency-codes.md) service to get the available codes.

## Response
List of calculated charging cost and time for an electrical vehicle. The list is in order of inputs.

### Details of fields

- `estimations` (ChargingCostEstimation[]): List of estimated cost and time.
  - `chargingTime` (integer (int64)): Charging time in seconds.
  - `energyUsed` (number (double)): Energy used in kW to make the charge.
  - `batChargeLvl` (number (double)): The charge level (in %) of the vehicle at the given charge point.
  - `chargingCost` (ChargingCost): Charging cost.
    - `currency` (string): Currency ISO 4217 Code.
    - `withoutVat` (number (float)): Price without VAT.
    - `includeVat` (number (float)): Price include VAT.

See the [Currency Codes](https://benomad.com/dev/doc/bemap-api/guides/services/currency-codes.md) service to get the available codes.

### Response samples
JSON Sample:
```javascript
{
  "estimations": [
    {
      "chargingTime": 2462,
      "energyUsed": 34.2,
      "batChargeLvl": 80,
      "chargingCost": {
        "currency": "EUR",
        "withoutVat": 17.1,
        "includeVat": 20.52
      }
    }
  ]
}
```