tags

tags #

Version info
This request parameter has been added in the the 2020-10-01 release.

Tags are a way to associate multiple types of extra data with requests by providing a list of strings. Unlike a referenceId, which is a single string that is generally used to associate requests with a unique meter or customer, tags can be used to more generally categorize requests.

Examples of tags are:

  • Name of a meter reader (e.g. reader=john doe)
  • Month being billed (e.g. 2021-08)
  • Administrative region of meter (e.g. state:texas)
  • User feedback provided after the request (e.g. correct or rejected)

Each request can contain multiple of these tags and more tags can be added after the request using the feedback API endpoints.

Tags must be specified as a JSON encoded array of strings.

Best practices #

The search functionality on the requests page in the portal allows you to later search requests by any combination of the tags that you’ve provided. You may, for example, want to quickly look up the image for a specific customer and billing cycle.

Even if you’re not currently doing many searches, it’s a good idea to already include any tags with your requests that may prove to be useful in the future. Tags are free to use and they consume negligible bandwidth compared to the photos themselves. It’s better to send some tags that don’t end up being useful after all than to run into a scenario where you want to search for information that wasn’t associated with the requests.

Every tag can be an arbitrary string, but it’s common to use a key:value or key=value style format when you want to combine the type of information and the information itself.

Example request #

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'tags=["month:2021-08","state:texas"]'
from pathlib import Path
from pprint import pprint

import json
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={"tags": json.dumps(["month:2021-08", "state:texas"])},
)

pprint(response.json())

If tags are provided in the request then the response will contain the same tags at the top-level.