Trade Search - Shipments

Introduction

This guide covers the Shipments endpoint.

We recommend using this endpoint when the principal object you are looking to return is a shipment. If you are looking for specific shipments in relation to particular entities, set the appropriate parameter filters, such as buyer_name or buyer_id. This will return back shipments related to these entities.

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

Shipment 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 - Suppliers & Buyers to demonstrate how these endpoints differ.

1 POST https://api.sayari.com/v1/trade/search/shipments
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 shipments per response. You can adjust this limit as needed and may use offset pagination to navigate through larger datasets of up to 100 paginations.

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 suppliers, based on our risk factor ontology

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

Buyer Risk: Counts of specific risk factors associated with buyers, based on our risk factor ontology

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

Departure Country: Shipment counts summarized by their departure country

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

Arrival Country: Shipment counts summarized by their arrival country

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

Top Suppliers: Identifies top suppliers by shipment count

1 "top_suppliers": [
2 {
3 "key": "4f5tF_6i3dFFvr4lDIrGAQ",
4 "doc_count": 3388
5 },

Top Buyers: Identifies top buyers by shipment count

1 "top_buyers": [
2 {
3 "key": "o2C-58vBszngTbUVbWJvww",
4 "doc_count": 1615
5 },

HS Code: Summarizes shipments by Harmonized System codes, offering both detailed and simplified descriptions

1 "hs_code": [
2 {
3 "key": "520939",
4 "doc_count": 2630,
5 "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",
6 "value_simple": "Heavy major cotton fabrics"
7 },

Source: Counts and summarizes shipments according to the underlying data sources

1 "source": [
2 {
3 "key": "e5de7b52cc88ef4cd1a10e201bdf46ee",
4 "doc_count": 28644
5 },

Understanding the Shipment Object

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

Each shipment object in the response provides detailed information:

data: An array of shipment hits
data[].id: The Sayari entity ID
data[].type: Always shipment, indicating the entity type
data[].arrival_date & departure_date: Key dates indicating when the shipment arrived and departed
data[].monetary_value & weight: The financial value and weight of the shipment, respectively
data[].supplier & buyer: Includes IDs, names, risk factors, associated countries, and business purposes for both buyers and suppliers
data[].identifier: Unique identifiers for the shipment, aiding in tracking and referencing
data[].sources: Data source ID and label, crucial for verification and reliability assessments
data[].hs_codes: Detailed Harmonized System codes and descriptions for the goods being shipped
data[].product_descriptions: Commercial descriptions of the goods being shipped
data[].record: The underlying record. Use this value as the id to query the Record endpoint.

1 "data": [
2         {
3             "id": "3WBjyrwq_91w7_IRgWKJyg",
4             "type": "shipment",
5             "buyer": [
6                 {
7                     "id": "CA4CHQMukcdQ03z-ij8qqA",
8                     "names": [
9                         "CôNG TY TNHH THIếT Kế PHụ KIệN THờI TRANG VIệT NAM",
10                         "VIET NAM STYLE FASHION ACCESSORIES COMPANY LIMITED",
11                         "VN STYLE FASHION ACCESSORIES CO.,LTD"
12                     ],
13                     "risks": {
14                         "basel_aml": 7.1,
15                         "cpi_score": 39
16                     },
17                     "countries": [
18                         "VNM"
19                     ],
20                     "business_purpose": []
21                 }
22             ],
23             "supplier": [
24                 {
25                     "id": "g39mBNjuFwXDncovHHfwFA",
26                     "names": [
27                         "HEDERA INTERNATIONAL TRADING LIMITED/SHANGHAI STYLE FASHION ACCESSORIE"
28                     ],
29                     "risks": {
30                         "basel_aml": 6.81,
31                         "cpi_score": 45
32                     },
33                     "countries": [
34                         "CHN"
35                     ],
36                     "business_purpose": []
37                 }
38             ],
39             "arrival_date": "2023-05-25",
40             "departure_date": "2023-05",
41             "monetary_value": [],
42             "weight": [],
43             "identifier": [
44                 {
45                     "value": "{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}",
46                     "type": "global_trade_internal_shipment_id"
47                 }
48             ],
49             "sources": [
50                 {
51                     "id": "e5de7b52cc88ef4cd1a10e201bdf46ee",
52                     "label": "Vietnam Imports & Exports (January 2023 - Present)"
53                 }
54             ],
55             "hs_codes": [
56                 {
57                     "code": "520932",
58                     "description": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, 3-thread or 4-thread twill, including cross twill, weighing more than 200g/m2"
59                 },
60                 {
61                     "code": "52093200",
62                     "description": "Vải vân chéo 3 sợi hoặc vân chéo 4 sợi, kể cả vải vân chéo dấu nhân"
63                 }
64             ],
65             "product_descriptions": [
66                 "Vải dệt thoi từ bông có tỷ trọng từ 85% trở lên, đã nhuộm, vân chéo 87/12/1% CO/PA/CARB khổ 153 cm 310G - Hàng mới 100%, dùng trong ngành may , Cotton woven fabric by weight 85% or more, dyed, twill 87/12/1% CO/PA/CARB 153 cm 310G - 100% brand new, used in garment industry"
67             ],
68             "record": "e5de7b52cc88ef4cd1a10e201bdf46ee/{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}/1690329600000/0"
69         },

Congratulations! This concludes our Trade Search - Shipments 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.

Introduction

This guide covers the Shipments endpoint.

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

Shipment 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 - Suppliers & Buyers to demonstrate how these endpoints differ.

1 POST https://api.sayari.com/v1/trade/search/shipments
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

Supplier Risk: Counts of specific risk factors associated with suppliers, based on our risk factor ontology

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

Buyer Risk: Counts of specific risk factors associated with buyers, based on our risk factor ontology

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

Departure Country: Shipment counts summarized by their departure country

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

Arrival Country: Shipment counts summarized by their arrival country

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

Top Suppliers: Identifies top suppliers by shipment count

1 "top_suppliers": [
2 {
3 "key": "4f5tF_6i3dFFvr4lDIrGAQ",
4 "doc_count": 3388
5 },

Top Buyers: Identifies top buyers by shipment count

1 "top_buyers": [
2 {
3 "key": "o2C-58vBszngTbUVbWJvww",
4 "doc_count": 1615
5 },

HS Code: Summarizes shipments by Harmonized System codes, offering both detailed and simplified descriptions

1 "hs_code": [
2 {
3 "key": "520939",
4 "doc_count": 2630,
5 "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",
6 "value_simple": "Heavy major cotton fabrics"
7 },

Source: Counts and summarizes shipments according to the underlying data sources

1 "source": [
2 {
3 "key": "e5de7b52cc88ef4cd1a10e201bdf46ee",
4 "doc_count": 28644
5 },

Understanding the Shipment Object

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

Each shipment object in the response provides detailed information:

data: An array of shipment hits
data[].id: The Sayari entity ID
data[].type: Always shipment, indicating the entity type
data[].arrival_date & departure_date: Key dates indicating when the shipment arrived and departed
data[].monetary_value & weight: The financial value and weight of the shipment, respectively
data[].supplier & buyer: Includes IDs, names, risk factors, associated countries, and business purposes for both buyers and suppliers
data[].identifier: Unique identifiers for the shipment, aiding in tracking and referencing
data[].sources: Data source ID and label, crucial for verification and reliability assessments
data[].hs_codes: Detailed Harmonized System codes and descriptions for the goods being shipped
data[].product_descriptions: Commercial descriptions of the goods being shipped
data[].record: The underlying record. Use this value as the id to query the Record endpoint.

1 "data": [
2         {
3             "id": "3WBjyrwq_91w7_IRgWKJyg",
4             "type": "shipment",
5             "buyer": [
6                 {
7                     "id": "CA4CHQMukcdQ03z-ij8qqA",
8                     "names": [
9                         "CôNG TY TNHH THIếT Kế PHụ KIệN THờI TRANG VIệT NAM",
10                         "VIET NAM STYLE FASHION ACCESSORIES COMPANY LIMITED",
11                         "VN STYLE FASHION ACCESSORIES CO.,LTD"
12                     ],
13                     "risks": {
14                         "basel_aml": 7.1,
15                         "cpi_score": 39
16                     },
17                     "countries": [
18                         "VNM"
19                     ],
20                     "business_purpose": []
21                 }
22             ],
23             "supplier": [
24                 {
25                     "id": "g39mBNjuFwXDncovHHfwFA",
26                     "names": [
27                         "HEDERA INTERNATIONAL TRADING LIMITED/SHANGHAI STYLE FASHION ACCESSORIE"
28                     ],
29                     "risks": {
30                         "basel_aml": 6.81,
31                         "cpi_score": 45
32                     },
33                     "countries": [
34                         "CHN"
35                     ],
36                     "business_purpose": []
37                 }
38             ],
39             "arrival_date": "2023-05-25",
40             "departure_date": "2023-05",
41             "monetary_value": [],
42             "weight": [],
43             "identifier": [
44                 {
45                     "value": "{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}",
46                     "type": "global_trade_internal_shipment_id"
47                 }
48             ],
49             "sources": [
50                 {
51                     "id": "e5de7b52cc88ef4cd1a10e201bdf46ee",
52                     "label": "Vietnam Imports & Exports (January 2023 - Present)"
53                 }
54             ],
55             "hs_codes": [
56                 {
57                     "code": "520932",
58                     "description": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, 3-thread or 4-thread twill, including cross twill, weighing more than 200g/m2"
59                 },
60                 {
61                     "code": "52093200",
62                     "description": "Vải vân chéo 3 sợi hoặc vân chéo 4 sợi, kể cả vải vân chéo dấu nhân"
63                 }
64             ],
65             "product_descriptions": [
66                 "Vải dệt thoi từ bông có tỷ trọng từ 85% trở lên, đã nhuộm, vân chéo 87/12/1% CO/PA/CARB khổ 153 cm 310G - Hàng mới 100%, dùng trong ngành may , Cotton woven fabric by weight 85% or more, dyed, twill 87/12/1% CO/PA/CARB 153 cm 310G - 100% brand new, used in garment industry"
67             ],
68             "record": "e5de7b52cc88ef4cd1a10e201bdf46ee/{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}/1690329600000/0"
69         },

Trade Search - Shipments

Trade Search - Shipments

Introduction

Shipment Request

Response Review

Understanding Facets

Understanding the Shipment Object

Introduction

Shipment Request

Response Review

Understanding Facets

Understanding the Shipment Object

1	POST https://api.sayari.com/v1/trade/search/shipments
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	}

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

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

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

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

1	"top_suppliers": [
2	{
3	"key": "4f5tF_6i3dFFvr4lDIrGAQ",
4	"doc_count": 3388
5	},

1	"top_buyers": [
2	{
3	"key": "o2C-58vBszngTbUVbWJvww",
4	"doc_count": 1615
5	},

1	"hs_code": [
2	{
3	"key": "520939",
4	"doc_count": 2630,
5	"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",
6	"value_simple": "Heavy major cotton fabrics"
7	},

1	"source": [
2	{
3	"key": "e5de7b52cc88ef4cd1a10e201bdf46ee",
4	"doc_count": 28644
5	},

1	"data": [
2	{
3	"id": "3WBjyrwq_91w7_IRgWKJyg",
4	"type": "shipment",
5	"buyer": [
6	{
7	"id": "CA4CHQMukcdQ03z-ij8qqA",
8	"names": [
9	"CôNG TY TNHH THIếT Kế PHụ KIệN THờI TRANG VIệT NAM",
10	"VIET NAM STYLE FASHION ACCESSORIES COMPANY LIMITED",
11	"VN STYLE FASHION ACCESSORIES CO.,LTD"
12	],
13	"risks": {
14	"basel_aml": 7.1,
15	"cpi_score": 39
16	},
17	"countries": [
18	"VNM"
19	],
20	"business_purpose": []
21	}
22	],
23	"supplier": [
24	{
25	"id": "g39mBNjuFwXDncovHHfwFA",
26	"names": [
27	"HEDERA INTERNATIONAL TRADING LIMITED/SHANGHAI STYLE FASHION ACCESSORIE"
28	],
29	"risks": {
30	"basel_aml": 6.81,
31	"cpi_score": 45
32	},
33	"countries": [
34	"CHN"
35	],
36	"business_purpose": []
37	}
38	],
39	"arrival_date": "2023-05-25",
40	"departure_date": "2023-05",
41	"monetary_value": [],
42	"weight": [],
43	"identifier": [
44	{
45	"value": "{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}",
46	"type": "global_trade_internal_shipment_id"
47	}
48	],
49	"sources": [
50	{
51	"id": "e5de7b52cc88ef4cd1a10e201bdf46ee",
52	"label": "Vietnam Imports & Exports (January 2023 - Present)"
53	}
54	],
55	"hs_codes": [
56	{
57	"code": "520932",
58	"description": "Fabrics, woven; containing 85% or more by weight of cotton, dyed, 3-thread or 4-thread twill, including cross twill, weighing more than 200g/m2"
59	},
60	{
61	"code": "52093200",
62	"description": "Vải vân chéo 3 sợi hoặc vân chéo 4 sợi, kể cả vải vân chéo dấu nhân"
63	}
64	],
65	"product_descriptions": [
66	"Vải dệt thoi từ bông có tỷ trọng từ 85% trở lên, đã nhuộm, vân chéo 87/12/1% CO/PA/CARB khổ 153 cm 310G - Hàng mới 100%, dùng trong ngành may , Cotton woven fabric by weight 85% or more, dyed, twill 87/12/1% CO/PA/CARB 153 cm 310G - 100% brand new, used in garment industry"
67	],
68	"record": "e5de7b52cc88ef4cd1a10e201bdf46ee/{3A5E9D6D-CE63-4574-8C3A6C4A1778082C}/1690329600000/0"
69	},