Entity Search

Introduction

This guide focuses on how to utilize the Entity Search endpoint.

Entity Search is a powerful tool for discovering entities or records of interest. Whether you’re investigating specific individuals like Victoria Beckham or exploring entities related to a broader inquiry, this endpoint provides a robust search capability to pinpoint the information you need.

Basic Entity Search

To make a simple request, use the “q” parameter to search against a query. The following are equivalent:

$
GET /v1/search/record?q=test HTTP/1.1
>
Accept: application/json
>
>
POST /v1/search/record HTTP/1.1
>
Accept: application/json
>
>
{
>
  "q": "test"
>
}

To initiate a workflow, begin by searching for an entity. For instance, to search for Victoria Beckham, you would use the following command:

1
POST https://api.sayari.com/v1/search/entity?limit=1
2
{
3
  "q": "victoria beckham"
4
}

This command returns the top entity match for “Victoria Beckham”, showcasing important details about the search hit:

1
{
2
    "offset": 0,
3
    "limit": 1,
4
    "next": true,
5
    "size": {
6
        "count": 8,
7
        "qualifier": "eq"
8
    },
9
    "data": [
10
        {
11
            "id": "XabunnGRTK2ieyLtP-PiUQ",
12
            "label": "VICTORIA CAROLINE BECKHAM",
13
            "type": "person",
14
            ...
15
            "matches": {
16
                "name": [
17
                    "<em>VICTORIA</em> CAROLINE <em>BECKHAM</em>"
18
                ]
19
            }
20
        }
21
    ]
22
}

Key Fields Explained

• data: An array of search hits
• data[].id: Sayari’s unique ID for the entity
• data[].label: The entity’s name
• data[].type: The type of entity (e.g., person or company)
• data[].entity_url: A relative URL to view more details about the entity
• data[].identifiers: A list of unique identifiers for the entity
• data[].countries: Associated countries for the entity using ISO 3166-1 alpha-3 codes
• data[].source_count: Counts of unique documents per source where this entity was found
• data[].relationship_count: Counts of neighbor entities by relationship type
• data[].matches: Highlighted matches in the search result

These fields help determine if a search hit warrants further investigation by providing insights into the entity’s relevance and connections.

Entity Search Facets

For a more granular view of your search results’ distribution by country, source, and entity type, include the facets query parameter:

1
POST https://api.sayari.com/v1/search/entity
2
{
3
  "q": "victoria beckham",
4
  "facets": true
5
}

The response will now include a facets property, offering a breakdown of counts per facet. This helps you understand the diversity and focus areas of your search results.

Entity Search Filters

To refine your search results, apply filters based on source, country, or entity type. This is particularly useful when dealing with common entity names or when you have specific criteria in mind:

1
POST https://api.sayari.com/v1/search/entity
2
{
3
  "filter": {
4
    "country": [
5
      "HKG"
6
    ]
7
  },
8
  "q": "jane smith"
9
}

Searching by Specific Fields

Beyond basic filters, you can target your search to specific fields, like identifier, address, name, position, and contact. For instance, to find entities matching a particular identifier:

1
POST https://api.sayari.com/v1/search/entity
2
{
3
  "q": "6543",
4
  "fields": [
5
    "identifier"
6
  ]
7
}