Get EV Awareness Charging Events API

This API fetches and delivers EV charging events to a customer's data lake/business system. It can be used for the following use cases:

Distribution system planning. A list of charging events including kW peak, time, and kWh will help distribution system planners create better models and proactively upgrade or defer upgrades down to the secondary of distribution transformers, as required.
EV programs. Knowledge of EV charging loads will help EV program groups target appropriate customers and design better rates for EV programs, optimizing marketing O&M and participation in programs.
Data scientists. Forecasting loads and creating models of EV charging behavior may be performed by data scientists in utilities for distribution system planning and EV program impacts.
Controls. Use of the real-time EV charging events to inform transformer protection, VVO, DERMS, or other applications.

MeterKey is stored in the table, which maps to the MeterID.

The 'event time' is standardized to be the start date and time of a given charging session.

UTC offset should be available as a part of the date and time input (parameters).

Get batch request and response examples

This is used to request a large data file in the format of your choice (Parquet, Orc, Json, CSV) for downloading when the request can take several minutes to complete.

Data product ID. 2d1b2602-a6ba-474b-8eb2-010fa9308dbf
Data latency. Three minutes or greater, depending on query parameters.
Maximum result size. Millions.
Data availability. Last 13 months.

Example request

Copy

POST /dpss/api/v1/subscriptions/{{SubscriptionId}}/batch-request HTTP/1.1
Host: k8s.itrontotal.com

Authorization: Bearer
Itron-CorrelationId: {{generated correlation id}}
DataSubscriberId: {{SubscriberId}}
Content-Type: application/json
Content-Length: 545

{
"filetype": "csv",
    "tokens": 
    {
        "StartEventDate": "",
        "EndEventDate": "",
        "StartReceivedDateTime": "2025-12-03",
        "EndReceivedDateTime": "",
        "Device": "",
        "ElectronicSerialNumber": "",
        "Meter": "",
        "MeterNumber": "",
        "ServicePoint": "",
        "Premises": "",
        "Transformer": "",
        "Feeder": ""
    },
    "isOhsRequest": false
}

Example response CSV

Copy

ReceivedTime,ServicePointId,MeterId,MeterNumber,ElectronicSerialNumber,TransformerId,PremiseId,ChargeStartTime,ChargeEndTime,ChargeW,ChargeDuration,ChargeEnergy
2023-09-13T00:29:55.55Z,900037xxxx,100063xxxx,100063xxxx,2.16.840.1.114416.15.80.1000xxxxxx,492954xxxx-9077xxxx,P900037xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,1237.375166,22,56.24432574
2023-09-13T00:29:55.55Z,900050xxxx,100083xxxx,100083xxx,2.16.840.1.114416.15.80.1000xxxxxx,--,P900050xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,2985.646248,3,995.215416
2023-09-13T00:29:55.55Z,900005xxxx,100009xxxx,100009xxxx,2.16.840.1.114416.15.80.1000xxxxxx,259474xxxx-9191xxxx,P900005xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,626.8082122,11,56.98256474
2023-09-13T00:29:55.55Z,900058xxxx,100044xxxx,100044xxxx,2.16.840.1.114416.15.80.1000xxxxxx,266253xxxx-1073xxxx,P900058xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,954.9134745,21,45.47207021
2023-09-13T00:29:55.55Z,900059xxxx,100050xxxx,100050xxxx,2.16.840.1.114416.15.80.1000xxxxxx,294963xxxx-9280xxxx,P900059xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,0,0,0
2023-09-13T00:29:55.55Z,900058xxxx,100007xxxx,100007xxxx,2.16.840.1.114416.15.80.10000xxxxxx,243584xxxx-9219xxxx,P900058xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,2681.166077,6,446.8610128
2023-09-13T00:29:55.55Z,900037xxxx,100083xxx,100083xxxx,2.16.840.1.114416.15.80.1000xxxxxx,449504xxxx-1079xxxx,P900037xxxx,2023-09-13T00:29:55.55Z,2023-09-13T00:29:55.55Z,5927.567965,6,987.9279942

Get on-demand request and response examples

This is used to request a smaller data set 'on demand' with very low latency.

Data product ID. 2d1b2602-a6ba-474b-8eb2-010fa9308dbf
Data latency. 1-5 seconds.
Maximum result size. 1,000 rows.
Data availability. Last 13 months.

Example request

Copy

POST /dpss/api/v1/subscriptions/{{subscriptionId}}/on-demand
Host: k8s.itrontotal.ca

   {
         "StartReceivedDatetime": "2023-1-1",
         "EndReceivedDatetime": "2023-1-31",
   }

Example response

Copy

