Device data

After understanding the Enode user and device lifecycle, an important aspect of the API is reading data from connected devices and designing how that information will fit into your overall application.

Copy linkBasic data fetching

After connecting vendors, you can use the API to fetch the information about devices that the user has associated with those vendors.

All device types on Enode have the ability to be listed, for example via our List VehiclesAPI endpoint:

Sample

curl {API_URL}/vehicles \
-X GET \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Listing is a convenient way to discover device IDs that you can fetch individually via endpoints like Get VehicleAPI:

Sample

curl {API_URL}/vehicles/{vehicleId} \
-X GET \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \

Copy linkKeeping data fresh

Data returned in the API reflects our latest understanding of the device, and Enode constantly keeps track of all connected devices and their latest information.

Data freshness varies across vendors and devices, but Enode employs various data refresh techniques that ensure device data is as up-to-date as possible:

Data refresh type	Description
Real-time events	We receive data change events (e.g., a vehicle was plugged in) directly from vendors as soon as they know a value has changed. Enode supports these event subscriptions for select fields from a growing number of vendors.
"Active" updates	When a device is actively consuming energy (e.g., a vehicle is charging or an HVAC is pumping heat), data updates will be more frequent. The actual update frequency varies by vendor and device type, but this is typically every 2 minutes (1 minute for HVACs).
Regular updates	If we don't receive real-time events and a device isn't active, data will be updated on our regular update cycle. The actual update frequency varies by vendor and device type, but this is typically every 7 minutes (2 minutes for HVACs).

Across all device types, fields found in API device response objects describe different dimensions of data freshness:

isReachable: indicates whether Enode can currently connect to and communicate with the vendor cloud. (For HVACs and Chargers, this also represents whether the device itself is online.)
lastSeen: the last time Enode successfully communicated with the vendor cloud. (For HVACs and Chargers, this also represents the last time the device itself was online.)
lastUpdated: found on fields like chargeState, this reflects how fresh specific data is. Whenever possible, this value will reflect the value reported by the device itself; otherwise, we fall back to when we last observed the data change.

Copy linkKeep data fresh with webhooks

The examples above to list and fetch individual devices is great for testing our API and to discover devices when a user first connects a vendor. However, they’re not recommended for ensuring your application has the most up-to-date information possible, and you should use webhooks instead.

Enode will send your application a webhook event whenever the data from a vendor or its devices changes without you needing to ask our API. This can include changes like:

Enode discovered a new device for a vendor already linked to a user
state of charge is updated for a vehicle (including when someone plugs it in)
smart charging status for a vehicle gets updated

Integrating with webhooks provides the most real-time information possible and makes your application most efficient. See our webhooks guide for the list of supported events and more information about building an effective webhook integration.

If your application cannot support webhooks, you can consider using infrequent polling of our API as an alternative.

Copy linkForce a data refresh

Any time you fetch data from the API, Enode effectively returns data that we have cached on our servers in order to ensure fast response times. So long as we can talk with a vendor’s cloud service, this cache will never be older than 2 or 7-10 minutes, as described above.

However, there may be times when you truly need the latest vendor information, such as during debugging or helping your operational staff diagnose connectivity issues in real time. In times like this, you can ask Enode to accelerate the next time we ask for device information by calling the refresh hint endpointsAPI available on some devices.

Copy linkBest practices

Copy linkPlan your data models

Recall that linking accounts to users happens at the vendor level, not device level. When a vendor account is connected to an Enode user, all devices for that vendor account will be linked to that user.

You may want to consider the following when designing your data model:

How many different vendors will a typical user connect?
How many individual devices will a user have per vendor?
Will multiple users want access the same vendor account or device in your app?

Our recommendation is to start simple but keep these in mind for future growth and scale.

Copy linkDecouple your IDs from Enode’s systems

Some Enode resource IDs are supplied by you instead of generated by the API, including tariffs, charging locations, and user IDs. For greatest flexibility, we recommend decoupling your application’s primary keys and IDs on Enode.

Copy linkImplementing basic flows

In general, we recommend caching our webhook results and rendering data based on your cache. It’s also useful to independently keep a log of state changes for devices, such as when smart charging status changes.
For list views, you may consider calling our list endpoints; same for showing a detail view of a device.
If a user requests more up-to-date info (e.g., via pull-to-refresh), you can query the API to check fields like isReachable or lastSeen to ensure freshness. Only in rare circumstances should you call /refresh-hint.

Copy linkDisplaying aggregated data and analytics

Enode supports various StatisticsAPI endpoints that returns rolled up data over a specified period of time. Instead of aggregating longitudinal data yourself, we recommend using this functionality.
For charging specifically, you can group by Charging SessionAPI instead of over time.

Previous articleUser and device lifecycle

Next articleControlling devices