.. _api_compare:


Compare two objects
===============================


FindFace Multi allows you to compare two objects of the same type (such as two faces, two bodies, or two vehicles) and determine their similarity. 

To perform a comparison, use the following method:

.. code::

   GET /verify

The REQUEST contains the following QUERY-STRING PARAMETERS:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name 
       - Type 
       - Description
     * - ``card_id``
       - string
       - ID of the record that contains objects to be compared with the main object defined in the ``object1`` parameter.

         Constraint: Min 1 char.  
     * - ``object1*``
       - string
       - Reference expression that identifies the main object used for comparison. One of the following expressions must be specified:

          - ``detection:<detection_id>`` 
          - ``faceevent:<event_id>``
          - ``carevent:<event_id>`` 
          - ``bodyevent:<event_id>`` 
          - ``faceobject:<object_id>`` 
          - ``carobject:<object_id>`` 
          - ``bodyobject:<object_id>`` 

         Constraint: Min 1 char.  
     * - ``object2``
       - string
       - Reference expression that identifies a specific object to be compared with the main object defined in the ``object1`` parameter. Only a single expression is allowed. The format of the expression is the same as for the ``object1`` parameter.
       
          - If ``card_id`` is not specified, the object defined in the ``object1`` parameter is compared with the object defined in the ``object2`` parameter.
          - If ``card_id`` is specified, ``object2`` is ignored, and the object defined in the ``object1`` parameter is compared with each object of the same type in the record.

         Constraint: Min 1 char.
 
.. rubric:: CURL example

.. code::

 curl -X GET "http://<findface-ip:port>/verify?object1=faceobject%3A4693621634822370700&object2=detection%3Ad1rqpj4kd5qs72mq5290" \
  -H "Authorization: Token <token>"
  
For example, to compare two faces, follow these steps:

#. Use the ``POST /detect`` method to :ref:`detect a face in a photo <api_detect>` and copy the ``id`` of the detected face.
#. In the ``object1`` parameter of the ``GET /verify`` method, specify the copied ``id`` in the following format: ``detection:<detection_id>``.
#. | In the ``object2`` parameter of the ``GET /verify`` method, specify the event ID of the face to be compared with the face defined in the ``object1`` parameter. Use the following format: ``faceevent:<event_id>``.
   | If the response is successful (200 OK), it returns a JSON object with the ``confidence`` field that holds the estimated similarity score between the two objects (in this case, faces).

.. list-table::
   :widths: 14 8 45
   :header-rows: 1

   * - Name 
     - Type 
     - Description
   * - ``confidence*``
     - number|object
     - Similarity score between two feature vectors in the database. 
    
       If the ``object1`` and ``object2`` parameters are specified in the request, the ``confidence`` field contains the similarity score represented as a single number. :ref:`Example <response_example_object1_object2>`.
       
       If the ``object1`` and ``card_id`` parameters are specified in the request, the ``confidence`` field contains an object that includes the following indicators:
      
        - similarity scores between the object defined in the ``object1`` parameter and each object of the same type in the record;
        - average similarity score (``average_conf``). :ref:`Example <response_example_object1_card_id>`.

       Constraints: Min 0┃Max 1.

.. _response_example_object1_object2:

.. rubric:: Response example (``object1`` and ``object2`` specified)

.. code::

 {
  "confidence": 0.86446184
 }

.. _response_example_object1_card_id:

.. rubric:: Response example (``object1`` and ``card_id`` specified)

.. code::

 {
  "confidence": {
    "face_objects": {
      "4689934075046362827": 0.7640308,
      "4693436597895149109": 0.9912036,
      "4693621634822370700": 0.8532853
    },
    "average_conf": 0.86950657
  }
 }