BeMapAPI
BeMap 4.1.0
API reference: POST /2.0/evsmartrouting

Illustration of near POI service

REST API, Service version 2.0.0

EV smart routing · v2.0#

EV Smart Routing service#

Performs a route calculation dedicated to electric vehicles. If the autonomy of the vehicle is not sufficient to reach final destination, this service returns a route which includes deviations through charging stations (aka step points). If the optimization criteria is fastest the calculated route optimizes the overall time (driving + charging) to reach the final destination.

Request#

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

Sample:

End-point URI: /bgis/service/2.0/evsmartrouting.

HTTP header: Content-Type: application/json.

POST data:

javascript
{
  "geoserver": "here",
  "csps": [
    "gireve"
  ],
  "vehicle": {
    "initBatLvl": 70,
    "key": "06b5c02d-ba2e-4b14-8b2b-6d793aac0da0",
    "payload": 75
  },
  "start": {
    "lon": 2.3414,
    "lat": 48.85717
  },
  "stop": {
    "lon": 3.569,
    "lat": 47.79602
  },
  "condition": {
    "minBatLvl": 10,
    "minArrivalBatLvl": 15,
    "temperature": 20,
    "currency": "EUR",
    "encodedGeometry": true,
    "departureTime": 1704905400000,
    "chargePluggingTime": 300
  }
}

All coordinates are defined by longitude and latitude, see the coordinate system glossary for more details.

