Integrating Scales with Your Software via an API

What a scale API does

A scale API (application programming interface) lets your own software read weights and records from a scale and send it commands, using a documented, machine-readable interface instead of screen-scraping a display or parsing a printer stream. With an API, a catch registration program, a packing line controller or a shore dashboard can use the scale as a data source and a controllable device.

Older integrations relied on a continuous serial output: the scale sent a text line with the weight several times per second over RS232, and the receiving program parsed it. That still works, but it only flows one way and every manufacturer's format differs. A network API adds structured data (usually JSON), access to stored records and presets, and a defined way to issue commands. The physical side of that connection is covered in RS232, Ethernet, USB, Wi-Fi or Bluetooth LE: Choosing a Scale Interface.

Typical endpoints and functions

Most scale APIs expose the same five groups of functions: live weight, stability and status, presets, logs, and commands such as zero, tare and print.

The table below is a generic illustration of how such an API is commonly organised. It is not the schema of any specific product, including WPL's.

Two principles make such an API predictable. Reading data uses safe methods that change nothing on the scale; changing presets or issuing commands uses methods whose effect is documented. HTTP semantics, including which methods are safe and idempotent, are defined in RFC 9110. Many vendors describe their HTTP APIs in the OpenAPI Specification format, which allows client code to be generated and requests to be validated.

Example payloads

A live weight response should carry the value, its unit, a timestamp and the status needed to decide whether the value may be used.

Illustrative example only, not WPL's actual API schema:

{

"scale_id": "scale-03",

"timestamp": "2026-09-14T06:42:17.250Z",

"net": 5.120,

"tare": 0.450,

"unit": "kg",

"stable": true,

"zero": false,

"check": "ok",

"preset": "COD-GUT-5KG"

}

The fields that matter most for integration are stable and timestamp. A program that registers a box weight should only accept a reading marked stable, and it should compare timestamps to detect a stale value when the connection stalls. Weights should be JSON numbers with a fixed unit, not strings with the unit appended, so they can be summed without parsing (RFC 8259).

A command exchange, again as an illustrative example:

POST /commands

{ "command": "tare", "request_id": "7f3c-0192" }

200 OK

{ "request_id": "7f3c-0192", "result": "done", "tare": 0.450, "unit": "kg" }

The request_id lets the client match the response to its request and lets the scale recognise a retry of a command it has already carried out, so that a lost response over a poor link does not cause a second tare.

Polling versus push

Polling means the client asks the scale for data at intervals; push means the scale sends data as soon as something changes. Polling is simpler to build, push is more efficient for live values and events.

The cost of polling is easy to underestimate. Polling live weight five times per second produces 432,000 requests per day per client. For a live display that is acceptable on a local network; over a satellite link it is not. A practical pattern is to use push or fast polling on board for displays and control, and to collect finished records from the log at intervals for everything that leaves the vessel.

Live values versus records

Treat the live weight as a display value and the log as the system of record. If your software builds its own records from polled live values, it can miss weighings between polls or register the same box twice. Reading registered records from the scale's log, with a unique record ID, avoids both problems. What those records should contain is described in Weighing Data Logging at Sea.

Commands, safety and access control

Remote commands are powerful and should be restricted: a zero or tare sent at the wrong moment silently corrupts every following weighing.

• Check state before acting. Only zero an empty, stable scale; only tare with the container on the platform and the reading stable.
• Confirm the result. Read the status after a command instead of assuming it succeeded.
• Make retries harmless. Use request IDs or idempotent operations so a repeated request has the same effect as one.
• Authenticate and limit access. Separate read access from command and preset-editing rights; do not expose scales directly to the internet.
• Log commands. Remote zero, tare and preset changes belong in the audit trail with the client that sent them.

Guidance on managing cyber risk on vessels is published by the IMO in its maritime cyber risk management guidelines.

Integration step by step

A reliable scale integration follows a fixed sequence from documentation to field test.

1. Obtain the API documentation for the exact scale model and software version.
2. List the data your software needs and map each item to an API field, including units and decimals.
3. Decide per data flow whether to poll, subscribe or read logs.
4. Use record IDs to make imports idempotent and detect gaps.
5. Handle unstable readings, overload, disconnection and timeouts explicitly.
6. Synchronise clocks and store UTC timestamps.
7. Test on board with the real network, not only in the office, including loss of connection mid-shift.
8. Record the API version used, so a later software update can be checked for changes.

How WPL approaches this

WeightControl includes an integrated API that returns data in JSON. Through it, external software can retrieve the current weight, checkweigher status and stability indication, load and edit presets, read the last registered log and all stored logs, and issue commands such as Zero, Print and Tare. WeightControl runs on the R10 scale itself or as an external application managing several scales. Documentation is included with each model; for details and updates contact info@wpl-industries.com. The WeightControl IOT module is available as an option on the M2, M3, M5 and M6 series; see the data integration hub for the wider architecture.