To learn how to interact with the BEAAM API of your BEAAM, the easiest way is to use the inbuilt Swagger UI. For that, open a browser and navigate to: http://<your_beaam_ip>/api/

To authenticate yourself with the API, you will need your BEAAM API Key. If you don't have that already, you can find out how to get it on https://neoom.com/developers

Energy Flow

The first thing you will probably want to check out is a high-level overview of the Energy Flow of your Site.

This Energy Flow data is available via /api/v1/site/state An example response could look like this:

{
  "energyFlow": {
    "states": [
      {
        "dataPointId": "947cf9e2-c6ae-534a-968a-c14aa31851ab",
        "key": "SELF_SUFFICIENCY",
        "value": 100,
        "ts": 1744812665002
      },
      {
        "dataPointId": "bc0e3b85-2d78-5f91-9b9f-46e8027175eb",
        "key": "POWER_GRID",
        "value": -3994,
        "ts": 1744812710003
      },
      {
        "dataPointId": "716c4658-083c-5e6b-aea9-5921dca72a9d",
        "key": "POWER_STORAGE",
        "value": 32.74635568513119,
        "ts": 1744812710003
      },
      {
        "dataPointId": "48b6f5ea-be8e-50e4-ac63-3894fd41771b",
        "key": "POWER_CONSUMPTION_CALC",
        "value": 61.99999999999997,
        "ts": 1744812710003
      },
      {
        "dataPointId": "9585ffee-2d35-5f3f-91ec-f4e126daf65a",
        "key": "POWER_PRODUCTION",
        "value": 4023.253644314869,
        "ts": 1744812710003
      },
      {
        "dataPointId": "03b5954a-d202-5b4b-b98c-d4356c8fda9f",
        "key": "STATE_OF_CHARGE",
        "value": 100,
        "ts": 1744812665002
      },
      [...]
    ]
  }
}

As you can see, this site is currently producing about 4kW of solar power summed up over all installed Inverters. Of these 4kW, almost everything goes straight into the grid, because the Batteries at the site are already at 100% charge and the house is idle and unoccupied.

If this site would have a dedicated meter installed, the key would be POWER_CONSUMPTION instead of POWER_CONSUMPTION_CALC.

There is a lot more to find within that data, but it's best for you to try it out yourself. You can also look up all available DataPoints in your site configuration (see next section)

Things

Going beyond aggregated site-level data and increasing resolution, you can also use the BEAAM API to query the state of individual Things like e.g., your Inverter, your Battery or your Charging Point.

For that, you will first need to know the ID of your Thing. This can be found in the Site Configuration available via the /api/v1/site/configuration endpoint.

Example:

{
  "siteId": "0756c8be-13e5-494c-9331-8dfc1a30d28a",
  "versionTimestamp": 1744812611,
  "siteInfo": {
    "gridConnections": {
      "0c7bc039-50c1-4b01-93bd-76ca45d55bff": {
        "name": "Netzzähler",
        "maxPowerSupply": 17300,
        "maxPowerFeedIn": 12000,
        "meterThingId": "0c7bc039-50c1-4b01-93bd-76ca45d55bff"
      }
    },
    "geoCoordinates": {
      "latitude": 48.4883057,
      "longitude": 14.497897
    }
  },
  "things": {
    "0c7bc039-50c1-4b01-93bd-76ca45d55bff": {
      "type": "ELECTRICITY_METER_AC",
      "dataPoints": {
        "536b1d2c-174b-5abd-8839-e41eb4d20f31": {
          "key": "CONNECTION",
          "dataType": "BOOLEAN",
          "unitOfMeasure": "None",
          "controllable": false
        },
        "9ef78594-9a38-53fc-b081-baeef1638946": {
          "key": "VOLTAGE_P1",
          "dataType": "NUMBER",
          "unitOfMeasure": "V",
          "controllable": false
        },
        "5338f86b-9c57-585a-8524-ab2bf80084ac": {
          "key": "VOLTAGE_P2",
          "dataType": "NUMBER",
          "unitOfMeasure": "V",
          "controllable": false
        },
        "4d92d98c-49f5-5987-9126-124d33b89871": {
          "key": "VOLTAGE_P3",
          "dataType": "NUMBER",
          "unitOfMeasure": "V",
          "controllable": false
        },
        "ba5b424d-4de0-5f8a-92be-e4f1bff6037a": {
          "key": "FREQUENCY",
          "dataType": "NUMBER",
          "unitOfMeasure": "Hz",
          "controllable": false
        },
        "5413c8ef-dc4b-5903-8a38-b4d6dcd2ab8d": {
          "key": "ACTIVE_POWER",
          "dataType": "NUMBER",
          "unitOfMeasure": "W",
          "controllable": false
        },
        [...]
      }
    },
    "d4f65a33-ee5c-421d-855d-2d5682a4bc4d": {
      "type": "INVERTER",
      "dataPoints": {
        [...]
      }
    },
    "7b91e8fe-2864-41b0-b850-f1748ca586b3": {
      "type": "PV",
      "dataPoints": {
        [...]
      }
    },
    [...]
  },
  "energyFlow": {
    "dataPoints": {
      "947cf9e2-c6ae-534a-968a-c14aa31851ab": {
        "key": "SELF_SUFFICIENCY",
        "dataType": "NUMBER",
        "unitOfMeasure": "%"
      },
      "9585ffee-2d35-5f3f-91ec-f4e126daf65a": {
        "key": "POWER_PRODUCTION",
        "dataType": "NUMBER",
        "unitOfMeasure": "W"
      },
      [...]
    }
  }
}

