.. _api_search_objects:


Search for objects in the system
=======================================

FindFace Multi allows you to search for faces, bodies, and vehicles (collectively referred to as "objects") throughout the entire system.

You can search for a specific object in one of the following ways:

   * by uploading a photo
   * by an event ID
   * by an object ID
   * by a cluster ID

To search for an object by uploading a photo, follow these steps:

#. Upload a photo with the ``POST /detect`` :ref:`method <api_detect>`: attach the source image file and send the ``POST`` request. 
#. Check the response: it will include the ``id`` of the detected object and the coordinates of the object's bounding box (bbox).
#. If the image contains multiple objects, select the one of interest and copy its ``id`` value.
#. Use one of the following methods to search for that object:

   * ``GET /cards/humans/`` (to search in records of individuals)
   * ``GET /cards/cars/`` (to search in records of vehicles) 
   * ``GET /events/faces/`` (to search in face events) 
   * ``GET /events/bodies/`` (to search in body events) 
   * ``GET /events/cars/`` (to search in car events) 
   * ``GET /clusters/faces/`` (to search in face clusters) 
   * ``GET /clusters/bodies/`` (to search in body clusters) 
   * ``GET /clusters/cars/`` (to search in vehicle clusters)

#. In the ``looks_like`` parameter of the chosen method, specify the copied ``id`` in the following format: ``detection:<detection_id>``. The specified ``id`` must correspond to the object type supported by the chosen method. For example, if you use the ``GET /cards/humans/`` method, the specified ``id`` must be the ID of a face or body.
#. If necessary, narrow the search by specifying additional filtering parameters such as a watch list (``watch_lists``, ``matched_lists``), confidence threshold (``threshold``), and more.
#. Send the ``GET`` request. The response will contain the search results. For example, if you use the ``GET /cards/humans/`` method to search by the ``id`` of a face detected in the photo, the method will return one or more records, each including the ``looks_like`` object with the ``matched_object`` parameter that holds the ID of a face similar to the one you are searching for. :ref:`Example <search_example>`. 

Alternatively, instead of uploading a photo, you can search for an object directly by using an event ID, object ID, or cluster ID, as follows:

#. Choose one of the methods listed in step 4 above. 
#. | In the ``looks_like`` parameter of the chosen method, specify one or more search expressions. Each expression must follow the format ``{face|body|car}{event|object|cluster}:<id>``, where ``face``, ``body``, and ``car`` indicate the object type. 
   | The specified expressions must contain only an object type supported by the chosen method. Valid expressions for each method are shown in the :ref:`table <list_of_methods>` below.

.. note::
    
    If necessary, the expressions listed below can be specified in the ``looks_like`` parameter together with the ``detection:<detection_id>`` expression.

.. _list_of_methods:

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

     * - Method   
       - Valid expressions for the ``looks_like`` parameter
     * - ``GET /cards/humans/``
       - ``{face|body}event:<event_id>``, ``{face|body}object:<object_id>``, ``{face|body}cluster:<cluster_id>``
     * - ``GET /cards/cars/``
       - ``carevent:<event_id>``, ``carobject:<object_id>``, ``carcluster:<cluster_id>`` 
     * - ``GET /events/faces/``
       - ``faceevent:<event_id>``, ``faceobject:<object_id>``, ``facecluster:<cluster_id>``
     * - ``GET /events/bodies/``
       - ``bodyevent:<event_id>``, ``bodyobject:<object_id>``, ``bodycluster:<cluster_id>``
     * - ``GET /events/cars/``
       - ``carevent:<event_id>``, ``carobject:<object_id>``, ``carcluster:<cluster_id>`` 
     * - ``GET /clusters/faces/``
       - ``faceevent:<event_id>``, ``faceobject:<object_id>``, ``facecluster:<cluster_id>``
     * - ``GET /clusters/bodies/``
       - ``bodyevent:<event_id>``, ``bodyobject:<object_id>``, ``bodycluster:<cluster_id>``
     * - ``GET /clusters/cars/``
       - ``carevent:<event_id>``, ``carobject:<object_id>``, ``carcluster:<cluster_id>``