# ImportYeti Importer & Supplier Trade Explorer (`xyrelith-data/importyeti-company-and-supplier-shipment-lookup`) Actor

Search ImportYeti by company, supplier, product, address, HS code, location or product tag; optionally open profiles for top trading partners, recent bills of lading, HS/HTS codes, shipping lanes, carriers, containers, notify parties and UFLPA flags.

- **URL**: https://apify.com/xyrelith-data/importyeti-company-and-supplier-shipment-lookup.md
- **Developed by:** [Xyrelith Data](https://apify.com/xyrelith-data) (community)
- **Categories:** E-commerce, Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## ImportYeti Importer & Supplier Trade Explorer

ImportYeti publishes US ocean-import records: who imported what, which overseas company shipped it, and the shipment volume behind the relationship. This actor turns those public pages into one structured dataset you can search, filter and join.

It works without a login, cookie, API key or browser. ImportYeti's public pages are read directly, and the actor rotates its network session automatically when the site's pageview limit is reached.

### What you can do

- **Search by name, product or address** — match importers, suppliers and indexed product text.
- **Paste ImportYeti URLs** — company, supplier, HS-code, location, product-tag or search links.
- **Look up an HS code** — get the code summary, its top suppliers, top US importers and recent shipments.
- **Browse a location** — a country, state, county or city directory of suppliers or importers.
- **Browse a product tag** — see the companies and suppliers behind a product category.
- **Open profiles** — add top trading partners, recent bills of lading, HS/HTS codes, port lanes, carriers, containers, notify parties, other addresses, tags and UFLPA flags.

### Modes

| Mode | Use it for |
|---|---|
| Search by name, product, or address | A company name (`apple`), brand (`ADIDAS`), product keyword (`hdmi cable`) or address text. |
| Scrape ImportYeti URLs | A list of known company/supplier/HS/location/tag/search URLs. |
| Find importers & suppliers by HS code | A 2-, 4- or 6-digit HS code such as `85`, `8471` or `8507.60`. |
| Browse a country, state, or city | A country slug (`china`) or a full location URL for a state, county or city. |
| Browse a product tag | A tag slug (`yoga-mat`) or a full `/tags/...` URL. |

Only the input that matches the selected mode is used. The other mode inputs can stay empty.

#### Defaults

| Field | Default |
|---|---|
| `mode` | `search` |
| `searchQueries` | Any |
| `startUrls` | Any |
| `hsCodes` | Any |
| `locations` | Any |
| `locationType` | `supplier` |
| `productTags` | Any |
| `entityType` | `any` |
| `shipmentRecency` | `any` |
| `minShipments` | `0` |
| `maxResults` | `25` |
| `includeProfileDetails` | `true` |
| `maxPartners` | `50` |
| `maxShipments` | `50` |
| `includeTradeDetails` | `true` |

### Input

| Field | What it does |
|---|---|
| `mode` | Selects the mode above. |
| `searchQueries` | One or more names, brands, product keywords or address strings (search mode). |
| `startUrls` | ImportYeti URLs or paths (URL mode). Full `https://www.importyeti.com/...` links and `company/apple`-style paths both work. |
| `hsCodes` | HS codes or `/hs-codes/...` URLs (HS mode). |
| `locations` | Country slugs or full `/location/...` URLs (location mode). |
| `locationType` | For bare country slugs: `supplier` or `company`. Ignored for full location URLs. |
| `productTags` | Tag slugs or `/tags/...` URLs (product-tag mode). |
| `entityType` | `any`, `company` or `supplier`. Search uses ImportYeti's server-side type filter. |
| `shipmentRecency` | `any`, `3mo`, `6mo`, `12mo` or `24mo`. Applied locally to the dates the source returns. |
| `minShipments` | Minimum lifetime shipments. Applied locally. |
| `maxResults` | Run-wide record cap. |
| `includeProfileDetails` | Open each matched profile for partner and shipment data. |
| `maxPartners` | Cap partner rows per profile (source maximum 50). |
| `maxShipments` | Cap recent bill-of-lading rows per profile (source maximum 50). |
| `includeTradeDetails` | Include HS/HTS, lanes, carriers, containers, notify parties, addresses, tags and monthly history from the opened profile. |

#### Examples

Basic company search:

```json
{
  "mode": "search",
  "searchQueries": ["apple"],
  "entityType": "company",
  "maxResults": 25
}
```

Product-keyword search with active suppliers and details:

```json
{
  "mode": "search",
  "searchQueries": ["hdmi cable"],
  "entityType": "supplier",
  "shipmentRecency": "12mo",
  "minShipments": 100,
  "includeProfileDetails": true,
  "maxPartners": 10,
  "maxShipments": 10,
  "maxResults": 20
}
```

HS-code lookup:

```json
{
  "mode": "byHsCodes",
  "hsCodes": ["8507.60"],
  "maxResults": 25
}
```

Company URL:

```json
{
  "mode": "byUrls",
  "startUrls": [{"url": "https://www.importyeti.com/company/apple"}],
  "maxResults": 1
}
```

Location and product-tag modes:

```json
{
  "mode": "byLocations",
  "locations": ["china"],
  "locationType": "supplier",
  "maxResults": 20
}
```

```json
{
  "mode": "byProductTags",
  "productTags": ["yoga-mat"],
  "maxResults": 20
}
```

### Output

Every record starts with the same envelope: `type` (`importyeti_record`), `recordKind`, `name`, `recordType`, `countryCode`, `address`, `detailUrl`, `matchSource`, `matchValue`, `sourcePageUrl` and `scrapedAt`.

`recordKind` tells you what the row is:

- `profile` — one company or supplier, from a search hit or a company/supplier URL.
- `tradeSummary` — one HS code, location or product tag, with totals and its nested partner/shipment tables.
- `partner` — one row from an HS/location/tag supplier or company table.

Key fields include:

- **Identity** — `name`, `recordType`, `alsoKnownAs`, `website`, `otherWebsites`, `address`, `addressParsed`, `addressPlain`, `locationHierarchy`, `latitude`, `longitude`.
- **Shipment summary** — `totalShipments`, `shipments12m`, `mostRecentShipment`, `mostRecentShipmentDate`, `firstShipmentDate`, `dateRange`, `totalShippingCost`, `shippingCostCoverage`, `avgTeuPerShipment`, `avgTeuPerMonth`, `quarterlyGrowth`.
- **Partners** — `topSuppliers` (names) and `topPartners` (structured rows with role, address, country, shipments, weight, TEU, HS codes and counterparties).
- **Recent shipments** — `recentShipments` with date, BOL/master/house numbers, counterparty, product description, weight, quantity, containers, route and estimated freight cost.
- **Product codes** — `hsCodes`, `htsCodes`, `topImports`.
- **Logistics** — `shippingLanes`, `topCarriers`, `carriersPerCountry`, `scacCodesDiversity`, `containers`, `containerTypes`, `containerLoad`.
- **Other** — `notifyParties`, `otherAddresses`, `tags`, `trademarks`, `trademarkCount`, `monthlyShipments`, `originCountries`, `chartImages`, `uflpa`, `uflpaUrl`, `manifestConfidential`.
- **Provenance** — `matchSource`, `matchValue`, `sourcePageUrl`, `scrapedAt`.

Empty values are omitted; the actor never pushes `null`, empty strings or placeholder text.

### Limits you should know

- **Search reach:** ImportYeti's public search serves up to 14 pages of 10 results for one entity type — **140 rows per role, 280 per query** when both types are fetched. `totalHits` and `totalPages` in the source JSON describe the whole index, not what is reachable. Use more `searchQueries` to cover more.
- **Profile reach:** each public profile exposes at most **50 top partners** and **50 recent bills of lading**. Older individual shipments are not public.
- **Pageview limit:** ImportYeti allows about **25 pageviews per IP address**, shared by search and profile pages. The actor rotates its network session automatically; if every rung is blocked, it fails honestly instead of returning an empty success.
- **Contacts:** ImportYeti masks phone numbers and email addresses for anonymous visitors. Those fields are not returned.
- **Source quirks:** some partner names are filed as `Missing in source document`; those rows are omitted. Website values occasionally arrive truncated by the source; invalid domains are omitted.

### Use cases

- Find the overseas companies shipping a product category to the US.
- Map a competitor's top suppliers and recent import activity.
- Build a list of US importers for an HS code or a location.
- Check a partner's shipment recency, volume and trade lanes before outreach.
- Research HS/HTS codes, carriers and port pairs behind a company's imports.

### FAQ

**Do I need an ImportYeti account or API key?**
No. The actor reads public pages only and needs no login, cookie or key.

**Why did I get fewer rows than `maxResults`?**
The source may have fewer matches, or the query hit the 280-row search ceiling. Add another query, use an HS/location/tag mode, or lower the filters.

**Why are phone numbers and emails missing?**
ImportYeti redacts them for visitors who are not logged in. The actor omits masked contact fields rather than guessing.

**Why are there only 50 shipments for a large importer?**
ImportYeti publishes the 50 most recent bills of lading per company or supplier. Older shipment detail is not on the public page.

**How are suppliers and importers distinguished?**
ImportYeti calls US importers `company` and overseas exporters `supplier`. Use `entityType` to filter, and read `recordType` on every row.

**Does this use a browser or proxy?**
No browser is involved. The actor uses normal HTTPS requests and selects its network session automatically. You do not configure a proxy.

**Is this affiliated with ImportYeti?**
No. This is an independent tool. US customs bill-of-lading data is public; users are responsible for complying with applicable law and the source site's terms.

### Data source and compliance

The actor reads only public ImportYeti pages: company and supplier profiles, search results, HS-code pages, location directories and product tags. It does not access a logged-in account, premium data, private records or a paid API. Shipment records originate in US Customs bill-of-lading filings. Use the data lawfully and respect the source site's terms.

# Actor input Schema

## `mode` (type: `string`):

What to scrape. Search matches names, product keywords and address text. URL, HS-code, location and product-tag modes read the corresponding ImportYeti pages directly.

## `searchQueries` (type: `array`):

Company names, brands, product keywords, or address text (mode=search). One entry per search. ImportYeti searches names, indexed product text and address text; a trademark name works as a brand search, not a separate trademark index.

## `startUrls` (type: `array`):

Company, supplier, HS-code, location, product-tag or search URLs (mode=byUrls). Full https://www.importyeti.com/... links or paths such as company/apple are accepted.

## `hsCodes` (type: `array`):

2-, 4- or 6-digit HS codes, e.g. 85, 8471, 8507.60, or full /hs-codes/... URLs (mode=byHsCodes). Each code returns its top suppliers, top US companies and recent shipments.

## `locations` (type: `array`):

Country slugs such as china or vietnam, or full /location/... URLs for states, counties and cities (mode=byLocations). Bare slugs use the location type below.

## `locationType` (type: `string`):

Whether bare country slugs point at the overseas-supplier directory or the US-importer directory. Ignored for full location URLs.

## `productTags` (type: `array`):

Product-tag slugs such as yoga-mat or lithium-battery, or full /tags/... URLs (mode=byProductTags).

## `entityType` (type: `string`):

Keep only US importers (companies), only overseas suppliers, or both. Search uses ImportYeti's own server-side type filter; HS, location and tag modes filter their supplier/company tables.

## `shipmentRecency` (type: `string`):

Keep only entities with a shipment in this window. ImportYeti's search API ignores this filter, so it is applied locally to the dates the source returns.

## `minShipments` (type: `integer`):

Drop entities with fewer than this many lifetime shipments. Applied locally.

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

Maximum records to return in this run. ImportYeti caps a search query at 280 reachable rows (140 per entity type); use more search queries for more. Every profile exposes at most 50 partners and 50 recent shipments.

## `includeProfileDetails` (type: `boolean`):

Open each matched company or supplier and return its trading partners, recent bills of lading and trade details. Adds one request per profile. Applies to search and URL modes; HS, location and tag pages already contain their tables.

## `maxPartners` (type: `integer`):

Cap the top-supplier or top-customer table per profile. ImportYeti exposes up to 50.

## `maxShipments` (type: `integer`):

Cap the recent bill-of-lading rows per profile. ImportYeti exposes up to 50.

## `includeTradeDetails` (type: `boolean`):

Emit HS/HTS codes, port lanes, carriers, containers, notify parties, other addresses, tags and monthly history from the opened profile. Only applies when profile details are opened.

## Actor input object example

```json
{
  "mode": "search",
  "searchQueries": [
    "apple"
  ],
  "startUrls": [],
  "hsCodes": [],
  "locations": [],
  "locationType": "supplier",
  "productTags": [],
  "entityType": "any",
  "shipmentRecency": "any",
  "minShipments": 0,
  "maxResults": 3,
  "includeProfileDetails": false,
  "maxPartners": 0,
  "maxShipments": 0,
  "includeTradeDetails": false
}
```

# Actor output Schema

## `results` (type: `string`):

All records in one dataset. Use the recordKind field (profile, tradeSummary or partner) to separate profile rows, HS/location/tag summaries and top-partner rows.

# 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 = {
    "mode": "search",
    "searchQueries": [
        "apple"
    ],
    "startUrls": [],
    "hsCodes": [],
    "locations": [],
    "locationType": "supplier",
    "productTags": [],
    "entityType": "any",
    "shipmentRecency": "any",
    "minShipments": 0,
    "maxResults": 3,
    "includeProfileDetails": false,
    "maxPartners": 0,
    "maxShipments": 0,
    "includeTradeDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("xyrelith-data/importyeti-company-and-supplier-shipment-lookup").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 = {
    "mode": "search",
    "searchQueries": ["apple"],
    "startUrls": [],
    "hsCodes": [],
    "locations": [],
    "locationType": "supplier",
    "productTags": [],
    "entityType": "any",
    "shipmentRecency": "any",
    "minShipments": 0,
    "maxResults": 3,
    "includeProfileDetails": False,
    "maxPartners": 0,
    "maxShipments": 0,
    "includeTradeDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("xyrelith-data/importyeti-company-and-supplier-shipment-lookup").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 '{
  "mode": "search",
  "searchQueries": [
    "apple"
  ],
  "startUrls": [],
  "hsCodes": [],
  "locations": [],
  "locationType": "supplier",
  "productTags": [],
  "entityType": "any",
  "shipmentRecency": "any",
  "minShipments": 0,
  "maxResults": 3,
  "includeProfileDetails": false,
  "maxPartners": 0,
  "maxShipments": 0,
  "includeTradeDetails": false
}' |
apify call xyrelith-data/importyeti-company-and-supplier-shipment-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xyrelith-data/importyeti-company-and-supplier-shipment-lookup"
        }
    }
}
```

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/OOJaXZWM3GswCgeh3/builds/8067cydD5JhF0oBDn/openapi.json