# Import Export Data API - ImportGenius Bill of Lading Shipments (`nabeelbaghoor/importgenius-bill-of-lading-shipments-api`) Actor

Search bill of lading and customs shipment records from the ImportGenius Trade Data API: importers, exporters, shippers, consignees, products, HS codes, ports and vessels across 25+ countries. Filter by field, modifier, US zip code and date range, or count matches. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/importgenius-bill-of-lading-shipments-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Lead generation, Developer tools
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 shipment record returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Import Export Data API - ImportGenius Bill of Lading Shipments

Search import and export shipment records, bills of lading and customs declarations, from the ImportGenius Trade Data API with your own access token, and get every record as a clean dataset row.

Works with the official ImportGenius Trade Data API on data.importgenius.com (GET /v2/shipments). ImportGenius covers more than 3.3 billion shipment records from customs and manifest data in 25+ countries. Search a country's imports or exports by product description, importer or consignee name, shipper name, trademark or any other search field on your plan, combine conditions with and, or and not, narrow to a date range, find US importers by zip code or zip code range, or just count the matches. Download as JSON, CSV or Excel, schedule it, or feed it into supplier discovery, competitor sourcing analysis, lead generation, brand protection, CRM enrichment, Power BI, Google Sheets and AI agents. Bring your own API key.

BYOK, not live-tested: the endpoint, parameters and query grammar come from ImportGenius's published API page (w3.importgenius.com/features/api-integration), and the /v2/shipments route was confirmed to exist on data.importgenius.com, but the actor has not been run against a live ImportGenius subscription.

### What it does

- **Field search**: searchField modifier term, exactly as the API documents it. Documented fields include product (product description), consname (US importer or consignee), shipname (shipper) and trademark; your ImportGenius integration lists the rest, and the actor accepts any of them.
- **Five match modifiers**: contains, exactly, any, starts_with and ends_with.
- **Advanced conditions**: add up to 10 extra conditions joined with and, or or not, such as "and consname contains acme" or "not product contains used".
- **Imports or exports, by country**: choose the customs dataset by its two letter code (us, vn, in, ru and the others on your plan) and the trade direction.
- **Date range**: only shipments between two dates.
- **US zip code search**: importers at one zip code or across a zip code range.
- **Count only**: one row with the number of matching shipments, to size a market or a supplier before you pull records.
- **Automatic paging**: ImportGenius returns at most 10 rows per request; the actor pages until your row ceiling, the last page or the total number of matches.
- **Every field kept**: each record keeps all the fields ImportGenius returns (for US imports these include HS code and product description, importer, consignee and shipper with addresses, notify party, arrival date, quantity, weight, foreign and US ports, vessel, voyage, bill of lading number, containers and carrier), under ImportGenius's own field names.
- **Pay only for results**: refused and empty searches are recorded as a free row that says why, never charged.

### How to get an access token

ImportGenius issues API access tokens, not self-served. API access is included with ImportGenius Enterprise (Global Enterprise) plans and is available as an upgrade on Business plans such as USA Pro, US-Mexico Pro and North America Pro. Request a demo or contact sales on importgenius.com; the implementation team configures your access, sends the token and gives you the list of search fields and country codes your plan covers. Paste the token into the Access token field. It is sent only to data.importgenius.com as the access_token parameter the API requires and is never logged.

Every API request spends credits on your ImportGenius plan (each answer reports your balance before and after), so keep Maximum results small while you test.

### Input

| Field | Description |
| --- | --- |
| `queryType` | `keyword` (field search, default), `zipCode` or `zipRange` (US only) |
| `searchField` | Field search: product (default), consname, shipname, trademark or another field on your plan |
| `modifier` | Field search: contains (default), exactly, any, starts_with, ends_with |
| `searchTerm` | Field search: the keyword, company name or brand |
| `zipCode` | US zip code search: five digits, such as 85258 |
| `zipCodeFrom`, `zipCodeTo` | US zip code range search |
| `extraConditions` | Up to 10 lines as additionType field modifier term, such as `and consname contains acme` |
| `country` | Two letter dataset code, such as us, vn, in or ru. Default us |
| `tradeType` | `im` imports (default) or `ex` exports |
| `startDate`, `endDate` | Optional date range as YYYY-MM-DD, both or neither |
| `countOnly` | Return only the number of matches |
| `maxResults` | Row ceiling for the run (default 10, one request) |
| `requestsPerMinute` | Pacing, default 30 |
| `apiKey` | Your ImportGenius access token (or the DATA_API_KEY secret) |