Parameters#

  • vehicleVehiclerequired

    Vehicle model (UUID key).

    Vehicle fields
    • keystringrequired

      The vehicle's UUID key. You can fin the UUID key in the API Vehicles.

    • initBatLvlnumber (float)

      Initial battery level in percent. Available value 0 to 100. Default value 100.

    • payloadinteger (int32)

      Vehicle's payload in kg (i.e: passengers, luggage and consumables weight). 75 kg by default.

    • featureVehicleFeatureFront

      Vehicle features is used to set the information about the vehicle.

      VehicleFeatureFront fields
      • heightinteger (int32)

        Height of vehicle in centimeters. Affects route calculation. Physical restriction.

      • widthinteger (int32)

        Width of vehicle in centimeters. Affects route calculation. Physical restriction.

      • lengthinteger (int32)

        Length of vehicle in centimeters. Affects route calculation. Physical restriction.

      • weightinteger (int32)

        Weight of vehicle in tens of metric tons, i.e.: 35 = 3.5t. Affects route calculation. Legal and physical restrictions.

      • axleWeightinteger (int32)

        Axle weight in tens of metric tons, i.e.: 12 = 1.2t. Affects route calculation. Legal and physical restrictions.

      • hazardousMaterialsenum

        Hazardous materials carried by the vehicle. Affects route calculation. Legal restriction.

        25 accepted values
        NONENo hazardous material.
        ALLGeneral hazardous materials.
        EXPLOSIVETrucks with Explosive and Flammable Goods.
        WATERTrucks with Goods Harmful for Water.
        US_CORROSIVEUSA only : Corrosive materials (e.g., hydrochloric acid, sulfuric acid, mercury, sodium hydroxide).
        US_EXPLOSIVESUSA only : Explosives (e.g., TNT, ammunition, flares, fireworks).
        US_FLAMUSA only : Flammable and combustible liquids (e.g., jet fuel, gasoline, fuel oil, alcohols).
        US_FLAM_SOLUSA only : Flammable solids, spontaneously combustible materials and water reactive substances (e.g., matches, white phosphorus, potassium).
        US_GASUSA only : Flammable, compressed and poisonous gases (e.g., propane, compressed oxygen, chlorine).
        US_ORGANICUSA only : Oxidizers and organic peroxides (e.g., ammonium nitrate and benzoyl peroxide).
        US_OTHERUSA only : Miscellaneous hazardous materials (e.g., asbestos, dry ice, lithium batteries).
        US_PIHUSA only : Poisonous inhalation hazards (PIH).
        US_POISONUSA only : Poisonous (toxic) and infectious substances (e.g., cyanide, most mercury-based compounds, viruses, toxins and regulated medical waste).
        US_RADIO_ACTIVEUSA only : Radioactive materials (e.g., plutonium-239 and uranium-235).
        TUNNEL_CAT_BTunnel Category B.
        TUNNEL_CAT_B1000CTunnel Category B1000C.
        TUNNEL_CAT_BDTunnel Category B/D.
        TUNNEL_CAT_BETunnel Category B/E.
        TUNNEL_CAT_CTunnel Category C.
        TUNNEL_CAT_C5000DTunnel Category C5000D.
        TUNNEL_CAT_CDTunnel Category C/D.
        TUNNEL_CAT_CETunnel Category C/E.
        TUNNEL_CAT_DTunnel Category D.
        TUNNEL_CAT_DETunnel Category D/E.
        TUNNEL_CAT_ETunnel Category E.
      • nbTrailerinteger (int32)

        Vehicle's number of trailers (-1: not defined, 0: no trailer). Affects route calculation. Legal restriction.

      • tollTransportCategoryenum

        Defines the toll vehicle category. Affects toll calculation. UNDEFINED by default.

        13 accepted values
        UNDEFINEDUndefined.
        MOTORCYCLEMotorcycle.
        AUTOAutomobile.
        TRUCKTruck.
        MOTOR_HOMEMotor home.
        MINIBUSMini bus.
        BUSBus.
        SIDECARSidecar (EU only).
        TRICYCLETricycle (EU only).
        DLV_TRUCKDelivery truck (EU only).
        SNOWMOBILESnowmobile (US only).
        PICK_UPPick up (US only).
        TRACTORTractor (US only).
      • caravanenum

        Defines if the vehicle has a caravan. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • hybridenum

        Defines if vehicle has a hybrid engine. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • disEquippedenum

        Defines if vehicle is equipped for disabled people. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • pollMinenum

        Defines if vehicle has minimal pollution. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • hovenum

        Defines if vehicle is a High Occupancy Vehicle (USA only). See Wikipedia: High-occupancy vehicle lane. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • cialenum

        Defines if vehicle is a commercial vehicle. Affects toll calculation. UNDEFINED by default.

        3 accepted values
        UNDEFINEDUndefined.
        YESYes.
        NONo.
      • nbVehAxlesinteger (int32)

        Defines the number of axles of the vehicle (optional). Affects toll calculation.

      • nbTrailAxlesinteger (int32)

        Defines the number of axles of the trailer (optional). Affects toll calculation.

      • nbTiresinteger (int32)

        Defines the number of tires (optional). Affects toll calculation.

      • nbPassengersinteger (int32)

        Defines the number of passengers (optional). Affects toll calculation.

      • vehHeightinteger (int32)

        Defines vehicle's height in centimeters (optional, use field height to define total height : vehicle + trailer). Affects toll calculation.

      • trailHeightinteger (int32)

        Defines trailer's height in centimeters (optional, use field height to define total height : vehicle + trailer). Affects toll calculation.

      • vehWeightinteger (int32)

        Defines vehicle's weight in tens of tons (optional, use field weight to define total weight : vehicle + trailer). Affects toll calculation.

      • emissionClassenum

        Defines vehicle's emission type (optional). See Wikipedia: European emission standards. Affects toll calculation.

        18 accepted values
        UNDEFINEDUndefined.
        EURO1EURO I.
        EURO2EURO II.
        EURO3EURO III.
        EURO4EURO IV.
        EURO5EURO V.
        EURO6EURO VI.
        EURO_EEVEURO EEV.
        ELECTRICEURO Electric.
        EURO0EURO 0
        EURO2_PRCEURO II with PRC (Particle Reduction Composite/System)
        EURO3_PRCEURO III with PRC (Particle Reduction Composite/System)
        EURO6_CO2_1EURO VI CO2 1
        EURO6_CO2_2EURO VI CO2 2
        EURO6_CO2_3EURO VI CO2 3
        EURO6_CO2_4EURO VI CO2 4
        EURO6_CO2_5EURO VI CO2 5
        MAXMaximal value.
      • adrTunnelCategoryenum

        ADR tunnel category defines all supported ADR (EU only, European Agreement concerning the International Carriage of Dangerous Goods by Road). Affects route calculation.

        5 accepted values
        NONENo tunnel category restriction (category A).
        CAT_BTunnel Category B.
        CAT_CTunnel Category C.
        CAT_DTunnel Category D.
        CAT_ETunnel Category E.
      • onlyPhysicalboolean

        Defines if vehicle's weight (weight, weight per axle and trailers) and hazardous materials (hazardous materials and ADR) should be ignored outside respectively bridges and tunnels. false by default. Affects route calculation.

  • startPlacerequired

    Departure coordinates (start point).

    Place fields
    • lonnumber (double)required

      Longitude in degrees decimal (WGS84).

    • latnumber (double)required

      Latitude in degrees decimal (WGS84).

    • altnumber (double)

      Altitude in meters.

    • headingnumber (double)

      Heading angle in degrees (optional). For BeNomad engine: If the angle is not available, set this field and speed field to 0.

    • speednumber (float)

      Speed in km/h (optional). For BeNomad engine: Use this field only if the heading is available.

    • timeinteger (int64)

      GPS time in milliseconds.

    • satinteger (int32)

      Number of satellites available.

    • radiusinteger (int32)

      Radius in meters around the coordinate. This radius defines the maximum distance the route calculation should approach the coordinate.

    • ignorePointboolean

      Defines if this coordinate is ignored by the route calculation. false by default.

    • ignoreTrafficDirectionsboolean

      Defines if traffic directions should be ignored by route calculation between this waypoint and the next one. false by default.

    • ignoreRestrictionsboolean

      Defines if forbidden maneuvers and blocked passages should be ignored by route calculation between this coordinate and the next one. false by default.

    • avoidUTurnboolean

      Defines if a UTurn should be avoided by route calculation on this coordinate. Not defined by default.

    • useStartAngleboolean

      If set to true and coordinate is located on a two-way road and heading is defined, coordinate's heading will be used as a general direction for departure from this coordinate. See the heading parameter. Not defined by default.

    • useStopRoadSideboolean

      Defines if route calculation must arrive on this coordinate on its side (if coordinate is on a two-way road). Not defined by default.

  • stopPlacerequired

    Arrival coordinates (stop point).

    Place fields
    • lonnumber (double)required

      Longitude in degrees decimal (WGS84).

    • latnumber (double)required

      Latitude in degrees decimal (WGS84).

    • altnumber (double)

      Altitude in meters.

    • headingnumber (double)

      Heading angle in degrees (optional). For BeNomad engine: If the angle is not available, set this field and speed field to 0.

    • speednumber (float)

      Speed in km/h (optional). For BeNomad engine: Use this field only if the heading is available.

    • timeinteger (int64)

      GPS time in milliseconds.

    • satinteger (int32)

      Number of satellites available.

    • radiusinteger (int32)

      Radius in meters around the coordinate. This radius defines the maximum distance the route calculation should approach the coordinate.

    • ignorePointboolean

      Defines if this coordinate is ignored by the route calculation. false by default.

    • ignoreTrafficDirectionsboolean

      Defines if traffic directions should be ignored by route calculation between this waypoint and the next one. false by default.

    • ignoreRestrictionsboolean

      Defines if forbidden maneuvers and blocked passages should be ignored by route calculation between this coordinate and the next one. false by default.

    • avoidUTurnboolean

      Defines if a UTurn should be avoided by route calculation on this coordinate. Not defined by default.

    • useStartAngleboolean

      If set to true and coordinate is located on a two-way road and heading is defined, coordinate's heading will be used as a general direction for departure from this coordinate. See the heading parameter. Not defined by default.

    • useStopRoadSideboolean

      Defines if route calculation must arrive on this coordinate on its side (if coordinate is on a two-way road). Not defined by default.

  • geoserverstring

    Geoserver name.

  • swidxinteger (int32)

    Switch index.

  • cspsstring[]

    List of charging station provider names.

  • csfsVersionbase64 string

    Represents the version of the filtering logic used in the charging station search query. This field determines which filtering implementation or algorithm is applied during processing. The default is 1. The available values are: 1, 2.

  • csfsstring[]

    List of charging station filter, return only the points matching the filters. Documentation of available filters.

  • tariffChargePassHashIdsstring[]

    List of eligible charge pass hash IDs (retrieved from the Charge Pass Service). The backend will select the applicable charge pass based on station, provider, and tariff compatibility to propose the lowest cost for a charge. The effectively applied charge pass is returned in chargingCost section.

  • conditionCondition

    Condition of trip, that contains the options and settings parameters like weather, battery levels, etc.

    Condition fields
    • optimModeenum

      Optimization mode.

      3 accepted values
      FASTESTFind the route which optimizes travel time. Default value.
      SHORTESTFind the route which optimizes travel distance.
      ECO_ENERGYFind the route which optimizes travel energy consumption.
    • criteriasenum[]

      The EV's list of criterias.

      7 accepted values
      AVOID_FERRIESFind a route with no ferry.
      AVOID_MOTORWAYSFind a route without motorways.
      AVOID_TOLLSFind a route with no toll.
      AVOID_UNPAVEDFind a route with no unpaved roads.
      AVOID_CROSSING_BORDERFind a route without country border crossing (makes sence only when the start and stop points are in the same country).
      LESS_EXPENSIVEFind the less expensive charging stations. Only with algorithm v2. Deprecated.
      TRAFFICUse traffic info for route calculation.
    • alternativebase64 string

      Index of alternative route. 0 to disable. 0 by default.

    • startUTurnThresholdinteger (int32)

      Specifies the start UTurn threshold. This value determines, at start point or any via point for which a use start angle / avoid UTurn property is set, the threshold (in 1/10th seconds / meters / Wh in resp. FASTEST / SHORTEST / ECO mode) above which the property may be ignored (default = 3000). For instance, in SHORTEST mode, if the route from start to stop leaving start point in the desired direction is more than startUTurnThreshold meters longer than the route from start to stop leaving start point in the opposite direction, leave the start point in the opposite direction.

    • departureTimestring

      This parameter is an EPOCH time stamp in milliseconds (UTC) or can take an string with ISO local date time format like '2011-12-03T10:15:30', '2011-12-03T10:15:30+01:00' or '2011-12-03T10:15:30+01:00[Europe/Paris]'. It is used to define the date and time of routing departure.

    • temperatureinteger (int32)

      Temperature in Celsius. Not used if weather is enabled. 20 by default.

    • minBatLvlnumber (float)

      Minimal battery level during the journey. This value is in percent. Available value 0 to 100.

    • minArrivalBatLvlnumber (float)

      Minimal battery level at destination. This value is in percent. Available value 0 to 100. The value of minArrivalBatLvl must be superior or equals to the value of minBatLvl. If the value of minArrivalBatLvl is lower than minBatLvl, the value of minBatLvl will be used instead of minArrivalBatLvl.

    • maxAfterChargeBatLvlnumber (float)

      Maximal battery level after a charge. This value is in percent. Available value 0 to 100.

    • connectorTypesinteger (int32)[]

      List of connector type ID, used to perform a filtration based on those connector.

    • chargingStationDeprecatedConnectorboolean

      Set to true to enable the support of charging station deprecated connector types. False by default.

    • chargePluggingTimeinteger (int32)

      Defines the fixed additional time in seconds for each charging stop. 300 by default.

    • chargeTimeSlotsChargeTimeSlot[]

      List of step-point time slots. Note: If forced charges are defined, they take priority over charge times.

      ChargeTimeSlot fields
      • durationinteger (int32)required

        Stop duration in seconds.

      • startDateTimestring

        Start local date time in text format ISO YYYY-MM-DDThh:mm:ss (eg: 2020-09-08T12:28:00).

      • stopDateTimestring

        Stop local date time in text format ISO YYYY-MM-DDThh:mm:ss (eg: 2020-09-08T12:28:00).

      • serviceCategorystring

        Service category. Semantics:
        - !: not (unary).
        - |: or (binary).
        - &: and (binary).
        - (: open section.
        - ): close section.
        - any numeric value.
        Example: (7315|9105)&!7395
        See the Class ID list in Glossary menu.

      • maxWalkingDistanceinteger (int32)

        Maximum walking distance in meters to the service(s) POI. Value range [50, 1000] between the step point and the service(s). 1000 meters by default.

    • restrictedEvseboolean

      Accept the restricted charging stations.

    • allowNaStatusboolean

      Allow use of pools with NA availability status. False by default.

    • ignoreAvailableStatusboolean

      Allow use of any pool regardless of availability status. False by default.

    • drivingStyleDrivingStyle

      Driving style definition for an electric vehicle.

      DrivingStyle fields
      • modeenumrequired

        Define the driving mode.

        4 accepted values
        ECOReduce the acceleration/deceleration, auxiliary consumption and prefer the national road over the high-ways.
        NORMALUse the speed limitation in vehicles database.
        SPORTNo speed limitation (only the legal speed limit of roads). Increase the acceleration/deceleration. Prefer the high-ways.
        CUSTOMAllow to override ponderation parameters.
      • allowOverVehSpdLimboolean

        Allows to define a maximum speed above the vehicle's maximum speed defined in the vehicle's database.

      • limitMaxSpeedinteger (int32)

        Defines vehicle's maximum speed in km/h used during the routing calculation. By default null. If null, uses the maximum speed defined in the vehicle's database. Note that if the speed is greater than the one defined in the database, it will be bounded by the later except if you activate the parameter allowOverVehSpdLim.

      • maxAccnumber (double)

        Average vehicle's acceleration in m/s². Must be > 0. For example: 1.25 m/s².

      • maxDecnumber (double)

        Average vehicle's deceleration in m/s². Must be < 0. For example: -1.25 m/s².

      • spsSpeedPonderationFront[]

        Speed weight coefficient for the specified road network level. A value < 1 will reduce speeds. A value > 1 will increase speeds.

        SpeedPonderationFront fields
        • factornumber (float)required

          Specifies a new ponderation factor for speeds (Default = 1). A value under 0 to reduce the speed, i.g: 0.8. A value upper to 1 for increase the speed, i.g: 1.3.

        • levelinteger (int32)required

          Road network level (0: all 4 levels, 1: main level, 2: secondary level, 3: third level, 4: fourth level).

        • roadTypeenum

          Define the road type.

          7 accepted values
          ALLAll road network.
          DEFAULTDefault.
          FERRYFerries way.
          MOTORWAYMotor-way.
          PEDESTRIANPedestrian.
          ROUNDABOUNTRoundabout.
          SLIPROADSlip road.
        • pondTypeenum

          Define the ponderation type.

          3 accepted values
          ALLSpeed coefficient applies both for finding the fastest route and calculating its ETA. Default value.
          CALSpeed coefficient applies only searching for the fastest route.
          ETASpeed coefficient applies only for calculating route's travel time (ETA).
    • allowMaxSpeedRecommendationboolean

      Allow to calculate the maximum speeds to reach destination or step-point. Since algorithm v3.

    • routesheetboolean

      Enable the route-sheet.

    • routesheetLanguagestring

      Define the language that will be used to render the text of route-sheet.

    • routesheetModeenum

      Define the output mode of route-sheet: only text, only details and both. TEXT by default.

      3 accepted values
      TEXTRender only the text information.
      DETAILSRender only the detailed information in separated fields.
      TEXT_DETAILSRender both text and details information.
    • routesheetVerboseLevelenum

      Select the information details level of route-sheet.

      3 accepted values
      LOWLow verbosity, the minimal information about the route-sheet instruction will be returned.
      MEDIUMMedium verbosity, the normal information about the route-sheet instruction will be returned.
      HIGHHigh verbosity, the maximum details information about the route-sheet instruction will be returned.
    • geometryboolean

      Set to true to enable the polyline otherwise set to false. True by default.

    • encodedGeometryboolean

      Set to true to enable the encoded polyline. False by default.

    • co2emissionsboolean

      If set to true CO2 emissions will be calculated in the journey, set to false by default.

    • weatherboolean

      Enable the weather information.

    • weatherProviderstring

      Define the weather provider.

    • currencystring

      Define the currency used for costs calculation. Currency ISO 4217 Code.

    • routeDetailsboolean

      Set to true to enable the route events detailed information like consumption, speed, altitude, etc. False by default. See the RouteConsumptionFront class for more details about the returned values.

    • routeDetailsFreqinteger (int32)

      Frequency in seconds of route event. 60 seconds by default which is also the minimal authorized value.

    • tollCostboolean

      Set to true to enable the toll cost calculation and toll events along the route. False by default.

  • viasVia[]

    List of via places.

    Via fields
    • lonnumber (double)required

      Longitude in degrees decimal (WGS84).

    • latnumber (double)required

      Latitude in degrees decimal (WGS84).

    • altnumber (double)

      Altitude in meters.

    • headingnumber (double)

      Heading angle in degrees (optional). For BeNomad engine: If the angle is not available, set this field and speed field to 0.

    • speednumber (float)

      Speed in km/h (optional). For BeNomad engine: Use this field only if the heading is available.

    • timeinteger (int64)

      GPS time in milliseconds.

    • satinteger (int32)

      Number of satellites available.

    • radiusinteger (int32)

      Radius in meters around the coordinate. This radius defines the maximum distance the route calculation should approach the coordinate.

    • ignorePointboolean

      Defines if this coordinate is ignored by the route calculation. false by default.

    • ignoreTrafficDirectionsboolean

      Defines if traffic directions should be ignored by route calculation between this waypoint and the next one. false by default.

    • ignoreRestrictionsboolean

      Defines if forbidden maneuvers and blocked passages should be ignored by route calculation between this coordinate and the next one. false by default.

    • avoidUTurnboolean

      Defines if a UTurn should be avoided by route calculation on this coordinate. Not defined by default.

    • useStartAngleboolean

      If set to true and coordinate is located on a two-way road and heading is defined, coordinate's heading will be used as a general direction for departure from this coordinate. See the heading parameter. Not defined by default.

    • useStopRoadSideboolean

      Defines if route calculation must arrive on this coordinate on its side (if coordinate is on a two-way road). Not defined by default.

    • stopDurationinteger (int32)

      Stop duration in seconds associated to the destination coordinate. By default 0. Note: if charging times are defined. Forced charges take priority over charge times. Note: only about forced charge, stop duration could be linked chargeMaxDist in case of forced charge. To ensure that charge duration is superior to stopDuration + FixedStopTime in EV Smart Routing, the stop duration used is min(stopDuration, KB_MIN_CHARGE_DURATION + FixedStopTime). However the original value stopDuration is not modified.

    • chargeMaxDistanceinteger (int32)

      This parameter should be defined to impose a charge around this destination. It defines the maximum walking distance 3000 meters a charge point can be from this destination to force a charge (0 means no charge forced). By default 0. NOTE: If you combine this parameter with the stopDuration parameter it will define how much time can be used for charging.

    • transportTypeenum

      Transport type associated to the destination coordinate. Useful for discriminating between passenger car, taxi and emergency.

      9 accepted values
      PEDESTRIANPedestrian.
      BICYCLEBicycle.
      MOTORCYCLEMotorcycle.
      CARPassenger car, tourist car.
      TAXITaxi.
      PUBLIC_BUSPublic bus.
      EMERGENCYEmergency vehicle.
      DELIVERY_TRUCKDelivery truck.
      TRUCKTruck.
    • maxSpeedinteger (int32)

      Maximum Speed in km/h associated to this destination coordinate. If not 0 this will force routing calculation to bound all driving speeds between this destination and the next one. If 0 the global maximum speed will be used if defined. By default 0.

    • ignoreVehicleProfileboolean

      Ignore vehicle profile status.

