Rollups

Rollup endpoints categorize records against the top values of specific fields up to 3 separate times. The dimensions parameter is used to define the rollup, with each dimension object describing the characteristics of each individual aggregation.

Calculating Top Values

Along with the target field, each dimension must specify the sort method to apply during aggregation. Two sorting methods are always available:

• count - The number of times each unique value of the field appears.
• field - Alphanumeric ordering of the total unique set of values of the specified field.

info

The available sorting methods are data-source specific. Please review the dimensions schema below with a selected data-source to review the options.

tip

If any unique sorting methods outside of count or field are used, then those methods must also be defined within the metrics parameter as well.

Sort Order and Operation

Each sort must specify which statistical operation is used when aggregating the selected records, such as summing all values together to form a total. Then, the direction of the sort should be specified as either ascending or descending.

Missing Values

Often times there will exist shipment records that have no value for the field specified in the aggregation. Unless include_missing: true is specified on the dimension, these shipments will be excluded from the results.

note

The aggregate missing values will show up within the results array with a value of NO_VALUE.

Pagination

A maximum of 100 results may be returned for each dimension during a single request, however the results for the first dimension may be paginated further by specifying an offset with the offset parameter.

info

The combined value of the size and offset parameters may not exceed the upper limit of 1,000 results.

Multiple Dimensions

Multiple dimensions can be specified to allow for a multi-level aggregation of the selected records.

Order Matters

Aggregation happens successively, depending on the order that the dimensions are defined in the array. An incorrect order will return results that are markedly different than the intended analysis.

Dimensions Example

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):

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

tip

Rollups against shipments may additionally be categorized against a provided time series

Dimension 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
field	string Enum: "data_source" "record_id" "trade_direction" "transport_type" "bol_number" "master_bol_number" "bol_type" "financial_countries" "origin_countries" "destination_countries" "container_numbers" "container_parsed_codes" "shipment_month" "shipment_year" "hs_codes_2" "hs_codes_4" "hs_codes_6" "hs_codes_8" "hs_codes_10" "gics_code" "scac" "us_export_type" "port_lading_name" "port_lading_country" "port_lading_un_locode" "port_lading_coast" "port_unlading_name" "port_unlading_country" "port_unlading_un_locode" "port_unlading_coast" "port_destination_name" "port_destination_country" "port_destination_un_locode" "consignee_jc_id" "consignee_pid" "consignee_agg_pid" "consignee_bidirectional_trade" "consignee_ccn_id" "consignee_capiq_id" "consignee_ultimate_parent_capiq_id" "consignee_name" "consignee_tax_number" "consignee_country" "consignee_region" "consignee_region_2" "consignee_region_3" "consignee_postal_code" "consignee_country_region" "consignee_stock_exchange_symbol" "consignee_ultimate_parent_stock_exchange_symbol" "consignee_simple_industry" "consignee_sic_codes" "consignee_trade_roles" "consignee_duns_number" "consignee_data_available" "shipper_jc_id" "shipper_pid" "shipper_agg_pid" "shipper_bidirectional_trade" "shipper_ccn_id" "shipper_capiq_id" "shipper_ultimate_parent_capiq_id" "shipper_name" "shipper_tax_number" "shipper_country" "shipper_region" "shipper_region_2" "shipper_region_3" "shipper_postal_code" "shipper_country_region" "shipper_stock_exchange_symbol" "shipper_ultimate_parent_stock_exchange_symbol" "shipper_simple_industry" "shipper_sic_codes" "shipper_trade_roles" "shipper_duns_number" "shipper_data_available"
size	integer [ 0 .. 100 ] Default: 10
offset	integer [ 0 .. 999 ] Default: 0 Note: The offset is only valid on the first dimension
include_missing	boolean Default: false Include missing values within the aggregation. Note: The missing values will return NO_VALUE in the results array
	object