serialNumber #

the serialNumber is an optional request parameter, which should contain the expected serial numbers visible on the meter, if this happens to be known beforehand. Providing this parameter allows for verifying that the readings by Blicker are in line with the expectations, and that the end-user has taken an image of the correct meter.

Some meters might contain multiple serial numbers. For this reason, multiple expected serial numbers may be provided. Each serial number that Blicker detects is matched with the best match in the expected serial numbers.

Whether a serial number could be verified is indicated with messages and the verificationConfidence. If we would not send the serial number request parameter, the serial number object in the response would not contain a verification confidence.

The value of the request parameter should be an encoded JSON array with all of the expected serial numbers as strings, even when there is only a single one.

Example requests #

Whether a detected serial number can be matched to any of the expected serial numbers is indicated by the verification confidence. We will provide an example for all three possibilities.

High verification confidence #

The test image contains a single serial number “40000444”, which will be correctly read by Blicker. Let’s first show an example where we know the exact serial number beforehand, and thus provide it to the Blicker reading endpoint.

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'serialNumber=["40000444"]'

from pathlib import Path
from pprint import pprint

import requests

response = requests.post(
    "https://api.blicker.ai/blicker/2020-10-01",
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"serialNumber": '["40000444"]'},
)

pprint(response.json())

Info
Note that the exact syntax of double quotations marks is important. Otherwise the string could not be interpreted as a valid JSON array.

In case there is an exact match for all detected serial numbers with one of the expected serial numbers, no message will be returned, and the verification confidence of the respective serial number objects will be high. To be precise, the expected serial number does not have to be an exact match. When an expected serial number is an exact substring of the detected serial number, the verification confidence will also be high. We will show the response JSON with only relevant information included.

{
   "messages":[],
   "objects":{
      "meter":[
         {
            "objects":{
               "serialNumber":[
                  {
                     "messages":[],
                     "objectId":"o-8pcR38FP",
                     "value":"40000444",
                     "verificationConfidence":"high",
                     "expectedSerialNumber":"40000444"
                  }
               ]
            }
         }
      ]
   }
}

Now let’s say that we are actually unsure whether the serial number should be “40000444” or maybe “abcdefgh”. In this case, we can just pass both in the request parameter.

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'serialNumber=["40000444", "abcdefgh"]'

from pathlib import Path
from pprint import pprint

import requests

response = requests.post(
    "https://api.blicker.ai/blicker/2020-10-01",
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"serialNumber": '["40000444", "abcdefgh"]'},
)

pprint(response.json())

In this case, the response will be the same as before as the detected serial number could still be matched with high confidence to at least one of the expected serial numbers.

Medium verification confidence #

It could be that Blicker does not read the serial number entirely correct. For example, it might not detect all characters, or some characters might be incorrectly read. We will simulate this by changing the expected serial number slightly. Let’s say we would have expected the serial number to be “40000888”.

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'serialNumber=["40000888"]'

from pathlib import Path
from pprint import pprint

import requests

response = requests.post(
    "https://api.blicker.ai/blicker/2020-10-01",
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"serialNumber": '["40000888"]'},
)

pprint(response.json())

In this case the verification confidence will be medium, and a message is returned to signal that the serial number is probably correct.

{
   "messages":[
        {
            "code":"match_serial_number",
            "message":"The expected serial number has probably been found.",
            "messageId":"m-3EiJpBmz",
            "objectId":"o-KymZHXN8"
        }
   ],
   "objects":{
      "meter":[
         {
            "objects":{
               "serialNumber":[
                  {
                     "messages":["m-3EiJpBmz"],
                     "objectId":"o-KymZHXN8",
                     "value":"40000444",
                     "verificationConfidence":"high",
                     "expectedSerialNumber":"40000888"
                  }
               ]
            }
         }
      ]
   }
}

A serial number will have a medium verification confidence when one of the expected serial numbers is found as a fuzzy substring of the detected serial number with an edit distance of at most 3.

Low verification confidence #

Let’s now look at an example where the serial number could not be verified.

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'serialNumber=["abcdefgh"]'

from pathlib import Path
from pprint import pprint

import requests

response = requests.post(
    "https://api.blicker.ai/blicker/2020-10-01",
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"serialNumber": '["abcdefgh"]'},
)

pprint(response.json())

In this case, the verification confidence will be low, and the messageCode no_match_serial_number will be returned.

{
   "messages":[
        {
            "code":"no_match_serial_number",
            "message":"The expected serial number could not be verified.",
            "messageId":"m-LaByNyad",
            "objectId":"o-NBWZhWQZ"
        }
   ],
   "objects":{
      "meter":[
         {
            "objects":{
               "serialNumber":[
                  {
                     "messages":["m-LaByNyad"],
                     "objectId":"o-NBWZhWQZ",
                     "value":"40000444",
                     "verificationConfidence":"low",
                     "expectedSerialNumber":"abcdefgh"
                  }
               ]
            }
         }
      ]
   }
}