Rekognition / Client / search_users

search_users#

Rekognition.Client.search_users(**kwargs)#

Searches for UserIDs within a collection based on a FaceId or UserId. This API can be used to find the closest UserID (with a highest similarity) to associate a face. The request must be provided with either FaceId or UserId. The operation returns an array of UserID that match the FaceId or UserId, ordered by similarity score with the highest similarity first.

See also: AWS API Documentation

Request Syntax

response = client.search_users(
    CollectionId='string',
    UserId='string',
    FaceId='string',
    UserMatchThreshold=...,
    MaxUsers=123
)
Parameters:

  • CollectionId (string) –

    [REQUIRED]

    The ID of an existing collection containing the UserID, used with a UserId or FaceId. If a FaceId is provided, UserId isn’t required to be present in the Collection.

  • UserId (string) – ID for the existing User.

  • FaceId (string) – ID for the existing face.

  • UserMatchThreshold (float) – Optional value that specifies the minimum confidence in the matched UserID to return. Default value of 80.

  • MaxUsers (integer) – Maximum number of identities to return.

Return type:

dict

Returns:

Response Syntax

{
    'UserMatches': [
        {
            'Similarity': ...,
            'User': {
                'UserId': 'string',
                'UserStatus': 'ACTIVE'|'UPDATING'|'CREATING'|'CREATED'
            }
        },
    ],
    'FaceModelVersion': 'string',
    'SearchedFace': {
        'FaceId': 'string'
    },
    'SearchedUser': {
        'UserId': 'string'
    }
}

Response Structure

  • (dict) –

    • UserMatches (list) –

      An array of UserMatch objects that matched the input face along with the confidence in the match. Array will be empty if there are no matches.

      • (dict) –

        Provides UserID metadata along with the confidence in the match of this UserID with the input face.

        • Similarity (float) –

          Describes the UserID metadata.

        • User (dict) –

          Confidence in the match of this UserID with the input face.

          • UserId (string) –

            A provided ID for the UserID. Unique within the collection.

          • UserStatus (string) –

            The status of the user matched to a provided FaceID.

    • FaceModelVersion (string) –

      Version number of the face detection model associated with the input CollectionId.

    • SearchedFace (dict) –

      Contains the ID of a face that was used to search for matches in a collection.

      • FaceId (string) –

        Unique identifier assigned to the face.

    • SearchedUser (dict) –

      Contains the ID of the UserID that was used to search for matches in a collection.

      • UserId (string) –

        A provided ID for the UserID. Unique within the collection.

Exceptions

  • Rekognition.Client.exceptions.InvalidParameterException

  • Rekognition.Client.exceptions.ResourceNotFoundException

  • Rekognition.Client.exceptions.ProvisionedThroughputExceededException

  • Rekognition.Client.exceptions.AccessDeniedException

  • Rekognition.Client.exceptions.InternalServerError

  • Rekognition.Client.exceptions.ThrottlingException