Request Library
Below is a quick reference of the sample API Requests that are found throughout this documentation.
Parameters such as query and filters operate across all endpoints,
while others are endpoint specific. Please reference the related source pages for more instruction.
In this example we are first sorting for shipments that have the smallest weight, followed by a sort to organize them by highest of estimated USD Value. source: retrieving-records-shipments
{
"data_source": "global",
"sort": [
{
"field": "weight_kg",
"order": "asc"
}, {
"field": "value_usd",
"order": "desc"
}
]
}
Find Shipments that contain any footwear terms in either the shipper's name, the consignee's name, or the shipment's item descriptions. source: data-selection-queries
{
"data_source": "global",
"query": {
"text": "shoes footwear boots heels sneakers"
}
}
Find Shipments that contain any footwear terms only in the shipment's descriptions. source: data-selection-queries
{
"data_source": "global",
"query": {
"text": "shoes footwear boots heels sneakers".
"group": "goods_described"
}
}
Find shipments that contain all three terms of sneakers, white, track, regardless of where those terms are present on the shipment record. source: data-selection-queries
{
"data_source": "global",
"query": {
"text": "sneakers white track",
"operator": "AND
}
}
Find shipments that contain all three terms of high heel shoes sequentially source: data-selection-queries
{
"data_source": "global",
"query": {
"text": "\"high heel shoes\"",
}
}
Find shipments that contain exactly shoes, along with either high heel or heel. source: data-selection-queries
{
"data_source": "global",
"query": {
"text": "(\"high heel\" | heel) +shoes",
"match": "exact"
}}
Find shipments that contain shoes in the description, and footwear in either the shipper's name or industry source: data-selection-queries
{
"data_source": "global",
"queries": [
{
"text": "shoes",
"group": "goods_described"
}, {
"text": "footwear",
"custom_group": ["shipper_name", "shipper_industry"]
}
]
}
Using this single filter, only shipments that originate from the United States will be matched. source: data-selection-filters
{
"data_source": "global",
"filters": {
"origin_countries": "United States"
}
}
Using this set filter, shipments that have either a destination of Germany or France will be matched. source: data-selection-filters
{
"data_source": "global",
"filters": {
"destination_countries": [ "Germany", "France" ]
}
}
Using this existence filter, only shipments that have an associated shipper and a defined shipper's name will be matched. source: data-selection-filters
{
"data_source": "global",
"filters": {
"shipper_name": "*"
}
}
Using this range filter, shipments that are together between 10-20 KG and dating from the first half of 2023 will be matched. source: data-selection-filters
{
"data_source": "global",
"filters": {
// Only shipments that have a weight greater than 10 KG and less than or equal to 20 KG
"weight_kg": {
"gt": 10,
"lte": 20
},
// Only shipments that are on or after January 25th, 2023, but before July 1st, 2023.
"record_date": {
"gte": "2023-01-25",
"lt": "2023-07-01"
},
}
}
Define a circular region by providing both a center point and a radial distance. source: data-selection-filters
{
"data_source": "global",
"filters": {
"consignee_lat_long": {
"lat_long": ["34.0200393", "-118.741368"],
"distance": "300km"
}
}
}
Define a rectangular region by providing both a top-left and bottom-right corner points. source: data-selection-filters
{
"data_source": "global",
"filters": {
"consignee_lat_long": {
"top_left": ["34.0200393", "-118.741368"],
"bottom_right": "300km"
}
}
}
In this example, we are searching for shipments that either have a weight greater than 20KG or an estimated value greater of $5,000, that are destined for the United States, and are being unloaded at a port which is not located on the west-coast. source: data-selection-filters
{
"data_source": "global",
"filters": {
"AND": {
"destination_countries": "United States"
},
"OR": [{
"weight_kg": {
"gt": 20
}
}, {
"value_usd": {
"gt": 5000
}
}],
"NOT": {
"port_unlading_coast": "west"
}
}
}
In this example, we are finding shipments that originate from the United Kingdom, and are destined for Canada. source: data-selection-examples-countries
{
"data_source": "global",
"filters": {
"origin_countries": "United Kingdom",
"destination_countries": "Canada"
}
}
In this example, we are finding shipments that originate from a port within the United Kingdom, and are to be offloaded at a port in Canada. source: data-selection-examples-countries
{
"data_source": "global",
"filters": {
"port_lading_country": "United Kingdom",
"port_unlading_country": "Canada"
}
}
In this example, we are only selecting shipment records that originate from import records to the United States. source: data-selection-examples-countries
{
"data_source": "us-imports"
}
In this example, we are using the global data-source but selecting shipment records that originate from import shipping records to Mexico. source: data-selection-examples-countries
{
"data_source": "global"
"filters": {
"data_source": "MexicoShipmentImport"
}
}
Within the query parameter, the goods_described group specifically targets both the description of the shipment's contents, along with any alphanumeric markings found on the shipping container itself. source: data-selection-examples-shipments
{
"data_source": "global",
"query": {
"group": ["goods_described"]
"text": "clothing"
}
}
Use a custom_group with just the commodity_description field specified source: data-selection-examples-shipments
{
"data_source": "global",
"query": {
"custom_group": ["commodity_description"]
"text": "clothing"
}
}
In this example we are trying to find all shipments for a company with ccn_id of 12345, regardless if the company is the shipper or the receiver. source: data-selection-examples-companies
{
"data_source": "global",
"filters": {
"OR": [{
"shipper_ccn_id": 12345
}, {
"consignee_ccn_id": 12345
}]
}
}
In this example, we are selecting all shipments where the term electric is present in the consignee business name. source: data-selection-examples-companies
{
"data_source": "global",
"query": {
"group": "consignee_name",
"text": "electric"
}
}
In this example, we are selecting for all shipments where the shipper has an estimated more than 1,000 employees. source: data-selection-examples-companies
{
"data_source": "global",
"filters": {
"shipper_employee_count": {
"gte": 1000
}
}
}
This will roll-up a set of matching records first by destination port country (returning the top 20, in descending order by the sum of the total weight of a given bucket's records), then by port of unlading (returning the top 5, in descending order by record count): source: analytics-aggregation-rollups
{
"data_source": "global",
"dimensions": [{
"field": "port_unlading_country",
"size": 20,
"offset": 20,
"sort": {
"key": "weight_kg",
"op": "sum"
"order": "desc"
}, {
"field": "port_unlading_name",
"size": 5,
"sort": {
"key": "count",
"order": "desc"
}
}
}],
"metrics": [{
"metric": "weight_kg",
"op": "sum"
}]
}
In this example, the count of shipment records, along with the total USD Value, is calculated for all shipments destined for the United States. The results are then bucketed by each month in 2020. source: analytics-aggregation-timeseries
{
"data_source": "global",
"filters": {
"shipment_destinations": "United States"
},
// time series parameters
"min_date": "2020-01-01",
"max_date": "2020-12-31",
"interval": "month",
// metrics may be additionally specified and will be
// calculated for each time-interval as well
"metrics": [
{ "metric": "value_usd", op: "sum" }
]
}
In this example, for shipments that contain clothing, find the top origin countries, destination countries, and unlading ports. source: analytics-aggregation-refinements
{
"data_source": "global",
"query": {
"text": "clothing"
},
"fields": ["destination_countries", "origin_countries", "port_unlading_name"]
}
The following request selects for all shipments destined for the United States in January 2023, and calculates the total USD Value of all shipments, the largest volume shipment present, and the average weight of all the shipments. source: analytics-aggregation-metrics
{
"data_source": "global",
"filters": {
"shipment_destinations": "United States",
"record_date": {
"gte": "2023-01-01",
"lt": "2023-02-01"
}
}
"metrics": [
{ "metric": "value_usd", op: "sum" },
{ "metric": "volume_teu", op: "max" },
{ "metric": "weight_kg", op: "avg" },
]
}
Example API Request for the Shipment Search endpoint. source: Shipment Search
{
"data_source": "global",
"size": 100,
"offset": 500,
"query": {
"text": "clothing shoes footwear",
"group": "goods_described",
"matching": "exact",
"operator": "AND"
},
"filters": {
"AND": {
"record_date": {
"gte": "2020-01-01"
}
},
"NOT": {
"origin_countries": [
"France",
"Spain"
]
},
"OR": [
{
"destination_countries": [
"United States",
"Canada"
]
},
{
"port_unlading_country": [
"United States",
"Canada"
]
}
]
},
"metrics": [
{
"metric": "value_usd",
"op": "sum"
}
],
"sort": [
{
"field": "record_date",
"order": "asc"
}
]
}
Example API Request for the Shipment Refinements endpoint. source: Shipment Refinements
{
"data_source": "global",
"query": {
"text": "clothing"
},
"filters": {
"record_date": {
"gte": "2020-01-01"
}
},
"fields": [
"destination_countries",
"origin_countries"
]
}
Example API Request for the Shipment Time-Series endpoint. source: Shipment Time-Series
{
"data_source": "global",
"query": {
"text": "clothing"
},
"filters": {
"destination_countries": "United States"
},
"metrics": [
{
"metric": "weight_kg",
"op": "avg"
}
],
"interval": "month",
"min_date": "2020-01-01",
"max_date": "2022-01-01"
}
Example API Request for the Shipment Rollup endpoint. source: Shipment Rollup
{
"data_source": "global",
"query": {
"text": "clothing"
},
"filters": {
"destination_countries": "United States"
},
"metrics": [
{
"metric": "weight_kg",
"op": "sum"
}
],
"time_series": {
"interval": "month",
"min_date": "2020-01-01",
"max_date": "2022-01-01"
},
"dimensions": [
{
"field": "port_unlading_country",
"size": 20,
"offset": 10,
"sort": {
"key": "weight_kg",
"op": "sum",
"order": "desc"
}
},
{
"field": "port_unlading_name",
"size": 10,
"sort": {
"key": "count",
"op": "sum",
"order": "desc"
}
}
]
}
Example API Request for the Company Search endpoint. source: Company Search
{
"size": 1000,
"company_type": "country_company_name",
"direction": "bidirectional",
"query": {
"text": "clothing"
},
"filters": {
"destination_countries": "United States"
},
"metrics": [
{
"metric": "weight_kg",
"op": "sum"
}
],
"sort": {
"key": "weight_kg",
"op": "sum",
"order": "desc"
}
}
Example API Request for the Company Rollup endpoint. source: Company Rollup
{
"company_type": "country_company_name",
"company_ids": [
89172432,
85220344,
89458782
],
"direction": "bidirectional",
"query": {
"text": "clothing"
},
"filters": {
"destination_countries": "United States"
},
"metrics": [
{
"metric": "weight_kg",
"op": "sum"
}
],
"dimensions": [
{
"field": "port_unlading_country",
"size": 20,
"offset": 10,
"sort": {
"key": "weight_kg",
"op": "sum",
"order": "desc"
}
},
{
"field": "port_unlading_name",
"size": 10,
"sort": {
"key": "count",
"op": "sum",
"order": "desc"
}
}
]
}
Example API Request for the Company Network endpoint. source: Company Network
{
"company_id": 89172432,
"company_type": "country_company_name",
"size": 1000,
"query": {
"text": "clothing"
},
"filters": {
"destination_countries": "United States"
},
"metrics": [
{
"metric": "weight_kg",
"op": "sum"
}
],
"sort": {
"key": "weight_kg",
"op": "sum",
"order": "desc"
},
"direction": "bidirectional"
}
Example API Request for the Company Lookup endpoint. source: Company Lookup
{
"company_id": 89172432,
"company_ids": [
89172433,
89172434,
89172435
],
"company_type": "country_company_name"
}