Resolution

Introduction

This guide covers the Resolution endpoint.

Resolution leverages elastic search and natural language processing (NLP) techniques to accurately match queries with the most relevant results. The response includes an entity attribute profile, an entity_id, and an explanation with match_strength, helping you understand the confidence level for each match.

The Resolution endpoint is recommended for screening purposes or when clients need to validate entities of interest against the Sayari Knowledge Graph.

Please note: Sayari consistently enhances and refines its match resolution logic. Consequently, the results outlined in the guide below are for demonstration purposes and may not reflect the latest updates.

Entity Request

To initiate a request, at a minimum, the name of the entity is required. For optimal results, we advise providing additional attributes such as address, country, and type to facilitate high-confidence matches.

The endpoint also supports identifier, contact, and date_of_birth attributes. Although not mandatory, including these attributes significantly increases the likelihood of obtaining accurate matches by offering more specific query parameters.

Sample Request - Medium Confidence

The following example demonstrates a request yielding medium confidence results with multiple plausible matches:

Given only name and country attributes, there might be multiple entities with the name “Victoria Beckham” in Great Britain, despite it being a relatively unique name.

Parameters

  • name: Victoria Beckham
  • country: GBR
$curl --request GET \
>curl -X GET "https://api.sayari.com/v1/resolution?name=victoria+beckham&country=GBR" \
>     -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Response Review

The response lists four potential matches. Without additional attributes like an address or identifier, we cannot assign a match_strength of “strong”, which leads to all matches being categorized as “weak”. However, each match has highQualityMatchName: true, which indicates a high-quality match for the name and suggests a unique match possibility.

Data Summary

  • data: An array of match hits
  • data[].entity_id: The matched Sayari entity ID for subsequent calls
  • data[].label: The name of the matched Sayari entity
  • data[].type: The type of the matched Sayari entity
  • data[].identifiers: Unique identifiers for the matched entity
  • data[].addresses: Physical locations associated with the entity
  • data[].countries: Countries where the entity operates
  • data[].sources: Data sources contributing to the entity information
  • data[].matched_queries: Fields that matched the search query, confirming the relevance
  • data[].explanation: Includes highlighted text to emphasize the match and match_strength to indicate result confidence
1{
2  "query": {
3    "country": "GBR",
4    "name": "VICTORIA BECKHAM",
5    "type": "person"
6  },
7  "result": {
8    "score": 142.09607,
9    "entity_id": "uvMxmRmbVbGdvGy5wLpNpA",
10    "label": "VICTORIA BECKHAM",
11    "type": "person",
12    "addresses": [
13      "СОЕДИНЕННОЕ КОРОЛЕВСТВО | LONDON, W6 7DN | 202 HAMMERSMITH ROAD, GB"
14    ],
15    "countries": [
16      "GBR",
17      "KAZ"
18    ],
19    "sources": [
20      "95d4ee257c785546e66a87a37fa183f4"
21    ],
22    "typed_matched_queries": [
23      "name|0",
24      "type|0",
25      "country|1",
26      "country|0",
27      "looseName|0",
28      "type|2"
29    ],
30    "matched_queries": [
31      "name",
32      "type",
33      "country"
34    ],
35    "highlight": {
36      "type": [
37        "<em>PERSON</em>"
38      ],
39      "name": [
40        "<em>VICTORIA</em> <em>BECKHAM</em>"
41      ],
42      "country": [
43        "<em>GBR</em>"
44      ]
45    },
46    "explanation": {
47      "type": [
48        {
49          "matched": "<em>PERSON</em>",
50          "uploaded": "person"
51        }
52      ],
53      "name": [
54        {
55          "matched": "<em>VICTORIA</em> <em>BECKHAM</em>",
56          "uploaded": "VICTORIA BECKHAM",
57          "nameCustomTfIdfScore": 0.5416772821044128,
58          "highQualityMatchName": true,
59          "isDeletionRecommended": false
60        }
61      ],
62      "country": [
63        {
64          "matched": "<em>GBR</em>",
65          "uploaded": "GBR"
66        }
67      ]
68    },
69    "match_strength": {
70      "value": "weak"
71    }
72  }
73}

Sample Request - High Confidence

Enhancing the query with an address attribute and specifying a type can lead to a high-confidence match and fewer results:

Parameters

  • name: Victoria Beckham
  • address: Hammersmith Road, London, W6 7DN
  • country: GBR
  • type: person
$curl -X GET "https://api.sayari.com/v1/resolution?name=victoria+beckham&address=Hammersmith+Road%2C+London%2C+W6+7DN&type=person&country=GBR" \
>     -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Response Review

Incorporating the address and type attributes allows the Resolution endpoint to return a single, high-confidence match with a match_strength of “strong”.

1{
2  "query": {
3    "country": "GBR",
4    "name": "VICTORIA BECKHAM",
5    "type": "person",
6    "address": "Hammersmith Road, London, W6 7DN"
7  },
8  "result": {
9    "score": 274.4378,
10    "entity_id": "uvMxmRmbVbGdvGy5wLpNpA",
11    "label": "VICTORIA BECKHAM",
12    "type": "person",
13    "addresses": [
14      "СОЕДИНЕННОЕ КОРОЛЕВСТВО | LONDON, W6 7DN | 202 HAMMERSMITH ROAD, GB"
15    ],
16    "countries": ["GBR", "KAZ"],
17    "sources": ["95d4ee257c785546e66a87a37fa183f4"],
18    "typed_matched_queries": [
19      "type|1",
20      "strictAddressNormalNameCombo",
21      "type|0",
22      "name|StrictV2|0",
23      "address|StrictV2|0",
24      "address|NormalV2|0",
25      "country|0",
26      "name|NormalV2|0",
27      "strictNameNormalAddressCombo"
28    ],
29    "matched_queries": [
30      "type",
31      "strictAddressNormalNameCombo",
32      "name",
33      "address",
34      "country",
35      "strictNameNormalAddressCombo"
36    ],
37    "highlight": {
38      "type": ["<em>PERSON</em>"],
39      "name": ["<em>VICTORIA</em> <em>BECKHAM</em>"],
40      "address": [
41        "СОЕДИНЕННОЕ КОРОЛЕВСТВО | <em>LONDON</em>, <em>W6</em> <em>7DN</em> | 202 <em>HAMMERSMITH</em> <em>ROAD</em>, GB"
42      ],
43      "country": ["<em>GBR</em>"]
44    },
45    "explanation": {
46      "type": [
47        {
48          "matched": "<em>PERSON</em>",
49          "uploaded": "person"
50        }
51      ],
52      "name": [
53        {
54          "matched": "<em>VICTORIA</em> <em>BECKHAM</em>",
55          "uploaded": "VICTORIA BECKHAM",
56          "nameCustomTfIdfScore": 0.5416772821044128,
57          "highQualityMatchName": true,
58          "isDeletionRecommended": false
59        }
60      ],
61      "address": [
62        {
63          "matched": "СОЕДИНЕННОЕ КОРОЛЕВСТВО | <em>LONDON</em>, <em>W6</em> <em>7DN</em> | 202 <em>HAMMERSMITH</em> <em>ROAD</em>, GB",
64          "uploaded": "Hammersmith Road, London, W6 7DN"
65        }
66      ],
67      "country": [
68        {
69          "matched": "<em>GBR</em>",
70          "uploaded": "GBR"
71        }
72      ]
73    },
74    "match_strength": "strong"
75  }
76}

Congratulations! You just completed the Resolution Guide.