• Home
/
• Working in m3ter - User Guides
/
• m3ter APIs

Getting Started with API Calls

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:

• Setting Up for Service User API Calls

• Example 1: Submit Measurements

• Example 2: Get Organization Config

• Example 3: Create Meter

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

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.

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.

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.

Step 4: Copy your Organization Id.

• When you have obtained your Service User Bearer Token at Step 3, you will 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 highlighted 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:

• cURL Version

• JavaScript Version

• Python Requests Version

• Java Version

To Submit measurement using Postman:

1. 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 URL in your browser after logging into the m3ter Console - see Step 4 in the previous section.

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

3. 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.

Here is the JSON for the Submit measurements request example:

1
{
2
    "measurements": [
3
        {
4
            "uid": "258c80a3-0744-4318-866a-681a7b232378",
5
            "meter": "test_meter1",
6
            "account": "doetech_premium",
7
            "ts": "2022-05-11T12:14:41.836Z",
8
            "measure": {
9
                "gb_stored": 34000
10
            }
11
        }
12
    ]
13
}

4. 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:

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

JavaScript Version

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

1
const data = {
2
  measurements: [
3
    {
4
      uid: '258c80a3-0744-4318-866a-681a7b232378',
5
      meter: 'test_meter1',
6
      account: 'doetech_premium',
7
      ts: '2022-05-11T12:14:41.836Z',
8
      measure: {
9
        gb_stored: 34000
10
      }
11
    }
12
  ]
13
};
14

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

Python Requests Version

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

1
import requests
2
import json
3

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

6
payload = json.dumps({
7
  "measurements": [
8
    {
9
      "uid": "258c80a3-0744-4318-866a-681a7b232378",
10
      "meter": "test_meter1",
11
      "account": "doetech_premium",
12
      "ts": "2022-05-11T12:14:41.836Z",
13
      "measure": {
14
        "gb_stored": 34000
15
      }
16
    }
17
  ]
18
})
19
headers = {
20
  'Authorization': 'Bearer {bearerToken}',
21
  'Content-Type': 'application/json'
22
}
23

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

26
print(response.text)

Java Version

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

1
package org.example;
2

3
import org.apache.http.HttpResponse;
4
import org.apache.http.HttpStatus;
5
import org.apache.http.client.fluent.Request;
6
import org.apache.http.entity.ContentType;
7
import org.apache.http.util.EntityUtils;
8

9
import java.io.IOException;
10

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

16
    private void start() throws Exception {
17
        System.out.println("Making POST request");
18
        String response = post("https://ingest.m3ter.com/organizations/{orgid}/measurements", "{
19
  \"measurements\": [
20
    {
21
      \"uid\": \"258c80a3-0744-4318-866a-681a7b232378\",
22
      \"meter\": \"test_meter1\",
23
      \"account\": \"doetech_premium\",
24
      \"ts\": \"2022-05-11T12:14:41.836Z\",
25
      \"measure\": {
26
        \"gb_stored\": 34000
27
      }
28
    }
29
  ]
30
}");
31
        System.out.println("Response = " + response);
32
    }
33

34
    private String post(String endpoint,
35
                        String body) throws IOException {
36
        Request request = Request.Post(endpoint)
37
                .bodyString(body, ContentType.APPLICATION_JSON)
38
                .addHeader("Authorization", "Bearer {bearer token}");
39
        HttpResponse response = request.execute().returnResponse();
40
        int httpCode = response.getStatusLine().getStatusCode();
41
        if (httpCode != HttpStatus.SC_OK) {
42
            // Implement error handling here
43
            return null;
44
        }
45
        return EntityUtils.toString(response.getEntity());
46
    }
47
}

Example 2: Get Organization Config

In this example, we retrieve the Organization config.

To obtain your Organization Config using Postman:

1. 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

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

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

Example 3: Create Meter

In this example, we create a Meter.

To Create a Meter using Postman:

1. 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

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

3. Select the Body tab and enter JSON for the request:

Here is the JSON for the Create Meter request example:

1
{
2
  "name": "Test Meter 2",
3
  "code": "test_meter2",
4
  "dataFields": [
5
    {
6
      "category": "MEASURE",
7
      "code": "gbs_stored",
8
      "name": "GBStorage",
9
      "unit": "GiBy"
10
    }
11
  ],
12
  "derivedFields": [ ]
13

14
}

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

4. 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:

1
curl --location --request POST 'https://api.m3ter.com/organizations/{orgid}/meters' \
2
--header 'Authorization: Bearer {bearerToken}' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
  "name": "Test Meter 2",
6
  "code": "test_meter2",
7
  "dataFields": [
8
    {
9
      "category": "MEASURE",
10
      "code": "gbs_stored",
11
      "name": "GBStorage",
12
      "unit": "GiBy"
13
    }
14
  ],
15
  "derivedFields": [ ]
16

17
}'

Python Requests Version

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

1
import requests
2
import json
3

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

6
payload = json.dumps({
7
  "name": "Test Meter 2",
8
  "code": "test_meter2",
9
  "dataFields": [
10
    {
11
      "category": "MEASURE",
12
      "code": "gbs_stored",
13
      "name": "GBStorage",
14
      "unit": "GiBy"
15
    }
16
  ],
17
  "derivedFields": []
18
})
19
headers = {
20
  'Authorization': 'Bearer {bearerToken}',
21
  'Content-Type': 'application/json'
22
}
23

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

26
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:

1. Go to the m3ter API Reference documentation.

2. Select to Download the m3ter Open API spec:

• An openapi.json file is downloaded into your Downloads folder.

3. In your Postman Workspace, select Collections.

4. Select Import. An Import dialog appears:

5. Select to import files. A File Upload window appears.

6. Navigate to where you've saved the openapi.json file from the download 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.

7. 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:

1. Go to the m3ter API Reference documentation.

2. Copy the link provided for the m3ter-Template API Collection:

3. In your Postman Workspace, select Collections.

4. Select Import. An Import dialog appears.

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

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

Next: HTTP Error Codes

Additional Support