Measure - PHD Solutions Documentation

Overview

The /measure endpoint instructs the device to perform a measure operation and return the result.

The IP address of the device is required to call this endpoint. Check the Integration Guide for details on determining the device IP address.

Request

curl -i "http://<YOUR_DEVICE_ADDRESS>/api/v1/measure" \
-X GET

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 24 Feb 2025 20:43:50 GMT
Server: Kestrel
Transfer-Encoding: chunked
api-supported-versions: 1.0

{
    "transactionReference": null,
    "customReference1": null,
    "customReference2": null,
    "customReference3": null,
    "imageIdentifier": "00000000-0000-0000-0000-000000000000",
    "elapsedMs": 1234,
    "dateTimeLocal": "2025-02-24T15:41:24.3898755-05:00",
    "dateTimeUtc": "2025-02-24T20:41:24.3898755Z",
    "errorCode": 0,
    "errorMessage": "-",
    "objectCount": 1,
    "dimsUnitOfMeasure": "cm",
    "weightUnitOfMeasure": "lb",
    "measurementFidelity": "0.5",
    "legalForTrade": false,
    "weight": 24.00,
    "objectId": "",
    "measuredObjects": [
        {
            "trackId": 0,
            "errorCode": 0,
            "errorMessage": "-",
            "rotationAngle": 12.3,
            "length": 10.3,
            "width": 12.1,
            "height": 14.5
        }
    ]
}

Request Parameters

The measure request has multiple optional query strings to help pass custom values and reference transactions. All parameters are optional.

Queries

Property	Data Type	Description
`TransactionReference`	string	a host-supplied transaction reference for tracking purposes. This can be any value you wish to supply as something that will be tracked with the measure operation in enVision Cloud and returned in the response. Possible values are an Order ID, Tracking Number or Barcoded identifier.
`CustomReference1`	string	a custom host-supplied reference. This value will be tagged to the transaction stored in enVision Cloud.
`CustomReference2`	string	a custom host-supplied reference. This value will be tagged to the transaction stored in enVision Cloud.
`CustomReference3`	string	a custom host-supplied reference. This value will be tagged to the transaction stored in enVision Cloud.

Example Query Request

An example request to measure with the query parameters

Request

curl -i "http://<YOUR_DEVICE_ADDRESS>/api/v1/measure?transactionReference=ABCD123&customReference1=XYZ123&customReference2=XYZ123&customReference3=XYZ123" \
-X GET

Response Properties

A single MeasureResult object

MeasureResult Properties

Property	Data Type	Description
`TransactionReference`	string?	Externally provided reference number for the transaction.
`CustomReference1`	string?	Externally provided custom reference value for the transaction.
`CustomReference2`	string?	Externally provided custom reference value for the transaction.
`CustomReference3`	string?	Externally provided custom reference value for the transaction.
`ImageIdentifier`	Guid?	the image identifier. Use this value as input to a subsequent API call to `/images` to fetch images for this transaction.
`ElapsedMs`	long	Count of elapsed milliseconds taken to complete the measurement.
`DateTimeLocal`	DateTime	Device-local date-time of the transaction.
`DateTimeUtc`	DateTime	UTC date-time of the transaction.
`ErrorCode`	int	Error code result. `0` indicates success.
`ErrorMessage`	string?	Error message associated with the error code.
`ObjectCount`	int	Count of objects measured (either `0` or `1`).
`DimsUnitOfMeasure`	string?	Object dimensions unit of measure (e.g., `in`, `cm`, `mm`).
`WeightUnitOfMeasure`	string?	Weight unit of measure (e.g., `lb`, `kg`).
`MeasurementFidelity`	string?	Precision of measurement (`1.0 = whole`, `0.5 = half`, `0.2 = 1/5`).
`LegalForTrade`	bool	`True` if the device was operating in Legal for Trade mode.
`Weight`	decimal?	Total weight in `WeightUnitOfMeasure` units.
`ObjectId`	string?	An object identifier. In this case will be populated with barcode value if a scanner is connected.
`MeasuredObjects`	`MeasureObjectResult[]`	An array of `MeasuredObjectResult` objects. The number of items within the array is equal to `ObjectCount`

MeasureObjectResult Properties

Property	Data Type	Description
`TrackId`	long	Track identifier for the specific object (used in in-motion scenarios).
`ErrorCode`	int	Object-level error code result. `0` indicates success.
`ErrorMessage`	string	Error message associated with the error code.
`RotationAngle`	decimal	Angle of rotation of the measured object.
`Length`	decimal?	Length of the object in `DimsUnitOfMeasure` units.
`Width`	decimal?	Width of the object in `DimsUnitOfMeasure` units.
`Height`	decimal?	Height of the object in `DimsUnitOfMeasure` units.

Ping

Describes the Ping endpoint

Images

Retrieving Images from the enVision K150S