Getting Started with API Calls - m3ter Documentation

This topic helps you get started making API calls as a Service User to the m3ter platform. It explains how to quickly get set up to make API calls and provides example calls to help you reach a point where you can begin to submit usage data measurements as a Service User:

If you are using Postman, you can import some sample m3ter collections into your Workspace. If you have downloaded the m3ter Open API spec, you can also import this as a collection into your Workspace in Postman:

Importing m3ter Collections into your Postman Workspace

Tip: Example Code Snippets. The API call examples include code snippets that you can copy to your clipboard in JSON, cURL, or Python Requests versions.

Setting Up for Service User API Calls

Follow these steps to get set up as a Service User able to make API calls to m3ter:

Step 1: Create a Service User and add Permissions

Log in to the m3ter Console and under Settings>Users, create a Service User.
Add required Permissions to the new Service User. You must assign Administrator Permissions to a Service User to allow that user to make API calls. See Adding Permissions to Service Users.

More Details? For details of how to complete this step, see Creating and Configuring Service Users.

Step 2: Generate Access Keys for the Service User.

In the Console, open the Overview page for a Service User and generate an Access Key id and Api Secret.
Make sure you make a copy of the Api Secret.

More Details? For details on how to complete this step, see Generating an API Key and Secret for a Service User.

Step 3: Use Basic Authentication to obtain a Bearer Token.

We maintain an OAuth 2.0 Client Credentials grant type authentication flow for Service User Authentication.
From your preferred OAuth 2.0 client, submit a request to the m3ter OAuth Client Credentials authentication flow using the Access Key id and Api Secret to obtain a Bearer Token for your Service User.
You will need the Bearer Token to make any subsequent API calls.

More Details? For more details on how to complete this step, see Obtaining a Bearer Token Using Basic Auth and see the Auth section of our API Reference Docs.

Step 4: Copy your Organization Id.

When you’ve obtained your Service User Bearer Token at Step 3, you’ll also need a copy of your Organization Id to make any subsequent API calls.
You can copy this directly to your clipboard from the Settings>Organization details page in the Console - see Managing your Organization.
You can obtain your Organization Id from the URL in your browser after logging in to the m3ter Console:

https://console.m3ter.com/org/396d788d-XXXX-4e8b-YYYY-a41f46ZZZZZ3/settings/users

In this example, the portion of the URL after /org/ is the Organization Id.

Example 1: Submit Measurements

In this example, we submit Meter measurements for an Account to the Ingest API. In addition to the JSON shown for the example request made through Postman, code versions using other common languages are given and can be copied directly to your clipboard:

API Reference Docs: see Submit measurements

To Submit measurement using Postman:

In your Postman Workspace, select to make a POST call and enter this URL as the endpoint:

https://ingest.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-aYYYYY3/measurements

Where the portion of the URL endpoint after /organizations/ is your Organization id and which you can copy from the Settings>Organization details page or from the URL in your browser after logging into the m3ter Console - see Step 4 in the previous section.

On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field:

Select the Body tab and enter JSON for the request:

In this example:

We’re submitting a single measurement for a measure type Data Field on a Meter.
The "uid" provided for the measurement must be a unique and immutable string.
For the "meter" parameter, enter the Meter’s code string.
For the "account" parameter, enter the Account’s code string.

Important! If you submit another measurement using the same "uid" but with a different "measure" quantity, an "accepted" response will be returned but the system interprets this as the same data and ignores the new measure.

Here is the JSON for the Submit measurements request example:

{
    "measurements": [
        {
            "uid": "258c80a3-0744-4318-866a-681a7b232378",
            "meter": "test_meter1",
            "account": "doetech_premium",
            "ts": "2022-05-11T12:14:41.836Z",
            "measure": {
                "gb_stored": 34000
            }
        }
    ]
}

Click Send. You will see that your submitted Meter measurement has been accepted in the Response panel:

cURL Version

If you are working in the cmd line, here’s the cURL version for this example Submit Measurements call:

