messages #

The messages at the top-level of the response contains an aggregate list of all messages. In general, messages warn that something is odd about the image or detected objects.
This key is always present, even when there are no messages.

Note that messages may be bound to a specific object. The corresponding objects in the response will also have a messages key. Within the objects, however, this is a list of only the messageIds. The actual messages are contained in the messages object at the top-level of the response.

Each message contains the following values:

messageId is an identifier of the message, formatted by m- followed by 8 random characters.
messageCode is a slug which represents the message type. See below for a table of all message types.
message is the written out message in the requested language.
objectId (optional) is an identifier of the object the message is bound to. See also objectId.

Note that the message value of these messages exists mostly for the convenience of developers. In other words, it is not recommended to show these messages as-is to end-users, but instead handle each message code individually, and provide custom translations for each message code relevant to the specific application and end-users. Alternatively, some types of messages may be ignored or not shown to end-users but handled differently. For example, the corresponding request could be flagged for later manual inspection.

Message codes #

We make a distinction between messages that are not bound to objects, messages that are bound to the meter object, and messages that are bound to display, serial number or barcode objects.

Not bound #

`messageCode`	`message` (English)	Notes
no_meter	No meter has been detected for this image.
no_match_gps_location	The GPS location of the image does not match the expected GPS location.	Added in 2020-10-01
no_valid_gps_location	No valid GPS information could be extracted from the image.	Added in 2020-10-01
no_valid_datetime	No valid datetime could be extracted from the image.	Added in 2020-10-01
no_match_minimum_datetime	The datetime of the image is lower than the expected minimum datetime.	Added in 2020-10-01
no_match_maximum_datetime	The datetime of the image is higher than the expected maximum datetime.	Added in 2020-10-01

Bound to meter object #

`messageCode`	`message` (English)
multiple_serial_numbers	Multiple possible serial numbers were detected.
uneven_displays	Displays with different numbers of digits have been found.
no_match_expected_n_displays	The number of displays detected does not match the expected number.
no_match_meter_category	The detected meter category does not match the expected meter category.
no_match_display_type	The display type of the detected meter does not match the expected display type.

Bound to display, serial number or barcode object #

`messageCode`	`message` (English)
no_display_value	No value has been detected for this display.
no_serial_number_value	No value has been detected for this serial number.
missing_display_digits	We suspect we missed some digits in this display. Mind the flash and any other obstructions.
missing_serial_number_characters	We suspect we missed some characters in this serial number. Mind the flash and any other obstructions.
display_on_edge	This display is on the edge of the photo. It might be truncated.
serial_number_on_edge	This serial number is on the edge of the photo. It might be truncated.
short_display	Only a few digits of this display have been read. It might be an incomplete reading.
short_serial_number	Only a few digits of this serial number have been read. It might be an incomplete reading.
no_match_expected_n_digits	The number of detected digits on this display does not match the expected number.
no_match_expected_display_range	The meter reading is outside the expected range.
no_match_serial_number	The expected serial number could not be verified.
match_serial_number	The expected serial number has probably been found.

Example response #

The following (incomplete) response contains examples of messages that are bound to the meter object, a display object, or to no object.

{
   "messages":[
        {
            "code":"uneven_displays",
            "message":"Displays with different numbers of digits have been found.",
            "messageId":"m-BaPCeDMg",
            "objectId":"o-GsWyEHGw"
        },
        {
            "code":"short_display",
            "message":"Only a few digits of this display have been read. It might be an incomplete reading.",
            "messageId":"m-bBzgy8rC",
            "objectId":"o-chL8oW88"
        }, 
        {
            "code": "no_valid_gps_location",
            "message": "No valid GPS information could be extracted from the image.",
            "messageId": "m-4Rxthan7"
        }
   ],
   "objects":{
      "meter":[
         {
           "objectId":"o-GsWyEHGw",
           "messages":["m-BaPCeDMg"],
            "objects":{
               "display":[
                  {
                     "objectId":"o-chL8oW88",
                     "messages":["m-bBzgy8rC"]
                  }
               ]
            }
         }
      ]
   }
}