Example: US imports of walnuts from one shipper in the first quarter of 2026.

```json
{
    "queryType": "keyword",
    "searchField": "product",
    "modifier": "contains",
    "searchTerm": "walnuts",
    "extraConditions": ["and shipname contains farms"],
    "country": "us",
    "tradeType": "im",
    "startDate": "2026-01-01",
    "endDate": "2026-03-31",
    "maxResults": 50
}
```

This becomes the documented request `GET /v2/shipments?q=product+contains+walnuts/and+shipname+contains+farms/date+from+2026-01-01+to+2026-03-31/page+from+1+limit+10&country=us&type=im`, with the token added.

### Example output

An illustrative row. The first columns are added by the actor; after them comes every field of the record exactly as ImportGenius returns it (only three are shown, named after the documented search fields). Values are an example only, not real data, and ImportGenius does not publish its row schema.

```json
{
    "recordType": "shipment",
    "country": "us",
    "tradeType": "im",
    "query": "product contains walnuts/page from 1 limit 10",
    "page": 1,
    "position": 1,
    "totalMatches": 1843,
    "dateFrom": "2026-01-01",
    "dateTo": "2026-03-31",
    "found": true,
    "note": null,
    "retrievedAt": "2026-10-17T09:00:00.000Z",
    "consname": "EXAMPLE FOODS INC",
    "shipname": "EXAMPLE NUT FARMS LTD",
    "product": "SHELLED WALNUTS 25 KG BAGS"
}
```

A count only search returns one row with `recordType` set to `count`, `totalMatches` and the date range.

### FAQ

#### What is the ImportGenius Trade Data API?

The ImportGenius Trade Data API is the enterprise REST API of ImportGenius (Trade Data Services Inc.), a US trade intelligence company that compiles customs and bill of lading records. Its shipments endpoint on data.importgenius.com returns import and export shipment manifest data as JSON, at most 10 rows per request, from more than 3.3 billion records in 25+ countries, authenticated with an access token.

#### Do I need my own ImportGenius access token?

Yes. This is a bring-your-own-key actor: it calls ImportGenius with your token, under your ImportGenius agreement and on your plan's credits. A missing or rejected token, or a request outside your plan, ends the run cleanly with a status message explaining what to change, and nothing is charged.

#### Which search fields can I use?

ImportGenius documents product, consname (the US importer or consignee name), shipname (the shipper name) and trademark in its examples and gives each customer the complete list for their plan during integration. The actor accepts any lower case field name and passes it to the API, which refuses fields your plan does not have.

#### Which countries are covered?

ImportGenius advertises import and export data for 25+ countries, including US imports and exports from bills of lading and customs data for countries such as Vietnam, India and Russia. Which country codes you can query depends on your plan.

#### How do I find a company's suppliers or customers?

Search US imports with searchField consname and the company name to see who ships to it (the shipper column), or searchField shipname and a supplier name to see whom it ships to. Add a date range to see recent activity, or use count only first to see how many shipments match.

#### How many rows can I get?

As many as your row ceiling and your ImportGenius credits allow. The API returns at most 10 rows per request, so 100 rows take 10 requests. The actor stops at the total number of matches the API reports.

#### What do I pay?

Pay per result: 0.01 USD per shipment record, or per count only answer. Refused and empty searches are never charged. Your ImportGenius subscription and its API credits are billed separately by ImportGenius.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `shipment-record` | 0.01 USD | Each shipment record returned, or one count only answer |

### Keyword map

