Skip to main content
API docs by Redocly

Panjiva API Specification (1.0)

Shipments

Use the available Shipment endpoints to retrieve shipment records, or perform analysis over shipment records.

Shipment Search

Use this endpoint to retrieve Shipment records. Review the available Shipment Search documentation for details on sorting shipments. Additionally, review the Shipment Schema to understand the common attributes of Shipment records.

Authorizations:
auth
Request Body schema: application/json
required
data_source
required
string
offset
integer [ 0 .. 4500 ]
size
integer [ 0 .. 500 ]
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

Array of objects
Default: "record_date"

This parameter controls the order by which shipment results are organized prior to being returned.

Responses

Request samples

Content type
application/json
Example
{
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "record_count": {
    },
  • "records": [
    ],
  • "analytics": {
    }
}

Shipment Refinements

Use this endpoint to list the top-values for specific shipment record attributes. Review the available Refinement Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
data_source
required
string
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

fields
required
Array of strings
Items Enum: "data_source" "trade_direction" "transport_type" "bol_type" "financial_countries" "origin_countries" "destination_countries" "shipment_month" "shipment_year" "gics_code" "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_country" "consignee_region" "consignee_region_2" "consignee_region_3" "consignee_simple_industry" "consignee_trade_roles" "consignee_data_available" "shipper_country" "shipper_region" "shipper_region_2" "shipper_region_3" "shipper_simple_industry" "shipper_trade_roles" "shipper_data_available"

Responses

Request samples

Content type
application/json
{
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    },
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "record_count": {
    },
  • "analytics": {
    }
}

Shipment Time-Series

Use this endpoint to calculate metrics on shipment attributes, further aggregated into specified time-series intervals. Review the available Time Series Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
data_source
required
string
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

required
Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

interval
required
string
Enum: "week" "month" "quarter" "year"
min_date
string <date>
max_date
string <date>

Responses

Request samples

Content type
application/json
{
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "interval": "month",
  • "min_date": "2020-01-01",
  • "max_date": "2022-01-01"
}

Response samples

Content type
application/json
{
  • "record_count": {
    },
  • "analytics": {
    }
}

Shipment Rollup

Use this endpoint to categorize records against the top values of specific attributes up to 3 separate times. Rollups are complex operations, please review the available Rollup Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
data_source
required
string
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

object

This parameter aggregates the entire set of shipment results for which the provided criteria matches, bounded by the start and end date provided and bucketed by the interval specified. Please review the available Time Series Documentation to learn more.

required
Array of objects [ 1 .. 3 ] items

This parameter allows for the categorization of records against the top values of specific fields up to 3 separate times. The dimensions parameter is complex, please review the Rollup Documentation to learn more.

Responses

Request samples

Content type
application/json
{
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "time_series": {
    },
  • "dimensions": [
    ]
}

Response samples

Content type
application/json
{
  • "record_count": {
    },
  • "analytics": {
    }
}

Companies

Use the available Company endpoints to retrieve company records, or perform analysis over company records such as constructing a supply-chain network.

Companies exist in different forms within Panjiva data, please refer to this documentation to review the different company entities.

Additionally, companies exist as either a shipper or receiver (consignee) of goods in relation to shipping records. As such, all company endpoints return an object with shippers and consignees.

Company Search

Use this endpoint to retrieve Company entities. Review the available Company Search documentation for details on searching and sorting results. Additionally, review the Company Schema to understand the common attributes of Company entities.

Authorizations:
auth
Request Body schema: application/json
required
size
integer [ 0 .. 5000 ]
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

object
company_type
string
Default: "country_company_name"
Enum: "ccn" "country_company_name" "pid" "capiq" "ultimate_parent_capiq"

The type of company entity specified and returned for the request. Please refer to the company entity documentation to learn more.

direction
string
Default: "bidirectional"
Enum: "bidirectional" "consignee" "shipper"

This parameter controls which trade direction the company search is performed against.

Responses

Request samples

Content type
application/json
{
  • "size": 1000,
  • "company_type": "country_company_name",
  • "direction": "bidirectional",
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "sort": {
    }
}

Response samples

Content type
application/json
{
  • "consignees": [
    ],
  • "shippers": [
    ]
}

Company Rollup

Use this endpoint to categorize company entities against the top values of specific attributes up to 3 separate times. Rollups are complex operations, please review the available Rollup Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
company_ids
Array of integers

The ids of the companies to perform the rollup analysis against.

object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

Array of objects [ 1 .. 3 ] items

