Use ImportYeti Importer & Supplier Trade Explorer with Python

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.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

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

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	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`	array	optional	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`	array	optional	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`	array	optional	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`	array	optional	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`	string	optional	Whether bare country slugs point at the overseas-supplier directory or the US-importer directory. Ignored for full location URLs.
`productTags`	array	optional	Product-tag slugs such as yoga-mat or lithium-battery, or full /tags/... URLs (mode=byProductTags).
`entityType`	string	optional	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`	string	optional	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`	integer	optional	Drop entities with fewer than this many lifetime shipments. Applied locally.
`maxResults`	integer	optional	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`	boolean	optional	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`	integer	optional	Cap the top-supplier or top-customer table per profile. ImportYeti exposes up to 50.
`maxShipments`	integer	optional	Cap the recent bill-of-lading rows per profile. ImportYeti exposes up to 50.
`includeTradeDetails`	boolean	optional	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.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/PFnzbyk7iniGWqyZw/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Dataset of ImportYeti profiles, HS/location/product-tag trade summaries and top-partner rows, including shipment totals, recent bills of lading, HS/HTS codes, lanes, carriers, containers, notify parties and UFLPA flags.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build 5R6amCzzOzPyzgAj4 and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.