To get the complete list of available connector types, see the Charging station connector service.

See the Currency Codes service to get the available codes.

Response#

Details of fields#

  • journeysJourney[]required

    Describes the whole itinerary which can be composed of multiple journeys.

    Journey fields
    • summarySummaryrequired

      Summary of journey information.

      Summary fields
      • vehicleInfoVehicleInfoV2required

        Vehicle information used to compute the journey.

        VehicleInfoV2 fields
        • brandstringrequired

          Brand name.

        • namestringrequired

          Model name of vehicle.

        • variantstring

          Variant of model.

        • yearstring

          Year of vehicle model.

      • distanceinteger (int64)required

        Distance: sum of distance, in meters.

      • durationinteger (int64)required

        Duration: sum of duration, in seconds.

      • batteryLevelnumber (double)required

        Remaining battery level (in percentage) at the end of the trip.

      • consumednumber (double)required

        Sum of consumed values in kWh.

      • chargingTimeinteger (int64)required

        Sum of charging time in seconds.

      • departureTimeinteger (int64)required

        Departure time in milliseconds.

      • arrivalTimeinteger (int64)required

        Arrival time in milliseconds.

      • boundingBoxBoundingBoxFrontrequired

        The rectangle that encompasses the entire trip, defined by four coordinates.

        BoundingBoxFront fields
        • minLonnumber (double)

          Minimum longitude, in degrees decimal (WGS84).

        • minLatnumber (double)

          Minimum latitude, in degrees decimal (WGS84).

        • maxLonnumber (double)

          Maximum longitude, in degrees decimal (WGS84).

        • maxLatnumber (double)

          Maximum latitude, in degrees decimal (WGS84).

      • savedCo2Emissionsnumber (float)

        Saved CO2 Emissions (kg). This value is calculated from the amount of energy consumed for this journey using the profile of an ICE vehicle similar to the selected electric vehicle.

      • chargingCostChargingCostFront

        Sum of charging cost.

        ChargingCostFront fields
        • currencystring

          Currency ISO 4217 Code.

        • withoutVatnumber (float)

          Price without VAT.

        • includeVatnumber (float)

          Price include VAT.

        • tariffChargePassHashIdstring

          Represents the hashed identifier for tariff charge passes that used to calculate the cost.

      • tollSumFeesTollSumFeesFront

        Sum of toll cost.

        TollSumFeesFront fields
        • currencystring

          Currency in norm ISO 4217, more details on Wikipedia ISO 4217 https://en.wikipedia.org/wiki/ISO_4217.

        • feeMinnumber (double)

          The minimum fee.

        • feeMaxnumber (double)

          The maximum fee.

    • eventsEvent[]required

      Describes all information along the computed journey.

      Event fields
      • eventTypeenumrequired

        The event's type.

        8 accepted values
        STARTStart point, event contains information about the start location of trip.
        STOPStop point, event contains information about the stop location of trip.
        VIAVia point, event contains information about the way-point location of trip.
        CHARGECharge step, event contains information about the charge step location of trip.
        ROUTERoute, that represent the route information about part of trip.
        TOLLToll along the journey.
        EXCEPTIONException event can show the information about a error on the API conversion between backend and frontend.
        NOT_SUPPORTED_ENUMThe event type is not supported by this API version, please check if a newer API is already released.
    • timeSlotWarnsTimeSlotWarning[]

      List of warnings about the time slots request.

      TimeSlotWarning fields
      • statusCodestringrequired

        Code of the time slot status. Available codes:
        - TSS_UNINITIALIZED: Time slot status uninitialized.
        - TSS_NO_POOL_FOUND: No pool found during this time slot (default value before EVRoute computation).
        - TSS_NO_POOL_FOUND_WITH_SERVICE: No pool found with the requested services.
        - TSS_NOT_SELECTED_TOO_MUCH_ENERGY_NEEDED: Too much additional energy needed to reach pools during this time slot.
        - TSS_NOT_SELECTED_OPENING_TIME: Opening Time are incorrect for pools found during these time slot.
        - TSS_NOT_SELECTED: Route with the pools found during this time slot validate less time slot that this current itinerary OR charge during time slot is useless.
        - TSS_IGNORED_DEPARTURE_DATE_TIME_NOT_SET: Time slot ignored: Departure date and time is not set.
        - TSS_IGNORED_END_BEFORE_DEPARTURE: Time slot ignored: Time slot end is before route departure OR stop duration implied to stop before route departure.
        - TSS_IGNORED_BEGIN_AFTER_ARRIVAL: Time slot ignored: Time slot begins after arrival date and time.
        - TSS_IGNORED_INTERNAL_ERROR: Time slot ignored: Internal error.
        - TSS_NOT_VALID_BEGIN_AFTER_END: Time slot not valid: Time slot begins after time slot end.
        - TSS_NOT_VALID_DURATION_TOO_SHORT: Time slot not valid: Stop duration is too short (should be superior to fixed stop time).
        - TSS_NOT_VALID_DURATION_TOO_LONG: Time slot not valid: Stop duration is too long (should be inferior to time slot duration).
        - TSS_NOT_VALID_SERVICE: Time slot not valid: Requested service format is incorrect").

      • messagestringrequired

        Describes a time slot status: if the time slot has been validated by a EV route.

  • logTagstring

    Log tag is an UUID tag used during the request calculation.