This parameter allows for the categorization of records against the top values of specific fields up to 3 separate times. The dimensions parameter is complex, please review the Rollup Documentation to learn more.

company_type
string
Default: "country_company_name"
Enum: "ccn" "country_company_name" "pid" "capiq" "ultimate_parent_capiq"

The type of company entity specified and returned for the request. Please refer to the company entity documentation to learn more.

direction
string
Default: "bidirectional"
Enum: "bidirectional" "consignee" "shipper"

This parameter controls which trade direction the company search is performed against.

Responses

Request samples

Content type
application/json
{
  • "company_type": "country_company_name",
  • "company_ids": [
    ],
  • "direction": "bidirectional",
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "dimensions": [
    ]
}

Response samples

Content type
application/json
{
  • "consignees": [
    ],
  • "shippers": [
    ]
}

Company Network

Use this endpoint to find the trading partners for the specified company. The direction of the network dictates the structure of the compiled trading relationships, please review the available Company Network Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
company_id
integer

The ids of the company to perform the network analysis against.

company_type
string
Default: "country_company_name"
Enum: "ccn" "country_company_name" "pid" "capiq" "ultimate_parent_capiq"

The type of company entity specified and returned for the request. Please refer to the company entity documentation to learn more.

direction
string
Default: "bidirectional"
Enum: "bidirectional" "consignee" "shipper"

This parameter dictates the structure of the company network that is compiled.

size
integer [ 0 .. 5000 ]

This parameter controls the number of trading partners to aggregate for the provided company. Note, the second tier of the network is restricted to a limit of 100 results.

object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

object

Responses

Request samples

Content type
application/json
{
  • "company_id": 89172432,
  • "company_type": "country_company_name",
  • "size": 1000,
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "sort": {
    },
  • "direction": "bidirectional"
}

Response samples

Content type
application/json
Example
{
  • "<root-company-id>": {
    }
}

Company Lookup

Use this endpoint to retrieve company entities with provided company identifiers.

Authorizations:
auth
Request Body schema: application/json
required
company_id
integer

The ID of a singular company to lookup. Note: This will be ignored if company_ids is provided

company_ids
Array of integers
company_type
string
Default: "country_company_name"
Enum: "ccn" "country_company_name" "pid" "capiq" "ultimate_parent_capiq"

The type of company entity specified and returned for the request. Please refer to the company entity documentation to learn more.

Responses

Request samples

Content type
application/json
{
  • "company_id": 89172432,
  • "company_ids": [
    ],
  • "company_type": "country_company_name"
}

Response samples

Content type
application/json
Example
{
  • "companies": [
    ]
}

Async

Use the available Async endpoints to retrieve shipment or company records in quantities that exceed the limits of the regular shipment and company search endpoints.

Review the documentation on performing Large Searches to learn more.

Bulk Shipment Search

Use this endpoint to retrieve a large set of shipment records for a particular shipment search.

Authorizations:
auth
Request Body schema: application/json
required
output_format
string
Default: "jsonl"
Enum: "jsonl" "csv"
  • jsonl: Each search result is stored in JSON format, separated by new-lines (better for programmatic usage)
  • csv: Shared properties from the results are distributed across columns in a table format (better for manual usage)
notify_email
string

The (singular) email address to send a notification when the bulk-async job is ready for download.

Note: The download_url property returned from the status endpoint may be alternatively used to retrieve the results file location

data_source
required
string
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects
Default: "record_date"

This parameter controls the order by which shipment results are organized prior to being returned.

Responses

Request samples

