Articles in this section

Pricing API

Niklas Wallner
  • Updated
Follow

What is the Pricing API used for?

Via the Pricing API, the EMP receives information about the tariffs used at the individual charging station connectors. The API is secured with a token, which you can see in be.ENERGISED under Settings/System Settings/API Settings.

Please note that the API requires a paid subscription.

The token must be passed as header x-api-token within each request.

 

Prerequisites to use the Pricing API

  • You have created an API token in the be.ENERGISED backend.
  • You can see charging stations in your backend (either roaming stations or your own stations).
  • You have configured a tariff that is assigned to at least one authentication medium.

 

Sample curl request:

curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/?evseId=AT*HTB*E00008&tag_id=123456ABC' \
--header 'x-api-token: your_token'

 

Endpoints

The API offers multiple endpoints to receive the data for either a specific EVSE-ID, a list of EVSE-IDs or a full fetch method.

 

api/pricing - single EVSE-ID

The single EVSE-ID endpoint creates a pricing structure for one EVSE-ID and authentication media combination. The endpoint accepts the following parameters.

 

Parameter Required Description
evseId yes Compliant with the following to calculate the stepCosts: specification for EVSE ID from “eMI3”. e.g. BE-BEC-E041503001”
tag_id, emaid, authendicationUuid yes Tag ID, EMAID or UUID from the card/token - only one of those three can be used at once
consumption no fictional consumption in Wh which will be used in the calculation. If left empty, no calculation will be done
duration, duration_in_minutes no total duration in seconds or minutes. If left empty no calculation will be done
currency no desired currency. If left empty default settings will be used
include_tax no includes the tax which would be used for this cost rate (tax field will be not present if not set to true)

 

Sample Request for a single EVSE-ID

Parameter Value Description
evseId DE*EEE*E000001  
tag_id SOMETHING  
consumption 90000 in Wh which are 90 kWh
duration 1000 value in seconds 
curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/?evseId=DE*EEE*E000001&tag_id=SOMETHING&consumption=90000&duration=1000' \
--header 'x-api-token: your_token'

 

Response

{
    "rateName": "Standard-Verkaufstarif eMSP",
    "costId": 2206,
    "currency": "EUR",
    "localCurrency": "EUR",
    "costTotalLocalCurrency": 36,
    "currencyConversionRate": 1,
    "costTotal": 36,
    "costTime": 0,
    "costPower": 36,
    "priceStructure": {
        "energy": {
            "unit": "Wh",
            "elements": [
                {
                    "intervalChange": 100,
                    "stepCosts": 0,
                    "intervalCosts": 0
                },
                {
                    "intervalChange": 101,
                    "stepCosts": 0.0404,
                    "intervalCosts": 40.4
                },
                {
                    "intervalChange": 102,
                    "stepCosts": 0.0004,
                    "intervalCosts": 0.4
                },
                {
                    "intervalChange": 100000,
                    "stepCosts": 35.9592,
                    "intervalCosts": 0.4
                }
            ]
        },
        "time": {
            "unit": "min",
            "elements": []
        }
    }
}

 

Sample Request for a single EVSE-ID with a desired currency

Parameter Value Description
evseId CH*CHI*E00193  
tag_id SOMETHING  
consumption 80000 in Wh which are 80 kWh
duration 1 value in seconds
currency CHF currency following the ISO standard 
curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/?evseId=CH*CHI*E00193&tag_id=SOMETHING&consumption=80000&duration=1&currency=CHF' \
--header 'x-api-token: your_token'

 

Response

{
    "rateName": "Standard-Verkaufstarif eMSP",
    "costId": 2020,
    "currency": "CHF",
    "localCurrency": "EUR",
    "costTotalLocalCurrency": 48.863,
    "currencyConversionRate": 1.0642,
    "costTotal": 52,
    "costTime": 0,
    "costPower": 52,
    "priceStructure": {
        "energy": {
            "unit": "Wh",
            "elements": [
                {
                    "intervalChange": 100,
                    "stepCosts": 0,
                    "intervalCosts": 0
                },
                {
                    "intervalChange": 101,
                    "stepCosts": 0.06565,
                    "intervalCosts": 65.65
                },
                {
                    "intervalChange": 102,
                    "stepCosts": 51.93435,
                    "intervalCosts": 0.65
                }
            ]
        },
        "time": {
            "unit": "min",
            "elements": []
        }
    }
}

 

Sample Request for a single EVSE-ID with tax

Parameter Value Description
evseId CH*CHI*E00193  
tag_id SOMETHING  
include_tax   add tax to price structure 
curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/?evseId=CH*CHI*E00193&tag_id=SOMETHING&include_tax' \
--header 'x-api-token: your_token'

 

Response

{
    "rateName": "Standard-Verkaufstarif eMSP",
    "costId": 2020,
    "currency": "CHF",
    "localCurrency": "EUR",
    "costTotalLocalCurrency": 48.863,
    "currencyConversionRate": 1.0642,
    "costTotal": 52,
    "costTime": 0,
    "costPower": 52,
    "priceStructure": {
        "energy": {
            "unit": "Wh",
            "elements": [
                {
                    "intervalChange": 100,
                    "stepCosts": 0,
                    "intervalCosts": 0
                },
                {
                    "intervalChange": 101,
                    "stepCosts": 0.06565,
                    "intervalCosts": 65.65
                },
                {
                    "intervalChange": 102,
                    "stepCosts": 51.93435,
                    "intervalCosts": 0.65
                }
            ],
            "tax": 1.87
        },
        "time": {
            "unit": "min",
            "elements": [],
            "tax": 1.24
        }
    }
}

 

