API Integration Guide

---

Build custom integrations with MachineMetrics using our REST API. Pull production data into spreadsheets, BI tools, or your own applications.

---

Overview

The MachineMetrics API enables you to:

• Retrieve production metrics (OEE, parts, cycle times, downtime)
• Export data to Google Sheets, Excel, or Power BI
• Manage operations (create, update, delete jobs)
• Query machine status in real-time
• Build custom dashboards and applications

API Endpoints

Environment	Base URL
Standard	https://api.machinemetrics.com
GovCloud	https://api.machinemetrics-us-gov.com

Developer Resources

• Full API Documentation: developers.machinemetrics.com
• API Reference: developers.machinemetrics.com/docs/rest/

---

Authentication

All API requests require authentication using an API key as a Bearer token.

Generating an API Key

1. Navigate to Settings → API Keys in MachineMetrics
2. Click Create API Key
3. Select the appropriate scopes (see below)
4. Click Save Changes
5. Copy your API key immediately — it will only be shown once

API Key Scopes

Scope	Description
reporting	Read access to reportable data (most common)
erp	Read/write for ERP integration
manager	Full control of manager-level functionality
manager.read	Read-only access to settings, jobs, users
operator.jobs	Job control and access
operator.parts	Part scrapping and categorization
operator.downtime	Downtime categorization
system.gateway	Manage edge devices
gateway	Machine data ingest

Using Your API Key

Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

---

Google Sheets Integration

Automatically pull MachineMetrics data into Google Sheets using Apps Script.

Setup

Step 1: Create the Spreadsheet

1. Create a new Google Sheet
2. Rename the first sheet to ExampleData
3. Add a second sheet named Charts

Step 2: Add the Apps Script

1. Click Extensions → Apps Script
2. Delete any existing code and paste the following:

function getData() {
  let chartSheetName = "Charts"
  let dataSheetName = "ExampleData"
  
  let apiKey = PropertiesService.getScriptProperties().getProperty('APIKey');
  const url = "https://api.machinemetrics.com/reports/production";
  
  let chartsSheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(chartSheetName);
  
  // Get date range from sheet cells
  let startDateInput = chartsSheet.getRange("D2").getValue();
  let endDateInput = chartsSheet.getRange("F2").getValue();
  
  let startDate = Utilities.formatDate(startDateInput, "GMT", "yyyy-MM-dd'T'HH:mm:ss'Z'")
  let endDate = Utilities.formatDate(endDateInput, "GMT", "yyyy-MM-dd'T'HH:mm:ss'Z'")
  
  // Configure the API request
  let body = {
    "start": startDate,
    "end": endDate,
    "data": [
      {"metric": "downtime"},
      {"metric": "oee"},
      {"metric": "goodParts"},
      {"metric": "actualPartTime"},
      {"metric": "timeInCut"}
    ],
    "groupBy": [{"group": "machine"}],
    "flatten": true
  }
  
  let options = {
    "method": "post",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + apiKey
    },
    "payload": JSON.stringify(body)
  };
  
  let response = UrlFetchApp.fetch(url, options);
  let data = JSON.parse(response.getContentText());
  let keys = Object.keys(data.items[0]);
  let sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(dataSheetName)
  
  // Clear old data
  sheet.clear({contentsOnly: true});
  
  // Create column headers
  keys.map(function (item){
    sheet.getRange(1, sheet.getLastColumn()+1).setValue(item);
  });
  
  // Populate data rows
  for (let i = 0; i < data.items.length; i++){
    let item = data.items[i];
    let j = 0;
    while (j < keys.length){
      sheet.getRange(i+2, j+1).setValue(item[keys[j]])
      j++
    }
  }
}

Step 3: Store Your API Key Securely

1. In Apps Script, click the Project Settings icon (gear)
2. Scroll to Script Properties
3. Click Add script property
4. Set Name to APIKey and Value to your MachineMetrics API key
5. Click Save script properties

Step 4: Configure Date Range

1. Return to your spreadsheet
2. On the "Charts" sheet, add:
   • Cell D2: Start date (format: yyyy-MM-dd)
   • Cell F2: End date (format: yyyy-MM-dd)

Step 5: Create a Refresh Button

1. Click Insert → Drawing
2. Draw a button shape
3. Click Save and Close
4. Click the button, then the three dots menu
5. Select Assign script
6. Enter getData and click OK

Click the button to pull data. Authorize the script when prompted.

---

Excel Integration (Windows)

Pull MachineMetrics data into Excel using VBA macros.

Note: This method works on Windows Excel only. Mac Excel does not support the required VBA features.

Setup

Step 1: Enable Macros

1. Open Excel and create a new workbook
2. Save as Excel Macro-Enabled Workbook (.xlsm)

Step 2: Add Required References

1. Press Alt + F11 to open the VBA Editor
2. Click Tools → References
3. Check Microsoft Scripting Runtime
4. Click OK

Step 3: Add JSON Parser

1. Download JsonConverter.bas from VBA-JSON GitHub
2. In VBA Editor, click File → Import File
3. Select the downloaded JsonConverter.bas

Step 4: Add the Macro

1. In VBA Editor, click Insert → Module
2. Paste the following code:

