Measurements via the MetriX REST interface

Contents:

1. Triggering measurements via the REST interface

2. Explanations-of-various-HTTP-responses

---

Triggering measurements via the REST interface

MetriX provides a REST interface that can be used to trigger measurements. By default, access is via port 32321.
The corresponding route is: /measurement/1234.

(1234 is an example of a unique identifier defined by you, e.g. a barcode, a PieceID, etc..)

• The route can be addressed both via HTTP POST and HTTP GET. 
• The header should always contain the Content-Type: application/json.
• If you want to transmit additional information about the measurement, the request can contain any JSON body. 

{
   "foo": 42,
   "bar": "abc"
}

 

Please note: A JSON body is also possible with GET  (see RFC2616), although older HTTP clients do not support this.

---

 

Explanations of various HTTP responses

You can send MetriX both an HTTP POST request and an HTTP GET request:

• HTTP POST request to MetriX
  The system is instructed to perform a measurement for the transmitted identifier. The measurement result is not returned.
• HTTP GET request to MetriX
  The system is instructed to perform a measurement for the transmitted identifier and to return the result directly.

The possible responses are listed below:

✅ POST | 200 OK

If MetriX responds with 200 OK, the identifier has been successfully accepted and the system is in a state in which measurement is possible.

✅ GET | 200 OK

If all requirements are fulfilled, MetriX responds as follows in the exemplary response body:

{
  "id": "TestSystem20250606110729846",
  "systemId": "TestSystem",
  "timestamp": "2025-06-06T11:07:58.7589839Z",
  "dimensioningState": "Stable",
  "legalForTradeHash": "956356C986A3574C3D61E98913159796",
  "length": 1.22,
  "width": 0.8,
  "height": 1.92,
  "exactVolume": 1.37392,
  "weight": 98,
  "weightState": "Stable",
  "weightReference": "0815",
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "overlayImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "croppedImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "croppedOverlayImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "userData": {
    "externalIdentifiers": [
      "1234"
    ],
    "payload": {
      "foo": 42,
      "bar": "abc"
    },
    "length": 1.2,
    "width": 0.8,
    "height": null,
    "weight": null,
    "customFields": {
      "isSeaFreight": true
    }
  }
}

Detailed explanations of the features listed:

All values are always given in SI units (meters, kilograms or cubic meters). This does not apply to manually entered values in the userData property, which may have customer-specific units.

The images are transferred as a data url.

Please note: A system can have several color cameras. Within a system, images can be recorded and saved in different resolutions. Depending on the configuration, not all images may be output (e.g. to reduce the size of the response). The content type of the images should be taken into consideration. 

❌ POST/GET | 400 Bad Request

If the identifier is not accepted or the system is in a state that does not allow measurements, you will receive the response: 400 Bad Request. You can find out what the problem is in the response body (see RFC7807).

Possible error messages and what they mean:

• • • Invalid Identifier

During the configuration of your MetriX system, certain formats are stored for defined identifiers. If MetriX now receives an identifier whose format differs from the stored format, the following response appears:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The external identifier does not match the configured format and is ignored.",
  "instance": "measurement/bar@@",
  "traceId": "0HND4SS6QTH5U:00000001"
}

 

• • • Additional Identifier disabled 

With individually configured special MetriX systems, it is possible to assign several identifiers to a measurement. If this setting is deactivated in the corresponding system and the system receives other values in addition to the standard identifier, the following response appears:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Additional external identifiers are disabled and the identifier is ignored.",
  "instance": "measurement/bar",
  "traceId": "0HND4T17Q41R8:00000002"
}

 

• • • Verification required

If the system needs to be verified before the next measurement can be started, the following response appears:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The external identifier is ignored due to pending verification.",
  "instance": "measurement/bar",
  "traceId": "0HND4T2NA1KJ0:00000001"
}

❌ GET | 404 Not Found 

If MetriX does not perform a measurement, e.g. because the measuring range is empty or the weight is not stable, the system responds after a timeout with the corresponding HTTP code: 404 Not Found. 

 

---

 

Would you like to try out the implementation in advance? 

No problem, a publicly accessible test REST interface is available to you. The test interface largely reproduces the behavior of the real system. Nevertheless, there may be individual restrictions or special features.

Directly to the detailed article Technical information on the test interface