Filtering Results

The parameter filters allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints. This is similar in concept to using a WHERE clause in an SQL query.

What are the available filters?

Each data-source has its own set of attributes which are available as filters. Review the schema down below with the chosen data-source to view the available filter attributes and their corresponding type.

Filter Types

Each available filter is representative of an underlying data-point on a shipment record. As such, each underlying data-point (and its corresponding filter, if present) has a specific data-type.

The specific data-type dictates which filter constraints may be used to evaluate the underlying data-point. Listed below are the different data-types that filters will fall under, along with the corresponding constraints that are available for that data-type.

Filter Type	Single	Set	Existence	Range	Geography
String	✅	✅	✅
Numeric	✅	✅	✅	✅
Date	✅	✅	✅	✅
Boolean	✅		✅
Geo Point			✅		✅

Filter Constraints

Constraint Type	Definition
Single	The specified record field must match this single value
Set	The specified record field must match at least one value in the provided set
Existence	The specified field must have any non-null value
Range	The specified field must have a value within the provided range
Geography	The specified field's geographical point must exist within the bounding region provided

Constraint Details and Examples

Single

Using this single filter, only shipments that originate from the United States will be matched.

{
  "data_source": "global",
  "filters": {
    "origin_countries": "United States"
  }
}

Set

Using this set filter, shipments that have either a destination of Germany or France will be matched.

{
  "data_source": "global",
  "filters": {
    "destination_countries": [ "Germany", "France" ]
  }
}

Existence

Using this existence filter, only shipments that have an associated shipper and a defined shipper's name will be matched.

{
  "data_source": "global",
  "filters": {
    "shipper_name": "*"
  }
}

Range

The possible range operators are:

• Less-than: lt
• Less-than-or-equal-to: lte
• Greater-than: gt
• Greater-than-or-equal-to: gte

info

Date constraints must be specified in the format of YYYY-MM-DD

Using this range filter, shipments that are together between 10-20 KG and dating from the first half of 2023 will be matched.

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

Geography

The bounding region for a geographical constraint may be specified in a number of ways, as described below.

Distance from a Point

Define a circular region by providing both a center point and a radial distance.

{
  "data_source": "global",
  "filters": {
    "consignee_lat_long": {
      "lat_long": ["34.0200393", "-118.741368"],
      "distance": "300km"
    }
  }
}

distance	string Available units are miles (mi), yards (yd), feet (ft), inch (in), kilometers (km), meters (m), centimeters (cm), millimeters (mm), nauticalmiles (nmi)
lat_long	Array of numbers = 2 items This is the center point as defined by a lat long pair in array format

Bounding Box

Define a rectangular region by providing both a top-left and bottom-right corner points.

{
  "data_source": "global",
  "filters": {
    "consignee_lat_long": {
      "top_left": ["34.0200393", "-118.741368"],
      "bottom_right": "300km"
    }
  }
}

top_left	Array of numbers = 2 items This is the top-left point of the rectangle as defined by a lat long pair in array format
bottom_right	Array of numbers = 2 items This is the bottom_right point of the rectangle as defined by a lat long pair in array format

Custom Shape

Define a shape that conforms to the GeoJson Specification.

tip

GeoJson.io is a helpful mapping tool that generates GeoJson compatible shapes.

Any of

relation	string Default: "intersects" Enum: "intersects" "disjoint" "within" "contains"
shape	string Value: "point"
coordinates	Array of numbers = 2 items This is the center point as defined by a lat long pair in array format

Using Multiple Filters

By default, all filters specified as properties on the base filter object must match in order for a shipment record to be returned. However, filters may be placed into separate groups that dictate how the underlying shipment record is selected during its evaluation against the filter criteria. The available filter groups are described below.

Filter Group	Definition
AND	All filter criteria defined in this group must match the shipment record
NOT	None of the filter criteria defined in this group must match the shipment record
OR	One of the filter groups defined in this array must match the shipment record

info

Every filter group must match in order for a record to be selected. This means that every filter in the AND group must match, every filter in the NOT group must not match, and at least one set of filters in the OR group must match, in order for a record to qualify.

Multiple Filter Example

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.

{
  "data_source": "global",
  "filters": {
    "AND": {
      "destination_countries": "United States"
    },
    "OR": [{
      "weight_kg": {
        "gt": 20
      }
    }, {
    "value_usd": {
        "gt": 5000
      }
    }],
    "NOT": {
      "port_unlading_coast": "west"
    }
  }
}

Filter Schema

Selected Data-Source	string Choose the desired data-source to view the available fields globalus-importsus-exportsbol-import-itemsbol-export-itemsbol-importsbol-exportsbra-importsbra-exportschn-importschn-exportschl-importschl-exportschl-import-itemscol-importscol-exportscri-importscri-exportscri-import-itemscri-export-itemsecu-importsecu-exportsidn-importsidn-exportsind-importsind-exportsind-import-itemsind-export-itemslka-importslka-exportsmex-importsmex-exportsmex-import-itemsmex-export-itemspak-importspak-exportspan-importspan-exportsper-importsper-exportsphl-importsphl-exportspry-importspry-exportstur-importstur-exportstur-import-itemstur-export-itemsury-importsury-exportsven-importsven-exportsvnm-importsvnm-exportsrussiaukraineuzbekistankazakhstanvietnam-chinaphilippinesethiopiaglobal
	Array of objects >= 2 items
	object
	object
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	object or Existence (string) This field is of type date.
	object or Existence (string) This field is of type date.
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	boolean or Array of booleans or Existence (string) This field is of type boolean
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	object or Existence (string) This field is of type numeric
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	Existence (string) or Geo Distance (object) or Geo Distance (object) or (Geo Shape (Point (object) or Multi Point (object) or Polygon (object) or Multi Polygon (object) or Envelope (object))) This field is of type geography
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type date.
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	Existence (string) or Geo Distance (object) or Geo Distance (object) or (Geo Shape (Point (object) or Multi Point (object) or Polygon (object) or Multi Polygon (object) or Envelope (object))) This field is of type geography
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type numeric
	object or Existence (string) This field is of type date.
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string
	string or Array of strings or Existence (string) This field is of type string