Guides

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.

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"
>}

Both GET and POST methods are supported. If you are a new API consumer, we recommend onboarding with POST, which will be referenced throughout this guide.

Warning: All search arguments passed through the query string of the GET request must be URL encoded. For example, foo OR (bar~5) becomes foo%20OR%20(bar~5).

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

1POST 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

Visit our ontology page to get a better understanding of our enum types and risk factors.

  • 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:

1POST 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:

1POST 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:

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

Congratulations! This concludes our Entity Search Guide. The Entity Search endpoint is a versatile tool for your investigative workflows, enabling you to explore entities based on a wide range of criteria. By leveraging facets and filters, you can navigate through vast datasets to find exactly what you’re looking for, ensuring your investigations are both efficient and comprehensive.

Built with