Content type
application/json
{
  • "output_format": "jsonl",
  • "notify_email": "myemail@domain.com",
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Bulk Shipment Rollup

Use this endpoint to retrieve a large set of aggregated shipment values for a particular shipment search.

Authorizations:
auth
Request Body schema: application/json
required
output_format
string
Default: "jsonl"
Enum: "jsonl" "csv"
  • jsonl: Each search result is stored in JSON format, separated by new-lines (better for programmatic usage)
  • csv: Shared properties from the results are distributed across columns in a table format (better for manual usage)
notify_email
string

The (singular) email address to send a notification when the bulk-async job is ready for download.

Note: The download_url property returned from the status endpoint may be alternatively used to retrieve the results file location

data_source
required
string
object

This parameter allows for free-text searching across data-points on the shipment records. It is a complex parameter, please review the Text Search Documentation to understand its different properties and functions.

Array of objects <= 500 items

This parameter allows for distinct search terms across separate search groups.

object

This parameter allows for precise and exact matching of records by evaluating specific shipment attributes against provided constraints.

Filters may be very complex, please review the Filters Documentation to understand how to compose filters properly.

Array of objects

This parameter allows for the calculation of aggregate statistics across the entire set of selected shipments. Please review the Metric Documentation to learn more.

required
Array of objects = 1 items

This parameter allows for the categorization of records against the top values of a specific field. The dimensions parameter is complex, please review the Rollup Documentation to learn more.

Responses

Request samples

Content type
application/json
{
  • "output_format": "jsonl",
  • "notify_email": "myemail@domain.com",
  • "data_source": "global",
  • "query": {
    },
  • "filters": {
    },
  • "metrics": [
    ],
  • "dimensions": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Bulk Job Status

For all bulk-async endpoints, the "job" that is queued-up and (asynchronously) executed is assigned a unique ID which is provided in the response – this ID can subsequently be used to call the status endpoint in order to poll the given job's latest information and status.

Authorizations:
auth
path Parameters
job-id
required
string <uuid>

The ID of the job to fetch the status for

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "string",
  • "notify_email": "string",
  • "parameters": {
    },
  • "status": "submitted",
  • "last_changed": "2019-08-24T14:15:22Z",
  • "download_url": "string"
}

Batch Company Search

Use this endpoint to retrieve results for a large number of separate company searches.

Authorizations:
auth
Request Body schema: application/json
required
notify_email
string

The (singular) email address to send a notification when the bulk-async job is ready for download.

Note: The download_url property returned from the status endpoint may be alternatively used to retrieve the results file location

output_format
string
Default: "jsonl"
Enum: "jsonl" "csv"
  • jsonl: Each search result is stored in JSON format, separated by new-lines (better for programmatic usage)
  • csv: Shared properties from the results are distributed across columns in a table format (better for manual usage)
Array of objects

Responses

Request samples

Content type
application/json
{
  • "output_format": "jsonl",
  • "notify_email": "myemail@domain.com",
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Batch Job Status

Authorizations:
auth
path Parameters
job-id
required
string <uuid>

The ID of the job to fetch the status for

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "string",
  • "notify_email": "string",
  • "parameters": {
    },
  • "status": "submitted",
  • "last_changed": "2019-08-24T14:15:22Z",
  • "download_url": "string"
}

HS Code

The Harmonized System is an international standard of 2, 4, or 6-digit codes maintained by the World Customs Organization. Each country may have its own more detailed set of codes beyond that - we expose the US International Trade Commission's Harmonized Tariff Schedule, which also includes 8 & 10-digit codes.

HS Code Search

Search across known HS codes using a familiar query with some filters.

Review the available HS Code Search Documentation to learn more.

Authorizations:
auth
Request Body schema: application/json
required
offset
integer [ 0 .. 4500 ]
size
integer [ 0 .. 500 ]
required
object

Free-text search for HS Codes

Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "size": 10,
  • "query": {
    },
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "record_count": {
    },
  • "results": [
    ],
  • "analytics": {
    }
}

Metadata

Endpoints for data-source metadata

List available data sources

Use this endpoint to determine the available data-sources for your organization. Please review the available Data-Source Documentation to learn more.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "data_sources": [
    ]
}

List metadata about a specific data-source

Use this endpoint to determine the available fields for parameters such as query or filter. The available fields for these parameters are also available in the API Reference. In some cases, the desired data-source must be selected in the drop-down for the relevant fields to present themselves.

Authorizations:
auth
path Parameters
data-source
required
string
Example: global

The data source to list metadata for

Responses

Response samples

Content type
application/json
{
  • "query": {
    },
  • "filters": [
    ],
  • "sort": {
    },
  • "metrics": [
    ],
  • "dimensions": [
    ],
  • "refinements": [
    ]
}

List metadata about a specific data-source

Use this endpoint to review the exact shipment record schemas that will be returned by the Shipment Search. Common attributes on these shipment records are further described in the Shipment Schema Documentation

Authorizations:
auth
path Parameters
data-source
required
string
Example: global

The data source to list metadata for

Responses

Response samples

Content type
application/json
{
  • "<country>-<direction>": {
    }
}

Auth

Endpoints for authorization

Fetch Token Details

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Generate Token

Authorizations:
auth
Request Body schema: application/json
required
grant_type
string
Value: "client_credentials"
client_id
string
client_secret
string

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_secret": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Revoke Token

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "success": true
}