GetEVDetectPremises API

This API fetches and delivers premises where electric vehicles have charged, whithin a user-defined date range.

Example use cases.

Distribution system planning. A list of charging events including kW peak, time, and kWh to 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 to 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.

Get bulk request and response examples

Data product ID.
Data latency. Three minutes or greater, depending on query parameters.
Data availability. Last 13 months.

All examples in this section are presented as cURL or CSV files.

Request

Copy

POST /data-products/8e08938a-160a-4dea-b0ff-a96a7933f5c6 /subscriptions/{subscriptionId}/batch-request
{
    "FileType": "Csv",
    "Tokens":
    {
        "StartReceivedDatetime": "2023-1-1",
        "EndReceivedDatetime": "2023-1-31",
        "StartEventDate": "2023-1-1",
        "EndEventDate": "2023-1-31",
        "EntityType": "Transformer",
        "EntityId": "X1-01-A",
    }
}

Response

Copy

ServicePointId ,MeterId,MeterNumber,ElectronicSerialNumber,TransformerId,PremiseId,ChargeStartTime,ChargeEndTime,AvgLoad,AvgVoltage,AvgVoltageBeforeCharge,ReceivedTime
9000372474,1000634831,1000634831,2.16.840.1.114416.15.80.1000634831,4929542183-90777887,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,44.38334,112.59,120.32,2023-09-13T00:29:55.55Z
9000502815,1000838385,1000838385,2.16.840.1.114416.15.80.1000838385,--,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,128.1167,112.67,120.03,2023-09-13T00:29:55.55Z
9000053282,1000092413,1000092413,2.16.840.1.114416.15.80.1000092413,2594744147-91918635,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,148.7167,111.94,120.45,2023-09-13T00:29:55.55Z
9000585414,1000448760,1000448760,2.16.840.1.114416.15.80.1000448760,2662535221-10734063,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,176.55,112.48,120.42,2023-09-13T00:29:55.55Z
9000594308,1000508737,1000508737,2.16.840.1.114416.15.80.1000508737,2949637457-92808645,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,111.8667,112.05,120.06,2023-09-13T00:29:55.55Z
9000580263,1000071660,1000071660,2.16.840.1.114416.15.80.1000071660,2435841314-92195447,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,221.2667,112.30,120.12,2023-09-13T00:29:55.55Z
9000372477,1000836297,1000836297,2.16.840.1.114416.15.80.1000836297,4495046038-10795431,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,104.4,112.80,120.01,2023-09-13T00:29:55.55Z
9000007738,1000561269,1000561269,2.16.840.1.114416.15.80.1000561269,2604141857-10581404,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,185.5167,112.31,120.16,2023-09-13T00:29:55.55Z
9000389087,1000326772,1000326772,2.16.840.1.114416.15.80.1000326772,2768938379-10477102,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,152.65,112.05,120.31,2023-09-13T00:29:55.55Z
9000530026,1000062826,1000062826,2.16.840.1.114416.15.80.1000062826,2302540356-10169202,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,196.4,112.66,120.31,2023-09-13T00:29:55.55Z
9000098919,1000567185,1000567185,2.16.840.1.114416.15.80.1000567185,3393042722-93886808,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,167.1167,112.75,120.29,2023-09-13T00:29:55.55Z
9001805366,1000846429,1000846429,2.16.840.1.114416.15.80.1000846429,--,,2023-09-13T00:29:55.55Z,2023-09-13T00:59:55.55Z,34.23333,112.06,120.74,2023-09-13T00:29:55.55Z

Get synchronous request and response examples

Data latency. 1-5 seconds.
Maximum result size. 1,000 rows.
Data availability. Last 13 months.

Request

Copy

GET /v1/{tenantid}/di/apps/ev/chargeevents

     {
         "StartReceivedDatetime": "2023-1-1",
         "EndReceivedDatetime": "2023-1-31",
         "EntityType": "Transformer",
         "EntityId": "X1-01-A"
     }

