datetime #

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

An image file from a phone or camera often contains metadata that specifies when the photo was taken. You can use the datetime request parameter to check if this date and time falls into a specific range.

The date and time associated with an image file cannot be relied on to be accurate. It is easy to change these values in an existing photo and if, for example the date and time settings of the camera are wrong, then the value may not be correct to begin with. The image could also simply not contain date and time information at all.

We recommend that this check is only used to suggest that the user may want to pick a more recent photo and not to directly accept or reject photos.

The parameter should be provided as an encoded JSON object that contains a min value, max value, or both. Each value should be an ISO 8601 formatted string. The time values in photos usually don’t contain any timezone information, so both the value in the image and the range values are assumed to be local time. Any provided time offsets are ignored.

Example of a datetime value:

{"min": "2021-08-20T00:00:00", "max": "2021-08-25T23:59:59"}

This would check if the photo was taken in 2021 on August 20th, August 25th, or any day in-between.

The minimum and maximum range should account for possible timezone differences, so it’s a good idea to account for this by adding an extra few hours or days of range to both the minimum and maximum values.

The response will contain the specified time range as expectedDateTime and the actual time and date of the photo in metaData - if it contained that information:

    "expectedDatetime": {
        "min": "2021-08-20T00:00:00",
        "max": "2021-08-25T23:59:59"
    "metaData": {
        "datetime": "2017-04-01T12:34:56"

If the value falls outside the specified range then the response will also include a message:

    "messages": [
            "code": "no_match_minimum_datetime",
            "message": "The datetime of the image is lower than the expected minimum datetime.",
            "messageId": "<messageId>"

A different message will be included if the image did not contain date and time information at all:

    "messages": [
            "code": "no_valid_datetime",
            "message": "An expected datetime has been provided, but no valid datetime could be extracted from the image.",
            "messageId": "<messageId>"

Example request #

curl -X 'POST' \
  '' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'datetime={"min":"2021-08-20T00:00:00","max":"2021-08-25T23:59:59"}'
from pathlib import Path
from pprint import pprint

import requests

datetime = json.dumps({"min": "2021-08-20T00:00:00", "max": "2021-08-25T23:59:59"})

response =
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"datetime": datetime},