api/batch - list of EVSE-IDs

The batch EVSE-ID endpoint creates a pricing structure for a list of given EVSE-IDs.

Parameter Required Description
evseIds yes Compliant with the following to calculate the stepCosts: specification for EVSE ID from “eMI3”. e.g. BE-BEC-E041503001 - comma separated
tag_id, emaid, authendicationUuid yes Tag ID, EMAID or UUID from the card/token - only one of those three can be used at once
consumption no fictional consumption in Wh which will be used in the calculation. If left empty no calculation will be done
duration, duration_in_minutes no total duration in seconds or minutes. If left empty no calculation will be done
currency no desired currency. If left empty default settings will be used

 

Sample Request for the batch request

Parameter Value Description
evseIds CH*AAA*E00001,AT*AAA*E00001 comma separated list of evse ids
tag_id SOMETHING   
curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/batch?evseIds=CH*AAA*E00001,AT*AAA*E00001tag_id=SOMETHING' \
--header 'x-api-token: your_token'

 

Response

{
    "CH*AAA*E00001": {
        "rateName": "xxx Tariff",
        "costId": 1234,
        "currency": "EUR",
        "localCurrency": "EUR",
        "costTotalLocalCurrency": null,
        "currencyConversionRate": 1,
        "costTotal": null,
        "costTime": null,
        "costPower": null,
        "priceStructure": {
            "energy": {
                "unit": "Wh",
                "elements": [
                    {
                        "intervalChange": 100,
                        "intervalCosts": 0,
                        "stepCosts": null
                    },
                    {
                        "intervalChange": 101,
                        "intervalCosts": 60.6,
                        "stepCosts": null
                    },
                    {
                        "intervalChange": 102,
                        "intervalCosts": 0.6,
                        "stepCosts": null
                    }
                ]
            },
            "time": {
                "unit": "min",
                "elements": []
            }
        }
    },
    "AT*AAA*E00001": {
        "rateName": "xxx Tariff",
        "costId": 1234,
        "currency": "EUR",
        "localCurrency": "EUR",
        "costTotalLocalCurrency": null,
        "currencyConversionRate": 1,
        "costTotal": null,
        "costTime": null,
        "costPower": null,
        "priceStructure": {
            "energy": {
                "unit": "Wh",
                "elements": [
                    {
                        "intervalChange": 100,
                        "intervalCosts": 0,
                        "stepCosts": null
                    },
                    {
                        "intervalChange": 101,
                        "intervalCosts": 60.6,
                        "stepCosts": null
                    },
                    {
                        "intervalChange": 102,
                        "intervalCosts": 0.6,
                        "stepCosts": null
                    }
                ]
            },
            "time": {
                "unit": "min",
                "elements": []
            }
        }
    }
}

 

api/all_paged - paginated list of prices per EVSE-ID

The all_paged endpoint allows the user of the API to receive all EVSE-IDs and their rate mappings reachable on the given client. The pagination happens cursor based, the cursor received from the response can be used to get the next page.

Parameter Required Description
cursor yes Unique identifier for a specific record, start for next page, first cursor equals start. If not on the first page use the last cursor received.
limit yes Specifying the maximum page size
tag_id, emaid, authendicationUuid yes Tag Id, emaid or uuid from the card/token - only one of those three can be used at once

 

Sample Request for the paginated request

Parameter Value Description
tag_id SOMETHING  
limit 100 100 entries will be returned
cursor start initial cursor value 
curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/all_paged?tag_id=SOMETHING&limit=100&cursor=start' \
--header 'x-api-token: your_token'

 

Response

{
    "pagination": {
        "nextCursorId": "80afa4ff-a4c4-4a36-972b-c3bd70120de2",
        "isLastPage": false
    },
    "data": {
        "CH*AAA*E00001": {
            "rateName": "xxx Tariff",
            "costId": 1234,
            "currency": "EUR",
            "localCurrency": "EUR",
            "costTotalLocalCurrency": null,
            "currencyConversionRate": 1,
            "costTotal": null,
            "costTime": null,
            "costPower": null,
            "priceStructure": {
                "energy": {
                    "unit": "Wh",
                    "elements": [
                        {
                            "intervalChange": 100,
                            "intervalCosts": 0,
                            "stepCosts": null
                        },
                        {
                            "intervalChange": 101,
                            "intervalCosts": 60.6,
                            "stepCosts": null
                        },
                        {
                            "intervalChange": 102,
                            "intervalCosts": 0.6,
                            "stepCosts": null
                        }
                    ]
                },
                "time": {
                    "unit": "min",
                    "elements": []
                }
            }
        }
    }
}

 

Next page should be fetched with:

curl --location --request GET 'https://yourinstancename.beenergised.cloud/api/pricing/all_paged?tag_id=SOMETHING&limit=100&cursor=80afa4ff-a4c4-4a36-972b-c3bd70120de2' \
--header 'x-api-token: your_token'

Version: 2022-10-14 05:23:57 UTC

Related articles

Comments

0 comments

Article is closed for comments.