Skip to main content

Free Text Search

The parameter query allows for free-text searching across data-points on the shipment records. A query consists of three parts:

  1. Text content (what to search for)
  2. Target Fields (where to look)
  3. Searching Logic (how to search)

Text Content​

This is the actual text content that is used to search against the data in the shipment records. This is specified in the query.text parameter.

Target Fields​

These are the unique data-points (or fields) on each shipment record that will be evaluated against the provided text content. There are two ways to provide the target fields for a query, by specifying either:

  1. A pre-defined group of fields by using the query.group parameter.
  2. A custom set of fields by using the query.custom_group parameter.
tip

Depending on the use case at hand some fields may be substantially more desirable than other. For example, if only the contents of the shipment are in question, using the group goods_described will remove results where the shipper's name may contain the search term.

Searching Logic​

By default, any individual word in the provided search content may match the shipment record to qualify as a hit. Also, only the root of the provided word must match.

For example, a search for purple shoes may return shipments for both purple paint and track shoe.

The search logic may be tailored further with three additional settings:

  1. ALL terms must match if query.operator is set to AND
  2. Provided terms must match exactly (shoes will not match shoe) if query.match is set to exact
  3. Multiple Queries may be provided using the queries parameter. Note: Every query must match the record
  4. Joins, Exclusions, Groups, Phrases and more are available using inline operators as further described in the schema below.

Query Examples​

Let's take a look at a few different ways that query can be used to search for footwear within shipments, ranging broad searches to more precise.

Search Broadly Across All Record Fields

Find Shipments that contain any footwear terms in either the shipper's name, the consignee's name, or the shipment's item descriptions.

{
  "data_source": "global",
  "query": {
      "text": "shoes footwear boots heels sneakers"
  }
}
Search only Shipment Descriptions

Find Shipments that contain any footwear terms only in the shipment's descriptions.

{
  "data_source": "global",
  "query": {
    "text": "shoes footwear boots heels sneakers".
    "group": "goods_described"
  }
}
Every search term must match

Find shipments that contain all three terms of sneakers, white, track, regardless of where those terms are present on the shipment record.

{
  "data_source": "global",
  "query": {
    "text": "sneakers white track",
    "operator": "AND
  }
}
Matching an entire phrase

Find shipments that contain all three terms of high heel shoes sequentially

{
  "data_source": "global",
  "query": {
      "text": "\"high heel shoes\"",
  }
}
Using Inline Operators and Exact Term Matching

Find shipments that contain exactly shoes, along with either high heel or heel.

{
"data_source": "global",
"query": {
    "text": "(\"high heel\" | heel) +shoes",
    "match": "exact"
}}
note

Since match: "exact" is specified, shoe, heels, heeled, or other variations of the provided term will not qualify as a match.

Using Multiple Queries and Custom Groups

Find shipments that contain shoes in the description, and footwear in either the shipper's name or industry

{
  "data_source": "global",
  "queries": [
    {
      "text": "shoes",
      "group": "goods_described"
    }, {
      "text": "footwear",
      "custom_group": ["shipper_name", "shipper_industry"]
    }
  ]
}

Query Schema​

Selected Data-Source
string

Choose the desired data-source to view the available fields

text
required
string

The actual textual content to search for.

This parameter accepts the following inline operators that allow for more complex logic when querying:

Operator Definition
+ Joins multiple terms with an AND operation
| Separates multiple terms with an OR operation
- Negates a single term
"..." Wraps a number of tokens to construct a phrase for searching
* Implies a prefix query when used at at the end of a term
(...) Used to construct logical precedence

Note that behavior of these inline operators may change based on the default operator specified in the operator parameter. When specifying an operator of OR, it may be necessary to include + ahead of specific terms to join them with all other terms in the query. When specifying an operator of AND, it may be necessary to include | ahead of specific terms to separate them from other terms in the query.

group
string
Default: "main"
Enum: "bill_of_lading" "consignee_name" "consignee_address" "consignee_industry" "shipper_name" "shipper_address" "shipper_industry" "goods_described" "hs_codes" "carrier" "port_lading" "port_unlading" "port_destination" "consignee_company_data" "shipper_company_data" "main" "product_data" "company_data" "port_data"

Represents the collection of fields that will be searched.

custom_group
Array of strings
Items Enum: "bol_number" "master_bol_number" "container_numbers" "consignee_name" "consignee_alt_names" "consignee_original_name" "consignee_full_address" "consignee_original_address" "consignee_simple_industry" "shipper_name" "shipper_alt_names" "shipper_original_name" "shipper_full_address" "shipper_original_address" "shipper_simple_industry" "commodity_description" "marks_description" "hs_codes_2" "hs_codes_4" "hs_codes_6" "hs_codes_8" "hs_codes_10" "transporter_name" "port_lading_alt_names" "port_unlading_alt_names" "port_destination_alt_names" "consignee_name" "consignee_alt_names" "consignee_original_name" "consignee_full_address" "consignee_original_address" "consignee_simple_industry" "shipper_name" "shipper_alt_names" "shipper_original_name" "shipper_full_address" "shipper_original_address" "shipper_simple_industry" "bol_number" "master_bol_number" "container_numbers" "consignee_name" "consignee_alt_names" "consignee_original_name" "consignee_full_address" "consignee_original_address" "shipper_name" "shipper_alt_names" "shipper_original_name" "shipper_full_address" "shipper_original_address" "commodity_description" "marks_description" "hs_codes_2" "hs_codes_4" "hs_codes_6" "hs_codes_8" "hs_codes_10" "commodity_description" "marks_description" "hs_codes_2" "hs_codes_4" "hs_codes_6" "hs_codes_8" "hs_codes_10" "consignee_name" "consignee_alt_names" "consignee_original_name" "consignee_full_address" "consignee_original_address" "consignee_simple_industry" "shipper_name" "shipper_alt_names" "shipper_original_name" "shipper_full_address" "shipper_original_address" "shipper_simple_industry" "transporter_name" "port_lading_alt_names" "port_unlading_alt_names" "port_destination_alt_names"

For explicitly specifying what fields to search over.

operator
string
Default: "OR"
Enum: "AND" "OR"

This represents the boolean logic applied to the terms in the query text.

More specifically, with 'OR' the presence of only one term is required for a given record to match the search – conversely, 'AND' would require all terms in the query text to be present in some form across the fields specified by the group parameter.

match
string
Default: "stem"
Enum: "stem" "exact"

The logic used to match the text query against the record fields stem means that the root of english words are used to match. 'exact' means that only record fields that match the exact term will be selected.