# Face Search API

Face Search API facilitates searching an image of a face to the closest matching face from your own online cloud database that is hosted with FaceX.

Unlike the other APIs, Face Search hosts a persisting Database of your Face Collection which can be managed by REST APIs or the User Portal GUI.

Please Note:

Face Search does not come bundled with the FaceAPIs, there is a separate pricing based on your Database Size and Search Volume.

Subscribing to a Face Search plan gives access to :

  • Your own Online Image Database – the limit of which is determined by your active plan
  • REST APIs to manage and search through your Database
  • Access to a Search Log - Basic attendance log will be stored in your online portal for your reference

Face Search API plans are charged based on the number of images you wish to register in the database and the number of search calls required per day.

# Face Search API comes with the REST APIs below.

API Description
Add_single_Image Request to add a single image directly into your online image database
Add_image_approval Request to add an image to a segmented Database (which can be approved for adding to the database from your user portal)
SearchbyImage Search your database using an Image file (jpeg/png) to find the top three closest matches
SearchbyBase64 Search your database using a Base64 image to find the top three closest matches

When to use the Add_image_approval API:

Add_single_Image adds an Image to the Database and immediately makes it available for search. With Add_image_approval API, the image is not added in the search database until you approve it via the User-Portal and thus gives you control over the images registered in your database.

# Creating your online database

You can only search your Database if you have created your Database Collection of Images. There are two ways to add images to your database: through the FaceX portal or by using the REST API : Add_single_Image or Add_image_approval.

# How to Subscribe ?

To start using the Face Search APIs, you need to sign up and subscribe to the Face Search API plans View payment plans here. Learn more about signing up to the FaceAPI plans in our article “Getting Started with FaceX APIs“.

# Image Guidelines Recommendation

In general, as the Face Search API does not filter the image to support various applications, any image would be accepted by the API. However, for best results there are a few factors to keep in mind. Please refer to the article “Image Quality for Facial Recognition” for best practices.

We recommend an image resolution no higher than 1024p, since it could slow down the response received. Supported image formats are JPEG/PNG format. Read more about the recommended Image Quality

# Request 1 - Add Image to Database

  • API Name : Add Image to Database
  • Purpose : API Call to add a single Image to your Face Search Database.
  • Request Endpoint : https://search.facex.io:8443/images/singleImage/
Key Description Type
content-type multipart/form-data (if using image file)

# Body

Key Description Type
image An image file, supported files jpeg, png File
user_id Your valid User ID (as shown in your user portal when you log in) String
name Name/ ID (unique Identifier) of the person you wish to register String
See a sample response
{
    "status":"ok",
    "code":1000,
    "success":true,
    "message":"Added image to batch.",
    "data":{
        "image_id":5bbbbBbbbBbBBbbbbbbbbbbB”
    }
}

ℹ️ If you do not receive the above response, it is highly likely that your Face Search Plan is not activated. Please write to us to figure out why. Alternatively, an extensive list of our Error Codes and solutions for each code can be found here.

# Video Demo of Web-Trial

# Request 2 - Add Image for Admin Approval

  • API Name : Add Image to Database for Admin Approval
  • Purpose : If you want to have an Admin Control to approve/delete Images to be added to the Database
  • Request Endpoint : https://search.facex.io:8443/images/singleImageForApproval/

# Header

Key Description Type
content-type multipart/form-data (if using image file)

# Body

Key Description Type
image An image file, supported files jpeg, png File
user_id Your valid User ID (as shown in your user portal when you log in) String
See a sample response
{
   "status":"ok",
   "code":1000,
   "success":true,
   "message":"Image added. Contact admin for approval",
   "data":{

   }
}

Isn't there a Name field in this API ?

You might have noticed that there unlike Add Image API (Request 1) there isn't a field in the Request Body to pass the image. This is not provided in this API to enable the Admin to add and approve the Images sent for this request.

# Video Demo of Web-Trial

# Request 3 - Search database using Image File

  • API Name : Search database using Image File
  • Purpose : API to search your database of Images with a single Image File, by default the top three matches are provided in this response
  • Request Endpoint : https://search.facex.io:8443/auth/searchWithRawImage