See chapter Google Encoded Polyline Algorithm Format of full description of encoding format.

Response samples#

JSON Sample:

javascript
{
  "journeys": [
    {
      "summary": {
        "vehicleInfo": {
          "brand": "Renault",
          "name": "Zoe 2",
          "year": "2019"
        },
        "distance": 169756,
        "duration": 7394,
        "batteryLevel": 15,
        "consumed": 34.13,
        "chargingTime": 467,
        "departureTime": 1704905690000,
        "arrivalTime": 1704913551000,
        "boundingBox": {
          "minLon": 2.3059,
          "minLat": 47.79602,
          "maxLon": 3.56947,
          "maxLat": 48.85848
        }
      },
      "events": [
        {
          "eventType": "START",
          "coord": {
            "lon": 2.3413990156969615,
            "lat": 48.85717
          },
          "address": "Pont Neuf, 75001 Paris, France",
          "departureTime": 1704905690000000
        },
        {
          "eventType": "ROUTE",
          "distance": 136762,
          "duration": 5501,
          "consumed": 27.512743964305944,
          "encodedGeometry": "ileiHwhhMGEKI[WYUu@g@ . . . TJLJDJAl@dG"
        },
        {
          "eventType": "CHARGE",
          "coord": {
            "lon": 3.243228,
            "lat": 47.93862
          },
          "arrivalTime": 1704911191000,
          "departureTime": 1704911958000,
          "arrivalBatteryLevel": 16.51411128574597,
          "departureBatteryLevel": 27.796459405101274,
          "chargingTime": 467,
          "chargingPower": {
            "currentType": "DC",
            "power": 50,
            "cnnTypeId": 38
          },
          "pool": {
            "providerName": "gireve",
            "providerMode": "LOCAL",
            "id": "402548",
            "sourceProvider": "Gireve",
            "updateDate": 1680318107013,
            "brand": "SDEY",
            "name": "SDEY/L4SV657FSZ",
            "countryCode": "FRA",
            "address": {
              "countryCode": "FR",
              "city": "Sépeaux-Saint Romain",
              "postalCode": "89116",
              "street": "D943"
            },
            "accessibility": "PUBLIC",
            "entrance": {
              "lon": 3.243228,
              "lat": 47.93862
            },
            "phoneNumber": "+33970830213",
            "availabilityStatus": "IN_SERVICE",
            "open24x7": false,
            "numberOfParkingSpace": 2,
            "comment": "Sepeaux, Echangeur A6 Sur Cd945",
            "stations": [
              {
                "id": "525614",
                "nature": "REAL",
                "availabilityStatus": "IN_SERVICE",
                "coordinate": {
                  "lon": 3.243228,
                  "lat": 47.93862
                },
                "authenticationModes": [
                  "RFID_BADGE",
                  "NA"
                ],
                "paymentModes": [
                  "OPERATOR_CONTRACT"
                ],
                "bookable": false,
                "chargingPoints": [
                  {
                    "id": "1168662",
                    "operatorId": "FR*S89*EVRFW*2",
                    "availabilityStatus": "IN_SERVICE",
                    "currentType": "DC",
                    "voltage": 400,
                    "ampere": 125,
                    "power": 50,
                    "type": 38,
                    "connectorTypes": [
                      {
                        "id": 38,
                        "key": "TYPE_2-CABLE_COMBO_CCS",
                        "deprecated": false,
                        "name": "Type 2 Combo",
                        "norm": "Combo Type 2 based, DC",
                        "maxPower": 350,
                        "acSingle": false,
                        "acThree": false,
                        "dc": true,
                        "cable": true
                      }
                    ]
                  }
                ]
              }
            ]
          }
        },
        {
          "eventType": "ROUTE",
          "distance": 32994,
          "duration": 1593,
          "consumed": 6.615769512437353,
          "encodedGeometry": "o_rcHqmxRb@YL|ASTER?PFRHJXDPQF . . . KLUPDP@"
        },
        {
          "eventType": "STOP",
          "coord": {
            "lon": 3.568998979043319,
            "lat": 47.79602
          },
          "address": "Place Charles Lepère, 89000 Auxerre, France",
          "departureTime": 7094
        }
      ]
    }
  ]
}

