# Charging cost calculation

`POST https://bemap.benomad.com/bgis/service/chargingcost/1.0`

Part of [Charging time and cost](https://benomad.com/dev/doc/bemap-api/electric-mobility/charging-time-cost.md).

> **Estimate the cost of a charge.** What a charge will cost and how long it will take, for a vehicle, a connector and a price list.

Computes an estimated charging cost and time, based on vehicle, connector power, charge need and prices list.

Provisioned per account: without it, BeMap answers `400 Access Denied`.

## Request body

JSON, `Content-Type: application/json`. Schema `ChargingCostRequest`.

- `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.

## Response

`200`, schema `ChargingCostResponse`.

- `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.

## Errors

- `400`: Bad Request
- `302`: no credentials were sent. Do not follow the redirect.
- `401`: the account or the API key is wrong.

How to read each one: [Errors](https://benomad.com/dev/doc/bemap-api/getting-started/errors.md).

## Example

```bash
curl -X POST 'https://bemap.benomad.com/bgis/service/chargingcost/1.0' \
  -u 'YOUR_ACCOUNT:YOUR_API_KEY' \
  --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{
  "vehicle": "29b8cbcd-a75e-48db-a29f-c26745013d20",
  "cur": "EUR",
  "temperature": 15,
  "charges": [
    {
      "currentType": "DC",
      "power": 50,
      "curBatLvl": 20,
      "toBatLvl": 80,
      "cnnTypeId": 38,
      "currency": "EUR",
      "tariffs": [
        {
          "prices": [
            {
              "type": "ENERGY",
              "price": 0.45,
              "unit": "PER_KWH"
            }
          ]
        }
      ]
    }
  ]
}'
```

Response captured from production:

```json
{
  "estimations": [
    {
      "chargingTime": 2773,
      "energyUsed": 31.200000000000003,
      "batChargeLvl": 80,
      "chargingCost": {
        "currency": "EUR",
        "withoutVat": 14.04,
        "includeVat": 14.04
      }
    }
  ]
}
```

## Tutorials

- [Step-by-Step: Compute a Charging Cost from Charging Station and Tariffs data](https://benomad.com/dev/doc/bemap-api/guides/tutorials/chargingcost-from-charging-station-tariffs.md)

## Reference pages

- [Charging cost calculation](https://benomad.com/dev/doc/bemap-api/guides/services/chargingcost.md)