# Header

Key Description Type
content-type multipart/form-data (if using image file)

# Body

Key Description Type
image An image file, supported files jpeg, png File
user_id Your valid User ID (as shown in your user portal when you log in) String
See a sample response
{
   "status":"ok",
   "code":1000,
   "success":true,
   "message":"Success.",
   "data":{
      "user":[
         {
            "_id":“image_id_closest match_1,
            "file_name":"file_name",
            "file_directory":"image_URL",
            "fullvector":"vector_value",
            "user_id":"",
            "index_value":"XX",
            "batch_id":"upload_batch_id",
            "person_name":"registered_name",
            "createdAt":"time _stamp",
            "updatedAt":"time _stamp",
            "__v":0,
            "distance":0.1
         },
         {
            "_id":“image_id_closest match_2,
            "file_name":"file_name",
            "file_directory":"image_URL",
            "fullvector":"vector_value",
            "user_id":"",
            "index_value":"XX",
            "batch_id":"upload_batch_id",
            "person_name":"registered_name",
            "createdAt":"time_stamp",
            "updatedAt":"time_stamp",
            "__v":0,
            "distance":0.6
         }
      },
{
         "_id":“image_id_closest match_3,
         "file_name":"file_name",
         "file_directory":"image_URL",
         "fullvector":"vector_value",
         "user_id":"",
         "index_value":"XX",
         "batch_id":"upload_batch_id",
         "person_name":"registered_name",
         "createdAt":"time_stamp",
         "updatedAt":"time_stamp",
         "__v":0,
         "distance":0.61
      }
   }
]
}
}

# Video Demo of Web-Trial

# Interpreting the Response

When a match is found the API will return the top three matches. The Response would have a "distance" parameter. Matches with Euclidean distance less than 0.5 have a higher probability for a TRUE Match. The Public Image URL, File Name and Registered Name will also be returned to help you display it on your application.

# Request 4 - Search database using Base64 Images

  • API Name : Search database using Base64 Image
  • Purpose : API to search your database of Images with a single Base64 image, by default the top three matches are provided in this response
  • Request Endpoint : https://search.facex.io:8443/auth/searchWithEncodedImage

# Header

Key Description Type
content-type application/json

# Body

{
    "image_encoded": "your_base64_image_should_be_added_here",
    "user_id" : "your_user_id" 
}
See a sample response
{
   "status":"ok",
   "code":1000,
   "success":true,
   "message":"Success.",
   "data":{
      "user":[
         {
            "_id":“image_id_closest match_1,
            "file_name":"file_name",
            "file_directory":"image_URL",
            "fullvector":"vector_value",
            "user_id":"",
            "index_value":"XX",
            "batch_id":"upload_batch_id",
            "person_name":"registered_name",
            "createdAt":"time _stamp",
            "updatedAt":"time _stamp",
            "__v":0,
            "distance":0.1
         },
         {
            "_id":“image_id_closest match_2,
            "file_name":"file_name",
            "file_directory":"image_URL",
            "fullvector":"vector_value",
            "user_id":"",
            "index_value":"XX",
            "batch_id":"upload_batch_id",
            "person_name":"registered_name",
            "createdAt":"time_stamp",
            "updatedAt":"time_stamp",
            "__v":0,
            "distance":0.6
         }
      },
{
         "_id":“image_id_closest match_3,
         "file_name":"file_name",
         "file_directory":"image_URL",
         "fullvector":"vector_value",
         "user_id":"",
         "index_value":"XX",
         "batch_id":"upload_batch_id",
         "person_name":"registered_name",
         "createdAt":"time_stamp",
         "updatedAt":"time_stamp",
         "__v":0,
         "distance":0.61
      }
   }
]
}
}

# Interpreting the Response

When a match is found the API will return the top three matches. The Response would have a "distance" parameter. Matches with Euclidean distance less than 0.5 have a higher probability for a TRUE Match. The Public Image URL, File Name and Registered Name will also be returned to help you display it on your application.

Last Updated: 5/12/2020, 4:35:31 PM