search4faces.com - api

search4faces.com API specification


Our API, or application programming interface, allows you to programmatically interact with a search4faces website.

The search4faces API is a web based API and is shipped as part of the web frontend. It uses the JSON-RPC 2.0 protocol over HTTPS.

You must include the following headers in requests sent to the API:

Content-Type: application/json

x-authorization-token: your_API_key

The basic API endpoint is:

https://search4faces.com/api/json-rpc/v1

If you want to try our API and see how it works without purchasing our plans first, just contact our team and we will make the API accessible to you free of charge. Client libraries are available for PHP and Python.


rateLimit

Retrieve the details about your API key limits.

Example request:

{
  "jsonrpc": "2.0",
  "method": "rateLimit",
  "id": "some-id",
  "params": {}
}

The method takes no parameters.

Example of successful response:

{
  "jsonrpc": "2.0",
  "result": {
    "apikey": "5c40b9-b246ab-648561-435157-2c3f8b",
    "limit": 10000,
    "remaining": 9954,
    "enddate": 2022-03-05 00:00:00,
    "speed": 8,
    "allowed": [
      "rateLimit",
      "detectFaces",
      "searchFace"
    ],
    "disabled": "no"
  },
  "id": "some-id"
}

Returns:

apikey (str) - your API key
limit (int) - total number of requests
remaining (int) - number of requests remaining
enddate (datetime) - end date for your API key validity
speed (int) - requests per minute
allowed (array[str]) - list of allowed methods
disabled (bool) - API key status
detectFaces

Detects faces within an image that is provided as input.

Example request:

{
  "jsonrpc": "2.0",
  "method": "detectFaces",
  "id": "some-id",
  "params": {
    "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP/wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA="
  }
}

Parameters:

image (str) - input jpeg or png image as base64-encoded bytes 

Example of successful response:

{
  "jsonrpc": "2.0",
  "result": {
    "image": "5eb16c3421dd32.08349177.jpg",
    "faces": [
      {
        "x": 25,
        "y": 37,
        "width": 55,
        "height": 67,
        "lm1_x": 39,
        "lm1_y": 68,
        "lm2_x": 62,
        "lm2_y": 62,
        "lm3_x": 53,
        "lm3_y": 80,
        "lm4_x": 47,
        "lm4_y": 90,
        "lm5_x": 67,
        "lm5_y": 84
      },
      {...}
    ]
  },
  "id": "some-id"
}

Returns:

image (str) - unique image identifier to pass it to the searchFace method
faces (array[obj]) - details of each face found in the image
  x (int) - left coordinate of the bounding box
  y (int) - top coordinate of the bounding box
  width (int) - width of the bounding box
  height (int) - height of the bounding box
  lm1_x (int) - x-coordinate of the left eye
  lm1_y (int) - y-coordinate of the left eye
  lm2_x (int) - x-coordinate of the right eye
  lm2_y (int) - y-coordinate of the right eye
  lm3_x (int) - x-coordinate of the nose
  lm3_y (int) - y-coordinate of the nose    
  lm4_x (int) - x-coordinate of left corner of the mouth
  lm4_y (int) - y-coordinate of left corner of the mouth
  lm5_x (int) - x-coordinate of right corner of the mouth
  lm5_y (int) - y-coordinate of right corner of the mouth
searchFace

Search for similar faces in a database that contains billions of images.

Example request:

{
  "jsonrpc": "2.0",
  "method": "searchFace",
  "id": "some-id",
  "params": {
    "image": "5eb16c3421dd32.08349177.jpg",
    "face": {
      "x": 25,
      "y": 37,
      "width": 55,
      "height": 67,
      "lm1_x": 39,
      "lm1_y": 68,
      "lm2_x": 62,
      "lm2_y": 62,
      "lm3_x": 53,
      "lm3_y": 80,
      "lm4_x": 47,
      "lm4_y": 90,
      "lm5_x": 67,
      "lm5_y": 84
    },
    "source": "vk_wall",
    "hidden": true,
    "results": "10"
    "lang": "en"
  }
}

Parameters:

image (str) - unique image identifier received when calling the detectFaces method
face (obj) - details of the face found, for example, when calling detectFaces method
  x (int) - left coordinate of the bounding box
  y (int) - top coordinate of the bounding box
  width (int) - width of the bounding box
  height (int) - height of the bounding box
  lm1_x (int) - x-coordinate of the left eye
  lm1_y (int) - y-coordinate of the left eye
  lm2_x (int) - x-coordinate of the right eye
  lm2_y (int) - y-coordinate of the right eye
  lm3_x (int) - x-coordinate of the nose
  lm3_y (int) - y-coordinate of the nose    
  lm4_x (int) - x-coordinate of left corner of the mouth
  lm4_y (int) - y-coordinate of left corner of the mouth
  lm5_x (int) - x-coordinate of right corner of the mouth
  lm5_y (int) - y-coordinate of right corner of the mouth
source (str) - vkok_avatar or vk_wall or tt_avatar or ch_avatar  (unique identifier for the face search database)
hidden (bool) - show hidden profiles in addition to the visible ones
results (int) - limit the number of search results, max 500
lang (str) - language of choice, default is "ru"

Example of successful response:

{
  "jsonrpc": "2.0",
  "result": {
    "profiles": [
      {
        "score": "94.70",
        "face": "https://search4faces.com/faces/vk01/00/00/00/7/0.jpg",
        "profile": "https://vk.com/id1",
        "photo": "https://vk.com/id1?z=photo1_288668576%2Fphotos1",
        "photo_x": 368,
        "photo_y": 265,
        "photo_width": 146,
        "photo_height": 174,
        "source": "https://sun9-3.userapi.com/c7003/v7003978/1ed9/yoeGXOWmW-M.jpg",
        "age": 35,
        "first_name": "Павел",
        "last_name": "Дуров",
        "maiden_name": "",
        "city": "Санкт-Петербург",
        "country": "Россия"
      },
      {...}
    ]
  },
  "id": "some-id"
}

Returns:

profiles (array[obj]) - details of each user profile found
  score (float) - similarity score
  face (str) - link to the image of the face
  profile (str) - public profile url
  photo (str) - url of the source image preview
  photo_x (int) - left coordinate of the bounding box
  photo_y (int) - top coordinate of the bounding box
  photo_width (int) - width of the bounding box
  photo_height (int) - height of the bounding box
  source (str) - url of the source image
  age (int) - user's age
  first_name (str) - user's first name
  last_name (str) - user's last name
  maiden_name (str) - user's middle name
  city (str) - user's city
  country (str) - user's country