Sub macroPOST()
    Dim URL As String
    Dim objHTTP As Object
    Dim StartDate As String, EndDate As String
    Dim StartTime As String, EndTime As String
    
    ' Get dates from Input sheet
    StartDate = Format(Worksheets("Input").Range("B3"), "yyyy-mm-dd")
    EndDate = Format(Worksheets("Input").Range("B4"), "yyyy-mm-dd")
    StartTime = Format(Worksheets("Input").Range("D3"), "hh:mm:ss")
    EndTime = Format(Worksheets("Input").Range("D4"), "hh:mm:ss")
    
    URL = "https://api.machinemetrics.com/reports/production"
    
    Set objHTTP = CreateObject("WinHttp.WinHttpRequest.5.1")
    objHTTP.Open "POST", URL, False
    objHTTP.setRequestHeader "Authorization", "Bearer YOUR_API_KEY_HERE"
    objHTTP.setRequestHeader "Content-Type", "application/json"
    
    JSONString = "{""start"":""" & StartDate & "T" & StartTime & "Z"", " & _
                 """end"":""" & EndDate & "T" & EndTime & "Z"", " & _
                 """groupBy"":[{""group"":""machine""},{""group"":""day""}], " & _
                 """data"":[{""metric"":""totalParts""},{""metric"":""timeInCycle""}], " & _
                 """flatten"":""true""}"
    
    objHTTP.Send JSONString
    
    ' Parse and display results
    Worksheets("Data").Activate
    Dim Parsed As Dictionary
    Sheets("Data").Cells.Clear
    
    Set Parsed = JsonConverter.ParseJson(objHTTP.responseText)
    
    ' Write headers and data...
    ' (See full code in documentation)
End Sub

3. Replace YOUR_API_KEY_HERE with your actual API key

Step 5: Configure Input Sheet

Create a sheet named "Input" with:

• B3: Start Date (e.g., 03/21/24)
• D3: Start Time (e.g., 12:00:00 AM)
• B4: End Date
• D4: End Time

Create another sheet named "Data" for the results.

Timezone Note: MachineMetrics uses UTC. Adjust times accordingly (e.g., add 5 hours for EST).

---

Power BI Integration

Connect Power BI to MachineMetrics for advanced reporting and visualization.

Setup

Step 1: Create a Blank Query

1. Open Power BI Desktop
2. Click Get Data → Blank Query
3. Click Advanced Editor

Step 2: Add the Query Code

Replace the default code with:

let
    APIKey = "bearer ",
    APIToken = "YOUR_API_KEY_HERE",
    url = "https://api.machinemetrics.com/reports/production",
    
    // Dynamic date range: last 30 days
    startDate = DateTime.ToText(Date.AddDays(DateTime.LocalNow(),-30),"yyyy-MM-ddTHH:mm:ssZ"),
    endDate = DateTime.ToText(DateTime.LocalNow(),"yyyy-MM-ddTHH:mm:ssZ"),
    
    body = Json.FromValue([
        start = startDate,
        end = endDate,
        data = {
            [metric = "totalParts"],
            [metric = "goodParts"],
            [metric = "rejectedParts"],
            [metric = "timeInCycle"]
        },
        groupBy = {
            [group = "day"],
            [group = "machine"]
        },
        flatten = true
    ]),
    
    JSONRetrive = Web.Contents(url, [
        Headers = [
            #"Authorization" = APIKey & APIToken,
            #"Content-Type" = "application/json"
        ],
        Content = body
    ]),
    
    JSONResult = Json.Document(JSONRetrive),
    items = JSONResult[items],
    #"Converted to Table" = Table.FromList(items, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Expanded Column1" = Table.ExpandRecordColumn(#"Converted to Table", "Column1", 
        {"machine", "day", "totalParts", "timeInCycle"}, 
        {"Machine", "Day", "Total Parts", "Time In-Cycle"})
in
    #"Expanded Column1"

Step 3: Configure Credentials

1. If prompted, click Edit Credentials
2. Select Anonymous authentication
3. Choose your API endpoint from the dropdown
4. Click Connect

Step 4: Build Your Reports

Click Close & Apply to load the data. Create visualizations using the imported data.

Multiple Locations

For multi-site deployments, modify the query to use an array of API keys:

let
    APIKeys = {"API_KEY_1", "API_KEY_2"},
    // ... fetch and combine data from each location

Troubleshooting

Issue	Solution
"Skip test connection" error	Check this box when publishing to Power BI Service
Date columns not recognized	Change column type to Date/Time/Timezone
Authentication errors	Verify API key and use Anonymous auth

---

Available Metrics

Common metrics available through the Production Reports API:

Metric	Description
oee	Overall Equipment Effectiveness
totalParts	Total parts produced
goodParts	Non-rejected parts
rejectedParts	Rejected/scrap parts
timeInCycle	Active machining time
timeInCut	Spindle cutting time
setupTime	Setup duration
downtime	Total downtime
utilizationRate	Machine utilization percentage

Grouping Options

Group	Description
machine	By individual machine
day	By calendar day
shift	By shift
operator	By operator
jobOperation	By job/operation

---

Related Articles

• ERP Integration Guide — Connect your ERP system
• Third-Party App Integrations — MaintainX, Make.com, and more
• Webhooks & Automation — Real-time event notifications