Some software providers also want to be responsible for the collection of data for their customers. Instead of each customer having their own Metry account, you as a software provider can have a single Metry account collecting data for all customers. What kind of model to use will depend on your service and how you like to work.
Benefits of consolidating all collection in one Metry account
- Your customers are reluctant to sign up for Metry themselves.
- You already take care of the collection for your customers and prefer to not change your service offering or how you work.
Benefits of customers having their own Metry account
- Existing Metry users with collection already setup can start using your service with little to no setup time.
- Customers can set up the collection in Metry themselves so that they don’t need to provide you with their credentials to utility providers’ customer pages.
- Customers can resolve issues with collection themselves, letting you as a developer focus on building your software.
- Resolving collection issues are generally more convenient as Metry can be in contact with the one holding the utility contract.
- The customer can be billed for the usage of Metry while you as a developer can build on top of Metry for free.
Getting started
As all data will exist on your own account, you will not need to create a developer account. Instead, you will use the private access token for the account at which all collection is configured. The private access token can be found when signed in to Metry. Go to Settings--> Access token to view your token. If you don't have a token, click the Create access token link to generate one. Please note that you need to have Administrator access privileges in Metry Portal to be able to view and generate the token. Read more about it here
Setting up collection
When first setting up collection on your account you will have an option to use either classic or property manager data collection. Using the property manager collection structure is usually most appropriate. It will allow you to create separate “subaccounts” for each of your customers that you can manage from your account and they will automatically share all their meters to your account.
However, there is a case where some software providers have a single account in the utility provider’s customer pages with all their customers data. In this case, using separate subaccounts may not be a fitting solution. In that case go with classic data collection. The only downside with this is that meters found will not automatically have a reference to the customer as they would if they are collected under a subaccount and may need to be structured manually using the tree structure or using another method.
Structuring collection with subaccounts
Mapping subaccounts to your customers
When setting up a subaccount, it can be useful to set the external ID to an identifier you have for the customer in your system to be able to map the meters to the correct customer. This will be stored in the property “custom_identifier” on the account in the API response.
Listing subaccounts
Subaccounts can be found in the API with the path “/accounts/me/subaccounts”. Only the first 50 will be included. Use the “skip” query parameter to get the next 50, 100, etc.
Finding a customer’s meters from a subaccount
Meters in your account collected under a subaccount will all be available on your account with a reference to the subaccount with the “assigner” property. It can also be used in a query to search for meters like so “/meters?assigner._id={subaccount_id}”.
Structuring collection with tree structure
Mapping tree nodes to your customers
When adding a tree node, you can optionally enter an external ID that can be an ID of the customer in your system. This can be useful to programmatically find all meters that belong to a specific customer via the Metry API.
Finding a customer’s meters within a tree node
Meters structured in a tree will have the tree position information in a property called “active_box_tree_paths”. If you have mapped a tree node to a customer in your system, you can use the tree node’s _id property to find meters added underneath it using the query “/meters?tree_structure_ids={tree_node_id}”.
Accessing time series data
There are two approaches to getting time series data for consumption and cost from Metry. One is to continuously import all data from Metry and save it in your own database. The other is to query time series data from our API at the time of creating the report or visualisation without using an intermediary storage. The best approach will depend on the needs of your application.
Importing data to your own database
The way to import data is to either use the Streams or Exports API. All new data in Metry will be available in the stream or exported files and can be imported by your system. If your system is already built to import files with data, exports may be the best option. If your system can poll data from an HTTP API, then using streams to import data can be the better option.
Importing data to your own database can be the better option in the following cases:
- You have an existing system that is already built to query data from your own database.
- You need to aggregate data for a lot of buildings and meters to generate reports and visualisation which can not be done efficiently at runtime using the Metry API.
Querying time series data at runtime
It is possible to get data for a specified meter, period and metrics using the Consumptions and Costs API endpoints. See the API reference for how to do it.
Querying time series data directly from the API can be the better option in the following cases:
- You don’t already have a storage and query solution for time series data in your application.
- You don’t need to make any complex or heavy aggregation of data that would be infeasible to do at runtime.