ErrorResponse object#

If an error occurs during the process on server side, only an error object will be returned in the response. See Error example chapter.

  • code: error code. See the Error list chapter.
  • message: error message.
  • coordinate: coordinate of error (optional).
  • lon: longitude of coordinate in decimal degrees (WGS84).
  • lat: latitude of coordinate in decimal degrees (WGS84).
Error codes#

List of all possible error codes:

CodeDescription
OKNo error.
CANNOT_PERFORM_CHARGINGTIMEThe charging time estimation cannot be performed.
CANNOT_PERFORM_ROUTINGThe routing calculation cannot be performed with the input coordinates.
CHARGING_STATION_NOT_FOUNDCannot find any charging station.
CANNOT_GET_CONNECTOR_TYPESIssue to get the list of connector types.
COORDINATE_NOT_MATCHOne of the input coordinates cannot be matched on a road.
INTERNAL_ERRORThe server cannot perform the routing calculation for internal service reason.
NO_REACHABLE_STEP_POINTNo charging stations found are reachable.
OVER_ALLOWED_DISTANCEToo many charges required (maximum charges = 16)
RouteNotFoundExceptionThe initial route cannot be found.
TooMuchViaExceptionToo much via coordinates in request.
ViaNotMatchExceptionOne of via coordinate of request cannot be map matched.
NotEnoughViaExceptionThe via coordinates cannot be map matched. A minimal of 2 coordinates must be map matched to perform a route.
VehicleFeatureIsRequiredExceptionThe vehicle feature is required. The vehicle must be checked.
VehicleProfileIsRequiredExceptionThe vehicle profile is required. The vehicle must be checked.
RequestsQuotasExceededExceptionWhen a "hard" quotas limit is reached. See the quotas service API to check the quotas limits "soft" and "hard".
Error example#
javascript
{
   "error": {
      "code": "NO_REACHABLE_STEP_POINT",
      "message": "All charging stations found cannot be reachable. Around this coordinate.",
      "coordinate": {
         "lon": 8.193691832353528,
         "lat": 45.42630127240513
      }
   }
}

All coordinates are defined by longitude and latitude, see the coordinate system glossary for more details.