import export data API, bill of lading data, bill of lading API, customs data API, shipment data API, ImportGenius API, ImportGenius Trade Data API, US import data, export data, trade data API, importer database, supplier search, find suppliers, find buyers, consignee search, shipper search, HS code search, container shipment data, vessel and port data, competitor sourcing, supply chain intelligence, brand protection, trade data for AI agents.

### Terms and data use

ImportGenius API access is governed by your separate commercial agreement with ImportGenius, which its website Terms of Use say takes precedence for subscribers. The public Terms of Use for the website are strict: they prohibit selling, transferring, licensing, distributing or publicly displaying ImportGenius content, and say that use or posting of any content on any other website or in a networked computer environment, for any purpose, is prohibited. Treat the shipment records as licensed to you for your own internal use, do not resell or republish them, check your ImportGenius agreement before storing results in shared systems or sharing them with third parties, and delete copies if your access ends. Every request spends credits on your plan. This actor is not affiliated with or endorsed by ImportGenius or Trade Data Services Inc.

# Actor input Schema

## `queryType` (type: `string`):

Field search matches a search field (product, importer, shipper, trademark and the other fields on your plan) with a modifier and a term. The two zip code searches find US shipments by the importer's zip code or a zip code range, and need the country set to us.

## `searchField` (type: `string`):

Field search only. The category of the term, in lower case. Documented examples: product (product description), consname (US importer or consignee name), shipname (shipper name) and trademark. ImportGenius gives the complete field list for your plan during integration.

## `modifier` (type: `string`):

Field search only. How the term is matched against the field.

## `searchTerm` (type: `string`):

Field search only. The keyword, company name or brand to search for, such as walnuts, a supplier name or a trademark. Several words are fine; a slash is not.

## `zipCode` (type: `string`):

US zip code search only. A five digit zip code, such as 85258.

## `zipCodeFrom` (type: `string`):

US zip code range search only. The lower five digit zip code of the range.

## `zipCodeTo` (type: `string`):

US zip code range search only. The higher five digit zip code of the range.

## `extraConditions` (type: `array`):

Optional advanced conditions, one per line, as additionType field modifier term. additionType is and, or or not; modifier is contains, exactly, any, starts_with or ends_with. Example: not product contains used. Up to 10.

## `country` (type: `string`):

Two letter code of the customs dataset to search, such as us (United States), vn (Vietnam), in (India) or ru (Russia). Which countries you can query depends on your ImportGenius plan; ImportGenius lists your codes during integration.

## `tradeType` (type: `string`):

Search the country's import records or its export records.

## `startDate` (type: `string`):

Optional. First shipment date to include, as YYYY-MM-DD. Set together with the end date; leave both empty for your plan's default range.

## `endDate` (type: `string`):

Optional. Last shipment date to include, as YYYY-MM-DD.

## `countOnly` (type: `boolean`):

Return one row with the number of matching shipments instead of the shipment records. Useful for sizing a market or a supplier before pulling rows.

## `maxResults` (type: `integer`):

The most shipment rows this run returns and charges for. ImportGenius returns at most 10 rows per request, and every request spends credits on your ImportGenius plan, so start small.

## `requestsPerMinute` (type: `integer`):

Pacing. A rate limit answer is waited out and retried.

## `apiKey` (type: `string`):

Your own ImportGenius API access token. Stored as a secret and sent only to data.importgenius.com as the access_token parameter the API requires; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "queryType": "keyword",
  "searchField": "product",
  "modifier": "contains",
  "searchTerm": "walnuts",
  "country": "us",
  "tradeType": "im",
  "countOnly": false,
  "maxResults": 10,
  "requestsPerMinute": 30
}
```

# Actor output Schema

## `records` (type: `string`):

One row per shipment record.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerm": "walnuts"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/importgenius-bill-of-lading-shipments-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searchTerm": "walnuts" }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/importgenius-bill-of-lading-shipments-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerm": "walnuts"
}' |
apify call nabeelbaghoor/importgenius-bill-of-lading-shipments-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/importgenius-bill-of-lading-shipments-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3YHva3BFyp5VhNxJ9/builds/IvYDN9hqvikZGQQqV/openapi.json