Get similar person

Available in VPC

This API retrieves people whose faces resemble a specified person, sorted by similarity. The search results can be used as candidates for Merge person.

Note

You cannot search for similar people for those without thumbnails, as their facial feature information is unavailable. To find similar people based on a new image rather than registered images, use Compare person.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
GET	/api/v1/workspaces/{workspace_name}/persons/{person_id}/similar

Request headers

For information about the request headers common to all Media Intelligence APIs, see Media Intelligence request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`workspace_name`	String	Required	Workspace name
`person_id`	String	Required	Base person ID See Get person list.

Request query parameters

You can use the following query parameters with your request:

Field	Type	Required	Description
`personCount`	Integer	Optional	Number of similar persons to query 1-10 (default: 3)
`scoreThreshold`	Integer	Optional	Similarity threshold for determining whether two individuals are similar 80-100 (default: 80)

Request example

The request example is as follows:

curl --location --request GET 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/persons/1001/similar?personCount=3&scoreThreshold=80' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`code`	String	-	API processing result code
`message`	String	-	API processing result message
`result`	Object	-	Similar person query result
`result.personId`	Integer	-	Base person ID
`result.similarPersons`	Array	-	Similar persons list: similarPersons Similarity in descending order. An empty array if no person meets the criteria.

`similarPersons`

The following describes similarPersons.

Field	Type	Required	Description
`personId`	Integer	-	Similar person's person ID
`name`	String	-	Similar person's name Anonymous persons are indicated as null.
`score`	Number	-	Similarity to the base person 0-100
`assetCount`	Integer	-	Number of assets featuring similar person

Response status codes

For information about the response status codes common to all Media Intelligence APIs, see Media Intelligence response status codes.

Response example

The response example is as follows:

{
  "code": "0",
  "message": "success",
  "result": {
    "personId": 1001,
    "similarPersons": [
      {
        "personId": 1002,
        "name": null,
        "score": 93.42,
        "assetCount": 3
      },
      {
        "personId": 1003,
        "name": "Gilsun Hong",
        "score": 82.13,
        "assetCount": 1
      }
    ]
  }
}