UpKuaJing Customs Trade Company Search#

Search for companies through customs trade data using the UpKuaJing Open Platform API. This skill uses a data-driven approach: finding companies by analyzing trade records and transaction patterns.

Overview#

This skill provides access to UpKuaJing's customs trade data API through four scripts: two search methods (trade list, company list) and two enhancement interfaces (company details, contact information). API key generation and top-up are provided through the auth.py script.

Running Scripts#

Environment Setup#

1. Check Python: python --version
2. Install dependencies: pip install -r requirements.txt

Script directory: scripts/*.py Run example: python scripts/*.py

Important: Always use direct script invocation like python scripts/trade_list_search.py. Do NOT use shell compound commands like cd scripts && python trade_list_search.py.

Two Search Methods#

Trade List Search ( trade_list_search.py)

• Return granularity: Each trade order as one record

• Use cases: Focus on "what transactions occurred"

• Examples:

  • "Show all orders where Company A purchased LED"
  • "Find soybean trade records imported/exported to US"
  • "View specific transaction details within a time period"

• Parameters: See Trade List

Company List Search ( company_list_search.py)

• Return granularity: Trade orders aggregated by company, each company as one row

• Use cases: Focus on "which companies exist"

• Examples:

  • "Find companies that purchased LED"
  • "Find US companies with electronics import/export business with China"
  • "Find companies with China-US trade" (logistics industry customer development)

• Parameters: See Company List

Two Enhancement Features#

After obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary: Company Details ( company_get_details.py --companyIds *)

• Get company information (excluding contact information)
• Parameters: --companyIds List of company IDs (space-separated), max 20 at a time
• API business parameters: Company Details

Contact Information ( company_get_contact.py --companyIds *)

• Get contact details: email, phone, social media, website
• Parameters: --companyIds List of company IDs (space-separated), max 20 at a time
• API business parameters: Get Contact Information

API Key and Top-up#

This skill requires an API key. The API key is stored in the ~/.upkuajing/.env file:

bash

cat ~/.upkuajing/.env

Example file content:

text

UPKUAJING_API_KEY=your_api_key_here

API Key Not Set#

First check if the ~/.upkuajing/.env file has UPKUAJING_API_KEY; If UPKUAJING_API_KEY is not set, prompt the user to choose:

1. User has one: User provides it (manually add to ~/.upkuajing/.env file)
2. User doesn't have one: You can apply using the interface ( auth.py --new_key), the new key will be automatically saved to ~/.upkuajing/.env Wait for user selection;

Account Top-up#

When API response indicates insufficient balance, explain and guide user to top up:

1. Create top-up order ( auth.py --new_rec_order)
2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;

Get Account Information#

Use this script to get account information for UPKUAJING_API_KEY: auth.py --account_info

API Key and UpKuaJing Account#

• Newly applied API key: Register and login at UpKuaJing Open Platform, then bind account

Fees#

All API calls incur fees, different interfaces have different billing methods. Latest pricing: Users can visit Detailed Price Description Or use: python scripts/auth.py --price_info (returns complete pricing for all interfaces)

List Search Billing Rules#

Billed by number of calls, each call returns up to 20 records:

• Number of calls: ceil(query_count / 20) times
• Whenever query_count > 20, must before execution:
  1. Inform user of expected number of calls
  2. Stop, wait for explicit user confirmation in a separate message, then execute script

Enhancement Interface Billing Rules#

Billed by number of IDs passed, max 20 IDs per call:

• Pass 1 ID = billed 1 time
• Pass 20 IDs = billed 20 times (single call limit)
• Before batch retrieval must:
  1. Inform user of number of IDs passed and corresponding fee count
  2. Stop, wait for explicit user confirmation in a separate message, then execute script

Fee Confirmation Principle#

Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.

Workflow#

Choose the appropriate API based on user intent

Decision Guide#

User IntentUse API"Analyze trade patterns/order data"Trade list"Find companies purchasing XXX"Company list"Find suppliers for XXX with email"Company list existEmail=1"Get company detailed information"Company details"Get contact information"Contact information

Usage Examples#

Scenario 1: Small Query — Trade Data Analysis#

User request: "Show 2024 LED lighting fixture trade data exported to US"

bash

python scripts/trade_list_search.py \
  --params '{"products": ["LED lights"], "buyerCountryCodes": ["US"], "dateStart": 1704067200000, "dateEnd": 1735689599999}' \
  --query_count 20

To further get supplier details (supports batch queries):

bash

python scripts/company_get_details.py --companyIds 123456 789012 ...

Scenario 2: Large Query — Big Data Analysis#

User request: "Analyze 100 soybean trade records from 2024" Before execution inform user: ceil(100/20) = 5 API calls, confirm before executing;

bash

python scripts/trade_list_search.py --params '{"products": ["soybean"], "dateStart": 1704067200000, "dateEnd": 1735689599999}' --query_count 100

Scenario 3: Ultra Large Query - Multiple Script Calls Required#

User request: "Find 2000 companies importing electronics from China, with email addresses" Before execution inform user: ceil(2000/20) = 100 API calls, confirm before executing;

bash

python scripts/company_list_search.py --params '{"companyType": 2, "sellerCountryCodes": ["CN"], "existEmail": 1}' --query_count 1000

After execution: Script responds {"task_id":"a1b2-c3d4", "file_url": "xxxxx", ……} Continue execution, append data: Specify task_id, script continues query from last cursor and appends to file

bash

python scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000

Error Handling#

• API key invalid/non-existent: Check UPKUAJING_API_KEY in ~/.upkuajing/.env file
• Insufficient balance: Guide user to top up according to Account Top-up steps
• Invalid parameters: Must first check the corresponding API documentation in references/ directory, check parameter names and formats, do not guess

Best Practices#

Choosing the Right Method#

1. Understand user intent:
   • Analyze trade data? → Use trade list search
   • Find customers/partners? → Use company list search
2. Check API documentation:
   • Before executing list queries, must first check the corresponding API reference documentation
   • Trade list: Check references/trade-list-api.md
   • Company list: Check references/company-list-api.md
3. Identify parameter conditions:
   • Set date range
   • HS codes are usually more precise than product names for filtering
   • Reduce noise by filtering specific countries
   • Use ISO country codes: CN, US, JP, etc.
   • Use filters to find companies with contact information

Handling Results#

1. Handle jsonl files carefully: For large data queries, pay attention to file size

2. Gradually enrich information: Only call details/contact interfaces when needed

   • Company IDs returned by both list interfaces can be used for both detail interfaces
   • If user only needs a few companies, don't get details for all companies

Notes#

• All timestamps are in milliseconds
• Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)
• File paths use forward slashes on all platforms
• Product names and industry names must be in English
• Search quantity affects API response time, recommend setting timeout:120
• Prohibit outputting technical parameter format: Do not display code-style parameters in responses, convert to natural language
• Do not estimate or guess per-call fees — use python scripts/auth.py --price_info to get accurate pricing information
• Do not guess parameter names, get accurate parameter names and formats from documentation

Related Skills#

Other UpKuaJing skills you might find useful:

• upkuajing-global-company-people-search — Global company and people search
• upkuajing-email-tool — Send emails and manage email tasks
• upkuajing-map-merchants-search — Map-based merchant search
• upkuajing-sms-tool — Send SMS and manage SMS tasks
• upkuajing-contact-info-validity-check — Check contact info validity