# Charging time

REST API, Service version 1.0.0

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

Computes an estimated charging time, based on energy vehicle feature (`vehicle` or `evf` parameters), connector power and charge need.

## Summary
1. Request
 1. Mandatory parameters
 2. Optional 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/chargingTime/1.0`

POST data:
```javascript
{
    "geoserver": "here",
    "vehicle": "3e34a8cc-5d3c-40ef-a296-9d43ff257329",
    "chargingPointPower": 75,
    "chargingCurrentType": "DC",
    "chargingBatteryLevel": 90
}
```

### __Parameters__

- `chargingPointPower` (number (double), required): Nominal power of connector of the charging station (in kW).
- `chargingCurrentType` (enum, required): Define the current type of charging point power.
  - `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).
- `geoserver` (string): Geoserver name.
- `swidx` (integer (int32), deprecated): Switch index.
- `vehicle` (string): Vehicle model (UUID key). Mandatory if `energyVehicleFeature` parameter is not set.
- `energyVehicleFeature` (RoutingEnergyVehicleFtr): Energy vehicle feature for energy consumption estimation. Optional if `vehicle` parameter is defined. Also accepted as `routingEnergyVehicleFeature`.
  - `scx` (number (double)): Product of vehicle's front area and aerodynamic coefficient (in m²).
  - `crr` (number (double)): Vehicle's tire rolling resistance coefficient (dimension-less, in interval ]0, 1[).
  - `engineEfficiency` (number (double)): Vehicle's efficiency coefficient between engine and gear (dimension-less, in interval ]0, 1[).
  - `batCapacity` (number (double)): Vehicle's capacity of the battery (in kWh, only if electric vehicle or hybrid re-chargeable, 0 otherwise).
  - `energyLoad` (number (double)): Vehicle's current energy load, state of charge (in kWh).
  - `dryWeight` (integer (int32)): Vehicle's weight without any consumables or passengers (in kg).
  - `payload` (integer (int32)): Vehicle's extra load (consumables or passengers weight for example) (in kg).
  - `auxConsumption` (integer (int32)): Vehicle's instantaneous auxiliary equipments consumption (in W).
  - `maxAccel` (number (double)): Maximum acceleration (superior to 0.1, in m/s², based on vehicle's acceleration capacity and expected driving behavior).
  - `maxDecel` (number (double)): Maximum deceleration (inferior to -0.1, in m/s², based on vehicle's braking capacity and expected driving behavior).
  - `extTemp` (number (float)): Outside temperature (in °C).
  - `maxChargePower` (number (double)): Maximum charge power AC single phase authorized by the vehicle (in kW).
  - `maxChargePowerAc3` (number (double)): Maximum charge power AC three phases authorized by the vehicle (in kW).
  - `maxChargePowerDc` (number (double)): Maximum charge power DC authorized by the vehicle (in kW).
  - `regenerativeBraking` (boolean): Defines if the vehicle supports regenerative braking (default = true).
- `options` (enum[]): Options of charging time service.
  - `OPTIMUM_BATTERY_CHARGE`: Calculate the optimum charge level (in %) of the vehicle battery at the given charge point; Above this level, the power delivered by the charge point decreases, and the charge takes more time.
- `temperature` (integer (int32)): Temperature in Celsius. Mandatory if `vehicle` parameter is used. Optional if `evf` parameter is used. By Default `20`.
- `remainingBatteryLevel` (number (double)): Remaining battery level in percent. Available value `0` to `100`. By default `0`. Mandatory if `vehicle` parameter is used. Optional if `evf` parameter is used.
- `connectorType` (string): Connector type ID, used to perform a power limitation based on those connector.
- `chargingBatteryLevel` (number (double)): Desired level of battery after charging (in percent, [1,100]), 100% for a full battery charge.

## Response
The calculated charging time for an electrical vehicle.

### Details of fields

- `optimumBatteryChargeLevel` (number (double)): The optimal charge level (in %) of the vehicle at the given charge point; Above this level, the power delivered by the charge point decreases, and the charge takes more time.
- `chargingTime` (integer (int64)): The estimated charging time, based on energy vehicle profile (in seconds) or -1 in case of error (that is, if battery capacity = 0, or Connector power inferior or equals to 0, or Maximum charge power inferior or equals to 0).

### Response samples
JSON Sample:
```
{
    "optimumBatteryChargeLevel": 75.0,
    "chargingTime": 1840
}
```