[
    {
        "ReceivedTime": {},
        "ServicePointId": "50015xxxx_zzzz",
        "MeterId": "J440xxxx",
        "MeterNumber": "J440xxxx",
        "ElectronicSerialNumber": "2.16.840.1.114416.34.360xxxxxx",
        "TransformerId": "BOL1xxxx",
        "PremiseId": "50015xxxx_zzzz",
        "FeederId": {},
        "ChargeStartTime": "2025-11-01T15:26:33",
        "ChargeEndTime": "2025-11-01T17:07:44",
        "ChargeW": 6861,
        "ChargeDuration": 1.690000,
        "ChargeEnergy": 11570.31
    },
    {
        "ReceivedTime": {},
        "ServicePointId": "50015xxxx_zzzz",
        "MeterId": "J440xxxx",
        "MeterNumber": "J440xxxx",
        "ElectronicSerialNumber": "2.16.840.1.114416.34.360xxxxxx",
        "TransformerId": "BOL1xxxx",
        "PremiseId": "50015xxxx_zzzz",
        "FeederId": {},
        "ChargeStartTime": "2025-11-03T11:45:29",
        "ChargeEndTime": "2025-11-03T12:37:52",
        "ChargeW": 7027,
        "ChargeDuration": 0.870000,
        "ChargeEnergy": 6134.96
    },
    {
        "ReceivedTime": {},
        "ServicePointId": "50015xxxx_zzzz",
        "MeterId": "J440xxxx",
        "MeterNumber": "J440xxxx",
        "ElectronicSerialNumber": "2.16.840.1.114416.34.360xxxxxx",
        "TransformerId": "BOL1xxxx",
        "PremiseId": "50015xxxx_zzzz",
        "FeederId": {},
        "ChargeStartTime": "2025-11-03T23:53:51",
        "ChargeEndTime": "2025-11-04T01:41:02",
        "ChargeW": 6863,
        "ChargeDuration": 1.790000,
        "ChargeEnergy": 12259.98
    },
]

Parameters

Table 20
Name	Description	Operators	Required	Type	Format	Default	Range	Origination
StartEventDate	Start date being queried as Min(EventDate)	Greater than or equal to	No	Date time	YYYY-MM-DDTHH:MM:SSZ	2020-01-01T00:00:00.0Z	(Current UTC Date) to (Current UTC Date - 13 months)	Edge app
EndEventDate	End date being queried as Max(EventDate)	Less than or equal to	No	Date time	YYYY-MM-DDTHH:MM:SSZ	9999-12-31T00:00:00.0Z	(Current UTC Date) to (Current UTC Date - 13 months)	Edge app
StartReceivedDatetime	Min ReceivedTime data	Greater than or equal to	No	Date time	YYYY-MM-DDTHH:MM:SSZ	2020-01-01T00:00:00.0Z	(Current UTC Date) to (Current UTC Date - 13 months)	App Platform
EndReceivedDatetime	Max ReceivedTime data	Less than or equal to	No	Date time	YYYY-MM-DDTHH:MM:SSZ	9999-12-31T00:00:00.0Z	(Current UTC Date) to (Current UTC Date - 13 months)	App Platform
EntityType	Servicepoint, Meter, ESN, Transformer, premises, None	Equals	No	String	N/A	N/A	N/A	CIS MDMS GIS
EntityId	Dependent on EntityType	List	No	String	N/A	N/A	N/A	CIS MDMS GIS
GroupId	Future TBD. Dependent on GroupType	Equals	No					DIS
GroupType	Future TBD.	Equals	No					DIS

Data values

Table 21
Name	Description	Type	Units	Range	Format	Nullable	Origination
ServicePointId	Service point ID as of the event date and time	String	N/A	N/A	N/A	No	CIS MDMS GIS
MeterId	Meter ID as of the event date and time	String	N/A	N/A	N/A	No	CIS MDMS GIS
MeterNumber	Meter number as of the event date and time	String	N/A	N/A	N/A	Yes	CIS MDMS GIS
ESN	Electronic serial number	String	N/A	N/A	N/A	No	CIS MDMS GIS
TransformerId	Transformer ID as of the event date and time	String	N/A	N/A	N/A	Yes	CIS MDMS GIS
PremiseId	Premise ID as of the event date and time	String	N/A	N/A	N/A	Yes	CIS MDMS GIS
ReceivedTime	When the data was received by the App Platform	Date time	N/A	N/A	YYYY-MM-DDTHH:MM:SSZ	No	App Platform
ChargeStartTime	Start date and time of EV charging event	Date time	N/A	N/A	YYYY-MM-DDTHH:MM:SSZ	No	Edge app
ChargeEndTime	End date and time of EV charging event	Date time	N/A	N/A	YYYY-MM-DDTHH:MM:SSZ	No	Edge app
ChargeW	W of the EV charging event	Real	W	>0	N.NN	Yes	Edge app
ChargeDuration	Duration of the charge in hours	Integer	Hours	>0	N	Yes	Edge app
ChargeEnergy	Wh of EV charging event	Real	Watt-hours	>0	N.NN	Yes	Edge app