Trade Search - Suppliers & Buyers

Introduction

This guide covers the Suppliers & Buyers endpoints.

Due to the similar nature of these endpoints, this guide focuses on suppliers. However, the same principles and structure apply to buyers. The key difference is the entity of interest, simply:

  • The buyer is the company entity receiving and importing goods.
  • The supplier is the company entity shipping and exporting goods.

We recommend using these endpoints when the principal object you are looking to return is the supplier or buyer company entity and a summary of their shipment metadata.

For guidance on how to utilize the Shipments endpoint, which returns the shipment entity as the principal object, check out our Guide: Trade Search - Shipments.

Supplier & Buyer Request

The following example demonstrates how to search for cotton shipments departing from China to Vietnam after January 1, 2023, with a summary of trade data:

Note: We have used the same filters as the example in the Guide: Trade Search - Shipment to demonstrate how these endpoints differ.

1POST https://api.sayari.com/v1/trade/search/suppliers
2{
3  "filter": {
4    "departure_country": ["CHN"],
5    "arrival_country": ["VNM"],
6    "hs_code": ["52"],
7    "arrival_date": ["2023-01-01"]
8  },
9  "facets": true
10}

Response Review

Responses are structured to provide a comprehensive view of the trade data, with a default and max limit of 100 suppliers per response. You can adjust this limit as needed and may use offset pagination to navigate through larger datasets of up to 100 paginations.

Understanding Facets

Facets offer a macro-level overview of trade activity, with results ranked by highest count. By summarizing various aspects of trade data, facets help you understand the breadth of your search results and identify focus areas. The below facets are available, providing a breakdown of relevant counts:

Supplier Risk: Counts of specific risk factors associated with supplier entities, based on our risk factor ontology. Review our risk factor ontology for details.

1"supplier_risk": [
2{
3"key": "owned_by_sanctioned_entity",
4"doc_count": 8
5},

Buyer Risk: Counts of specific risk factors associated with buyer entities, based on our risk factor ontology. Review our risk factor ontology for details.

1"buyer_risk": [
2{
3"key": "export_to_soe",
4"doc_count": 478
5},

Supplier Country: Country counts per supplier country

1"supplier_country": [
2{
3"key": "CHN",
4"doc_count": 25318,
5"label": "China"
6},

Buyer Country: Country counts per buyer country

1"buyer_country": [
2{
3"key": "VNM",
4"doc_count": 28678,
5"label": "Vietnam"
6},

Understanding the Suppliers & Buyers Object

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

Each entity object in the response provides the following detailed information:

Entity Overview:

  • data: An array of entity (Supplier & Buyer) hits
  • data[].id: The Sayari entity_id
  • data[].label: The name of the entity
  • data[].degree: The number edges, or relationships, the entity has
  • data[].type: Specifies the entity type, which will always be company
  • data[].pep: Indicates whether the entity is politically exposed (false in this case, meaning it’s not)
  • data[].sanctioned: Shows if the entity is on any sanctions lists (false here, meaning it’s not)
  • data[].closed: Status indicating if the entity is currently operational (false here, meaning the entity is active)

Entity Attribute Data:

  • data[].addresses: Lists physical locations associated with the entity across various countries
  • data[].countries: Includes countries where the entity operates or has related source data

Relationship and Trade Activity:

  • data[].relationship_count: Breaks down the entity’s trading relationships, including the number of entities it ships to and receives from
  • data[].source_count: Details the data sources contributing to the entity’s profile

Entity Risk:

  • data[].risk: Contains risk factors like owned_by_sanctioned_entity, assessing the entity’s risk level

Metadata and Trade Details:

  • data[].metadata: Provides insights into trade activities, including the latest shipment date, total shipments, and Harmonized System (HS) codes for the traded goods
1{
2  "data": [
3    {
4      "id": "WT_MMBH-nO_M_K7kYFxyYQ",
5      "label": "UNITED WELL TRADING LIMITED",
6      "degree": 24303,
7      "entity_url": "/v1/entity/WT_MMBH-nO_M_K7kYFxyYQ",
8      "pep": false,
9      "psa_id": "249108827632",
10      "psa_count": 39,
11      "sanctioned": false,
12      "closed": false,
13      "type": "company",
14      "identifiers": [],
15      "addresses": [
16        "16/F , RAILWAY PLAZA , NOS.39 CHATHAM ROAD SOUTH , TSIM SHA TSUI , KOWLOON , HONG KONG , HK",
17        "NO.2 , 1/F , FACTORY 4 , 2 CENTURY ROAD , TORCH DEVELOPMENT ZONE , ZHONGSHAN , GUANGDONG PROVINCE , CN",
18        "NO.2 , 1/F , FACTORY 4 , 2 CENTURY ROAD , TORCH DEVELOPMENT ZONE , ZHONGSHAN , GUANGDONG PROVINCE , CHINA , CN"
19      ],
20      "countries": [
21        "VNM",
22        "JPN",
23        "CHN",
24        "HKG",
25        "KOR"
26      ],
27      "relationship_count": {
28        "ships_to": 25,
29        "receives_from": 14,
30        "receiver_of": 2996,
31        "shipper_of": 21270
32      },
33      "source_count": {
34        "ee100f9b5dfdae8991ba43f5de6e1854": {
35          "count": 2,
36          "label": "Panama Imports & Exports (January 2022 - Present)"
37        },
38        "ce462e9deea545cce35df38c48512a0c": {
39          "count": 8,
40          "label": "India Imports & Exports (January 2023 - Present)"
41        },
42        "e5de7b52cc88ef4cd1a10e201bdf46ee": {
43          "count": 22497,
44          "label": "Vietnam Imports & Exports (January 2023 - Present)"
45        },
46        "31df3cc3a57cc4a39dcc29dd4b9ce5e5": {
47          "count": 800,
48          "label": "Mexico Imports & Exports (January 2022 - Present)"
49        },
50        "16a4cc2d0f467fa993b28587d542a25d": {
51          "count": 999,
52          "label": "USA Imports (2021 - Present)"
53        }
54      },
55      "risk": {
56        "basel_aml": {
57          "value": 7.1,
58          "metadata": {
59            "country": [
60              "VNM"
61            ]
62          },
63          "level": "relevant"
64        },
65        "cpi_score": {
66          "value": 39,
67          "metadata": {
68            "country": [
69              "VNM"
70            ]
71          },
72          "level": "relevant"
73        }
74      },
75      "user_attribute_count": {},
76      "user_record_count": 0,
77      "user_related_entities_count": 0,
78      "user_relationship_count": {},
79      "related_entities_count": 24303,
80      "attribute_count": {
81        "contact": 5,
82        "address": 36,
83        "country": 7,
84        "name": 1
85      },
86      "metadata": {
87        "latestShipmentDate": "2023-10-31",
88        "shipments": 1145,
89        "hsCodes": [
90          {
91            "key": "520931",
92            "doc_count": 541,
93            "value": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, plain weave, weighing more than 200g/m2",
94            "value_simple": "Heavy major cotton fabrics"
95          },
96          {
97            "key": "520939",
98            "doc_count": 496,
99            "value": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, of weaves n.e.c. in item no. 5209.3, weighing more than 200g/m2",
100            "value_simple": "Heavy major cotton fabrics"
101          },
102          {
103            "key": "52093100",
104            "doc_count": 486,
105            "value": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, plain

Congratulations! This concludes our Trade Search - Suppliers & Buyers Guide. Whether you’re conducting in-depth research or simply exploring global trade patterns, we hope our API offers the data and insights you need.