Response

Copy

[
 {
   "ServicePointID": 9000372474,
   "MeterId": 1000634831,
   "MeterNumber": 1000634831,
   "ElectronicSerialNumber": "2.16.840.1.114416.15.80.1000634831",
   "TransformerID": "4929542183-90777887",
   "PremiseId": "",
   "ChargeStartTime": "2023-09-13T00:29:55.55Z",
   "ChargeEndTime": "2023-09-13T00:59:55.55Z",
   "AvgLoad": 44.38334,
   "AvgVoltage": 112.59,
   "AvgVoltageBeforeCharge": 120.32,
   "ReceivedTime": "2023-09-13T00:29:55.55Z"
 },
 {
   "ServicePointID": 9000502815,
   "MeterId": 1000838385,
   "MeterNumber": 1000838385,
   "ElectronicSerialNumber": "2.16.840.1.114416.15.80.1000838385",
   "TransformerID": "--",
   "PremiseId": "",
   "ChargeStartTime": "2023-09-13T00:29:55.55Z",
   "ChargeEndTime": "2023-09-13T00:59:55.55Z",
   "AvgLoad": 128.1167,
   "AvgVoltage": 112.67,
   "AvgVoltageBeforeCharge": 120.03,
   "ReceivedTime": "2023-09-13T00:29:55.55Z"
 }]

Parameters

Name	Description	Operators	Required	Type	Format	Default	Range	Origination
StartEventDate	Start date being queried as Min(EventDate)	Greater than or equal to	No	Datetime	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	Datetime	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	Datetime	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	Datetime	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	In list	No	String	N/A	N/A	N/A	CIS MDMS GIS
GroupID	Future. Dependent on GroupType	In list	No	String	N/A	N/A	N/A	DIS
GroupType	Future	Equals	No	String	N/A	N/A	N/A	DIS
HasEV	Flag to retrieve premises with, without, or all premises with EV detection. Valid values; 0 = no EV 1 = has EV 2 = both	Equals	No		N/A	1	N/A

Data values

Name	Description	Type	Units	Range	Format	Nullable	Origination
ServicePointId	Service Point ID as of EventDate	String	N/A	N/A	N/A	No	CIS MDMS GIS
MeterId	Meter ID as of EventDate	String	N/A	N/A	N/A	No	CIS MDMS GIS
MeterNumber	Meter Number as of EventDate	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 EventDate	String	N/A	N/A	N/A	Yes	CIS MDMS GIS
PremiseId	Premise ID as of EventDate	String	N/A	N/A	N/A	Yes	CIS MDMS GIS
ReceivedTime	When the data was received in the data lake	Datetime	N/A	N/A	YYYY-MM-DDTHH:MM:SSZ	No	App Platform
EndLastEVCharge	End date and time of the last detected EV charge	Datetime	N/A	N/A	YYYY-MM-DDTHH:MM:SSZ	No	EV Detection agent
AvgEVSECharge	Average EVSE (electric vehicle supply equipment) energy used per charge session.	Real	kWh	N/A			EV Detection agent
AvgPeak	Average peak kW of EV charging sessions	Real	kW	0 to 655.35			EV Detection agent
MeanDuration	Mean charge duration of a charging session		hours	0 to 1024			EV Detection agent
AverageDailyNumChargeSessions	Average number os charge sessions per day		hours	0 to 1024			EV Detection agent
DateFirstDetected	Date first detected as tracked by the application	Datetime					EV Detection agent
DateFirstDetectedinRange	Date first detected as tracked by the application within the date range specified	Datetime					EV Detection agent
HasEV	Flag to retrieve premises with, without, or all premises with EV Detection Valid values: 0 = no EV 1 = has EV 2 = both						EV Detection agent
EVStatusUpdateTime	Timestamp at which the status has been updated between states of having EV charging or no EV charging	Datetime					EV Detection agent