Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Searching for users (image)

Focus mode
Searching for users (image) - Amazon Rekognition

SearchUsersByImagesearches the specified CollectionID for users in a collection that match the largest face detected in a supplied image. By default, SearchUsersByImage returns UserIDs for which the similarity score is greater than 80%. The similarity indicates how closely the UserID matches the largest face detected in the supplied image. If multiple UserIDs are returned, they are listed in order of highest similarity score to lowest. Optionally, you can use the UserMatchThreshold to specify a different value. For more information, see Managing users in a collection.

To search users by image (SDK)
  1. If you haven't already:

    1. Create or update a user with AmazonRekognitionFullAccess permissions. For more information, see Step 1: Set up an AWS account and create a User.

    2. Install and configure the AWS CLI and the AWS SDKs. For more information, see Step 2: Set up the AWS CLI and AWS SDKs.

  2. Use the following examples to call the SearchUsersByImage operation.

    Java

    This Java example searchers the users in a collection based off an inpute image, using the SearchUsersByImage operation.

    import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.SearchUsersByImageRequest; import com.amazonaws.services.rekognition.model.SearchUsersByImageResult; import com.amazonaws.services.rekognition.model.UserMatch; public class SearchUsersByImage { //Replace bucket, collectionId and photo with your values. public static final String collectionId = "MyCollection"; public static final String s3Bucket = "bucket"; public static final String s3PhotoFileKey = "input.jpg"; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); // Get an image object from S3 bucket. Image image = new Image() .withS3Object(new S3Object() .withBucket(s3Bucket) .withName(s3PhotoFileKey)); // Search collection for users similar to the largest face in the image. SearchUsersByImageRequest request = new SearchUsersByImageRequest() .withCollectionId(collectionId) .withImage(image) .withUserMatchThreshold(70F) .withMaxUsers(2); SearchUsersByImageResult result = rekognitionClient.searchUsersByImage(request); System.out.println("Printing search result with matched user and similarity score"); for (UserMatch match: result.getUserMatches()) { System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity()); } } }
    AWS CLI

    This AWS CLI command searches the users in a collection based on an input image, with the SearchUsersByImage operation.

    aws rekognition search-users-by-image --image '{"S3Object":{"Bucket":"s3BucketName","Name":"file-name"}}' --collection-id MyCollectionId --region region-name
    Python

    The following example searches the users in a collection based on an input image, with the SearchUsersByImage operation.

    # Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. # PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) import boto3 from botocore.exceptions import ClientError import logging import os logger = logging.getLogger(__name__) session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') def load_image(file_name): """ helper function to load the image for indexFaces call from local disk :param image_file_name: The image file location that will be used by indexFaces call. :return: The Image in bytes """ print(f'- loading image: {file_name}') with open(file_name, 'rb') as file: return {'Bytes': file.read()} def search_users_by_image(collection_id, image_file): """ SearchUsersByImage operation with user ID provided as the search source :param collection_id: The ID of the collection where user and faces are stored. :param image_file: The image that contains the reference face to search for. :return: response of SearchUsersByImage API """ logger.info(f'Searching for users using an image: {image_file}') try: response = client.search_users_by_image( CollectionId=collection_id, Image=load_image(image_file) ) print(f'- found {len(response["UserMatches"])} matches') print([f'- {x["User"]["UserId"]} - {x["Similarity"]}%' for x in response["UserMatches"]]) except ClientError: logger.exception(f'Failed to perform SearchUsersByImage with given image: {image_file}') raise else: print(response) return response def main(): collection_id = "collection-id" IMAGE_SEARCH_SOURCE = os.getcwd() + '/image_path' search_users_by_image(collection_id, IMAGE_SEARCH_SOURCE) if __name__ == "__main__": main()

    This Java example searchers the users in a collection based off an inpute image, using the SearchUsersByImage operation.

    import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.SearchUsersByImageRequest; import com.amazonaws.services.rekognition.model.SearchUsersByImageResult; import com.amazonaws.services.rekognition.model.UserMatch; public class SearchUsersByImage { //Replace bucket, collectionId and photo with your values. public static final String collectionId = "MyCollection"; public static final String s3Bucket = "bucket"; public static final String s3PhotoFileKey = "input.jpg"; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); // Get an image object from S3 bucket. Image image = new Image() .withS3Object(new S3Object() .withBucket(s3Bucket) .withName(s3PhotoFileKey)); // Search collection for users similar to the largest face in the image. SearchUsersByImageRequest request = new SearchUsersByImageRequest() .withCollectionId(collectionId) .withImage(image) .withUserMatchThreshold(70F) .withMaxUsers(2); SearchUsersByImageResult result = rekognitionClient.searchUsersByImage(request); System.out.println("Printing search result with matched user and similarity score"); for (UserMatch match: result.getUserMatches()) { System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity()); } } }

SearchUsersByImage operation request

The request for SearchUsersByImage includes the the collection to search in and the source image location. In this example, the source image is stored in an Amazon S3 bucket ( S3Object ). Also specified are the maximum number of users to return ( MaxUsers ) and the minimum confidence that must be matched for a user to be returned ( UserMatchThreshold).

{ "CollectionId": "MyCollection", "Image": { "S3Object": { "Bucket": "bucket", "Name": "input.jpg" } }, "MaxUsers": 2, "UserMatchThreshold": 99 }

SearchUsersByImage operation response

The response for SearchUsersByImage includes a FaceDetail object for the SearchedFace, as well as a list of UserMatches with the UserId, Similarity, and UserStatus for each. If the input image contained more than one face, a list of UnsearchedFaces will be also returned.

{ "SearchedFace": { "FaceDetail": { "BoundingBox": { "Width": 0.23692893981933594, "Top": 0.19235000014305115, "Left": 0.39177176356315613, "Height": 0.5437348484992981 } } }, "UserMatches": [ { "User": { "UserId": "demoUser1", "UserStatus": "ACTIVE" }, "Similarity": 100.0 }, { "User": { "UserId": "demoUser2", "UserStatus": "ACTIVE" }, "Similarity": 99.97946166992188 } ], "FaceModelVersion": "6", "UnsearchedFaces": [ { "FaceDetails": { "BoundingBox": { "Width": 0.031677018851041794, "Top": 0.5593535900115967, "Left": 0.6102562546730042, "Height": 0.0682177022099495 } }, "Reasons": [ "FACE_NOT_LARGEST" ] }, { "FaceDetails": { "BoundingBox": { "Width": 0.03254449740052223, "Top": 0.6080358028411865, "Left": 0.516062319278717, "Height": 0.06347997486591339 } }, "Reasons": [ "FACE_NOT_LARGEST" ] } ] }
PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.