curl --location --request POST 'https://ingest.m3ter.com/organizations/{orgid}/measurements' \
--header 'Authorization: Bearer {bearerToken}} '  \
--header 'Content-Type: application/json' \
--data-raw '{ 
   "measurements": [  
         {            
         "uid": "258c80a3-0744-4318-866a-681a7b232378", 
         "meter": "test_meter1",
         "account": "doetech_premium",
         "ts": "2022-05-11T12:14:41.836Z",
         "measure": {
             "gb_stored": 34000
             }
         }
   ]
}'

JavaScript Version

Here’s the JavaScript version of the Submit Measurements call:

const data = {
  measurements: [
    {
      uid: '258c80a3-0744-4318-866a-681a7b232378',
      meter: 'test_meter1',
      account: 'doetech_premium',
      ts: '2022-05-11T12:14:41.836Z',
      measure: {
        gb_stored: 34000
      }
    }
  ]
};

fetch('https://ingest.m3ter.com/organizations/{orgid}/measurements', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {bearer token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
}).then((response) => {
  console.log(response.json());
});

Python Requests Version

Here’s the Python Requests version of the Submit Measurements call:

import requests
import json

url = "https://ingest.m3ter.com/organizations/{orgid}/measurements"

payload = json.dumps({
  "measurements": [
    {
      "uid": "258c80a3-0744-4318-866a-681a7b232378",
      "meter": "test_meter1",
      "account": "doetech_premium",
      "ts": "2022-05-11T12:14:41.836Z",
      "measure": {
        "gb_stored": 34000
      }
    }
  ]
})
headers = {
  'Authorization': 'Bearer {bearerToken}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Java Version

Here’s the Java version of the Submit Measurements call:

package org.example;

import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.fluent.Request;
import org.apache.http.entity.ContentType;
import org.apache.http.util.EntityUtils;

import java.io.IOException;

public class Main {
    public static void main(String[] args) throws Exception {
        new Main().start();
    }

    private void start() throws Exception {
        System.out.println("Making POST request");
        String response = post("https://ingest.m3ter.com/organizations/{orgid}/measurements", "{
  \"measurements\": [
    {
      \"uid\": \"258c80a3-0744-4318-866a-681a7b232378\",
      \"meter\": \"test_meter1\",
      \"account\": \"doetech_premium\",
      \"ts\": \"2022-05-11T12:14:41.836Z\",
      \"measure\": {
        \"gb_stored\": 34000
      }
    }
  ]
}");
        System.out.println("Response = " + response);
    }

    private String post(String endpoint,
                        String body) throws IOException {
        Request request = Request.Post(endpoint)
                .bodyString(body, ContentType.APPLICATION_JSON)
                .addHeader("Authorization", "Bearer {bearer token}");
        HttpResponse response = request.execute().returnResponse();
        int httpCode = response.getStatusLine().getStatusCode();
        if (httpCode != HttpStatus.SC_OK) {
            // Implement error handling here
            return null;
        }
        return EntityUtils.toString(response.getEntity());
    }
}

Example 2: Get Organization Config

In this example, we retrieve the Organization config.

API Reference Docs: see Retrieve OrganizationConfig.

To obtain your Organization Config using Postman:

In your Postman Workspace, select to make a GET call and enter this URL as the endpoint:

https://api.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-a41fZZZZZ3/organizationconfig

On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field:

Click Send. Your Organization Config is returned into the Response panel:

Example 3: Create Meter

In this example, we create a Meter.

API Reference: see Create Meter

To Create a Meter using Postman:

In your Postman Workspace, select to make a POST call and enter this URL as the endpoint:

https://api.m3ter.com/organizations/396d788d-XXXX-4e8b-XXXX-a41fZZZZZ3/meters

On the Authorization tab, for Type select Bearer Token and copy and paste it into the Token field.
Select the Body tab and enter JSON for the request:

Here is the JSON for the Create Meter request example:

{
  "name": "Test Meter 2",
  "code": "test_meter2",
  "dataFields": [
    {
      "category": "MEASURE",
      "code": "gbs_stored",
      "name": "GBStorage",
      "unit": "GiBy"
    }
  ],
  "derivedFields": [ ]

}

In this example, we create a Meter with a single Data Field of type Measure, and which has no Derived Fields defined.