From this we can learn that our main electricity meter has the Thing ID 0c7bc039-50c1-4b01-93bd-76ca45d55bff. This ID is stable, so even if you decide to add more devices to your site, it will stay the same.

States

Now that you have the ID of the Thing, you can query the states of all its DataPoints by calling /api/v1/things/<thing_id>/states.

Example Response:

{
  "thingId": "0c7bc039-50c1-4b01-93bd-76ca45d55bff",
  "states": [
    {
      "dataPointId": "536b1d2c-174b-5abd-8839-e41eb4d20f31",
      "key": "CONNECTION",
      "value": true,
      "ts": 1744812665075
    },
    {
      "dataPointId": "9ef78594-9a38-53fc-b081-baeef1638946",
      "key": "VOLTAGE_P1",
      "value": 229.7,
      "ts": 1744814230062
    },
    {
      "dataPointId": "5338f86b-9c57-585a-8524-ab2bf80084ac",
      "key": "VOLTAGE_P2",
      "value": 228.9,
      "ts": 1744814230062
    },
    {
      "dataPointId": "4d92d98c-49f5-5987-9126-124d33b89871",
      "key": "VOLTAGE_P3",
      "value": 230.1,
      "ts": 1744814230062
    },
    {
      "dataPointId": "ba5b424d-4de0-5f8a-92be-e4f1bff6037a",
      "key": "FREQUENCY",
      "value": 49.96,
      "ts": 1744814210065
    },
    {
      "dataPointId": "5413c8ef-dc4b-5903-8a38-b4d6dcd2ab8d",
      "key": "ACTIVE_POWER",
      "value": -907,
      "ts": 1744814230062
    },
    [...]
  ]
}

Depending on the Thing, there might be other DataPoints available, so, again, feel free to take a look around.

Commands

Some Things also expose tunables or settings like e.g., the Target Power of a Battery. These can be controlled via Commands.

By sending a POST request with the following payload to /api/v1/things/<thing_id>/commands.

[
  {
    "key": "TARGET_POWER",
    "value": 5000
  }
]

the targeted Battery will start charging with 5kW. Consequently, a value of -5000 will make it discharge at 5kW.

For EV Charging Points, depending on the specific model, MAX_POWER_CHARGE or MAX_CURRENT_CHARGE can be used to control the charging power/current respectively.

To find out which Data Points can be controlled via Commands, look for controllable: true in your Site Config.

Ingesting States

Beside Commands that control Data Points, it is also possible to ingest States for them.

The main use case of this functionality are Generic devices that can be configured for a site on connect.neoom.com. These will not poll data from anywhere but accept it via the Local API.

By using that interface, it is possible to e.g. integrate something that is either entirely home-made or not yet supported by neoom by writing your own glue code or configuring your home automation system to feed in the correct data.

The generic device model is available for Energy Meters, Consumers, Heat Pumps and Charging Points.

After having set up such a Generic device, States for the Data Points of its Things can be pushed via a POST request like this to /api/v1/things/<thing_id>/commands:

[
  {
    "key": "CURRENT_P1",
    "value": 0.3
  },
  {
    "key": "CURRENT_P2",
    "value": 0.4
  },
  [...]
]