Tip: Global or Product Meter? In this example, we have omitted a "product" parameter from the request body, which means this request will create a Global Meter. If you want to create a Meter belonging exclusively to a specific Product, you must provide the Product id in your request.

Click Send. You’ll see the newly created Meter details returned in the Response panel:

cURL Version

If you are working in the cmd line, here’s the cURL version for this example Create Meter call:

curl --location --request POST 'https://api.m3ter.com/organizations/{orgid}/meters' \
--header 'Authorization: Bearer {bearerToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Test Meter 2",
  "code": "test_meter2",
  "dataFields": [
    {
      "category": "MEASURE",
      "code": "gbs_stored",
      "name": "GBStorage",
      "unit": "GiBy"
    }
  ],
  "derivedFields": [ ]

}'

Python Requests Version

Here’s the Python Requests version for this example Create Meter call:

import requests
import json

url = "https://api.m3ter.com/organizations/{orgid}/meters"

payload = json.dumps({
  "name": "Test Meter 2",
  "code": "test_meter2",
  "dataFields": [
    {
      "category": "MEASURE",
      "code": "gbs_stored",
      "name": "GBStorage",
      "unit": "GiBy"
    }
  ],
  "derivedFields": []
})
headers = {
  'Authorization': 'Bearer {bearerToken}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Importing m3ter Collections into your Postman Workspace

If you are working in Postman for making API calls to m3ter, some m3ter Collections are available for you to import into your Postman Workspace. These Collections provide examples of calls you’ll typically need to make to the m3ter APIs:

Importing the m3ter Open API
- m3ter Open API. The entire set of available API calls for the m3ter platform.
Importing the m3ter-Template API Collection
- m3ter-Template Collection. A set of templated calls arranged by key functional area and covering calls for common operations in these areas.

Importing the m3ter Open API

To import the m3ter Open API as a Collection into your Postman Workspace:

Go to the m3ter API Reference documentation.
In the Getting Started section, select Postman.
On the Postman page, select the m3ter Open API spec JSON file link:

A spec.json file opens in a separate browser tab.

Save the file locally.
In your Postman Workspace, select Import:

An Import dialog appears:

Select to import files. A File Upload window appears.
Navigate to where you’ve saved the spec.json file locally and select Open:

The Import dialog adjusts to show progress for the import process.
When the import process has completed, you can select how you want to complete the import:

In this example, we’ve selected to import the file as a Postman Collection.

Select Import.

The m3ter API is loaded into the Collections panel in your Postman Workspace:

Importing the m3ter-Template API Collection

To import the m3ter-Template Collection into your Postman Workspace:

Go to the m3ter API Reference documentation.
In the Getting Started section, select Postman.
On the Postman page, copy the link provided for the m3ter-Template API Collection:

In your Postman Workspace, select Collections.
Select Import:

An Import dialog appears.

Paste the URL link into the import target field on the dialog.

The m3ter-Template API Collection is imported into your Workspace:

​Setting Up for Service User API Calls

​Step 1: Create a Service User and add Permissions

​Step 2: Generate Access Keys for the Service User.

​Step 3: Use Basic Authentication to obtain a Bearer Token.

​Step 4: Copy your Organization Id.

​Example 1: Submit Measurements

​cURL Version

​JavaScript Version

​Python Requests Version

​Java Version

​Example 2: Get Organization Config

​Example 3: Create Meter

​cURL Version

​Python Requests Version

​Importing m3ter Collections into your Postman Workspace

​Importing the m3ter Open API

​Importing the m3ter-Template API Collection

Setting Up for Service User API Calls

Step 1: Create a Service User and add Permissions

Step 2: Generate Access Keys for the Service User.

Step 3: Use Basic Authentication to obtain a Bearer Token.

Step 4: Copy your Organization Id.

Example 1: Submit Measurements

cURL Version

JavaScript Version

Python Requests Version

Java Version

Example 2: Get Organization Config

Example 3: Create Meter

cURL Version

Python Requests Version

Importing m3ter Collections into your Postman Workspace

Importing the m3ter Open API

Importing the m3ter-Template API Collection