{"id":"bfa2603c-7c8f-4e34-ade1-a437c65f632b","entityType":"agent","slug":"clawhub-upkuajing-upkuajing-customs-trade-company-search","name":"Global customs trade data aggregated across 220+ countries with integrated bulk search functionality for global B2B prospecting. Accelerate discovery ofverified genuine buyers and qualified international suppliers for export businesses. Dig into official ","canonicalUrl":"https://www.xpersona.co/agent/clawhub-upkuajing-upkuajing-customs-trade-company-search","canonicalPath":"/agent/clawhub-upkuajing-upkuajing-customs-trade-company-search","generatedAt":"2026-10-10T08:29:40.459Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":null},"description":"Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business. Trigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17304xrt0p2xssnmr7datqzks83gvsr:upkuajing-customs-trade-company-search","sourceUrl":"https://clawhub.ai/upkuajing/upkuajing-customs-trade-company-search","homepage":"https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/upkuajing/upkuajing-customs-trade-company-search","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Global customs trade data aggregated across 220+ countries with integrated bulk search functionality for global B2B prospecting. Accelerate discovery ofverified"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":null},"stars":null,"forks":null,"downloads":1894,"packageName":null,"latestVersion":"1.0.10","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:23:59.311Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:23:59.312Z","lastCrawledAt":"2026-10-09T23:23:59.311Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:23:59.311Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.10","createdAt":"2026-08-24T09:08:29.260Z","changelog":"updated","fileCount":17,"zipByteSize":29464},{"version":"1.0.9","createdAt":"2026-07-16T08:56:32.115Z","changelog":"updated","fileCount":15,"zipByteSize":26388},{"version":"1.0.8","createdAt":"2026-07-16T06:16:59.548Z","changelog":"updated","fileCount":15,"zipByteSize":26653},{"version":"1.0.7","createdAt":"2026-07-06T03:59:08.850Z","changelog":"updated","fileCount":15,"zipByteSize":26190},{"version":"1.0.6","createdAt":"2026-04-17T11:37:18.979Z","changelog":"updated","fileCount":15,"zipByteSize":26354},{"version":"1.0.5","createdAt":"2026-04-10T03:03:05.812Z","changelog":"Initial release","fileCount":13,"zipByteSize":22462}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17304xrt0p2xssnmr7datqzks83gvsr:upkuajing-customs-trade-company-search","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17304xrt0p2xssnmr7datqzks83gvsr:upkuajing-customs-trade-company-search` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/upkuajing/upkuajing-customs-trade-company-search before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T08:29:40.455Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-customs-trade-company-search/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":null},"readme":"Skill: Global customs trade data aggregated across 220+ countries with integrated bulk search functionality for global B2B prospecting. Accelerate discovery ofverified genuine buyers and qualified international suppliers for export businesses. Dig into official import & export shipment records to pinpointproduct-matching importers and full historical transaction logs. Run targeted lookups filtered by company profiles, HS codes and product keywords. Trade teamsleverage verified real-world shipment intelligence to secure high-value B2B prospects and track competitors’ cross-border trading activity.\n\nOwner: upkuajing\n\nSummary: Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business. Trigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search\n\nTags: B2B prospecting:1.0.10, HS-code lookup:1.0.10, buyer:1.0.10, competitor monitoring:1.0.10, customs:1.0.10, customs-trade data:1.0.10, exporter:1.0.10, importer:1.0.10, latest:1.0.10, market-research:1.0.10, overseas buyer search:1.0.10, sourcing:1.0.10, trade-data:1.0.10\n\nVersion history:\n\nv1.0.10 | 2026-08-24T09:08:29.260Z | user\n\nupdated\n\nv1.0.9 | 2026-07-16T08:56:32.115Z | user\n\nupdated\n\nv1.0.8 | 2026-07-16T06:16:59.548Z | user\n\nupdated\n\nv1.0.7 | 2026-07-06T03:59:08.850Z | user\n\nupdated\n\nv1.0.6 | 2026-04-17T11:37:18.979Z | user\n\nupdated\n\nv1.0.5 | 2026-04-10T03:03:05.812Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.10: 17 files, 29464 bytes\n\nFiles: references/company-detail-api.md (1066b), references/company-list-api.md (2993b), references/contact-fetch-api.md (1540b), references/skill-error-report-api.md (2070b), references/trade-list-api.md (3034b), requirements.txt (13b), scripts/auth.py (5885b), scripts/common.py (14512b), scripts/company_get_contact.py (1687b), scripts/company_get_details.py (1645b), scripts/company_list_search.py (6315b), scripts/error_report.py (1845b), scripts/trade_list_search.py (5973b), scripts/version_check.py (4933b), skill-card.md (3191b), SKILL.md (12534b), _meta.json (158b)\n\nFile v1.0.10:SKILL.md\n\n---\nname: upkuajing-customs-trade-company-search\ndescription: \"Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business.\\n\\nTrigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search\"\nmetadata: {\"version\":\"1.0.10\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Customs Trade Company Search\n\nSearch 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.\n\n## Overview\n\nThis 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).\nAPI key generation and top-up are provided through the `auth.py` script.\n\n## Running Scripts\n\n### Environment Setup\n\n1. **Check Python**: `python --version`\n2. **Install dependencies**: `pip install -r requirements.txt`\n\nScript directory: `scripts/*.py`\nRun example: `python scripts/*.py`\n\n**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`.\n\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\n\n### Two Search Methods\n\n**Trade List Search** (`trade_list_search.py`)\n- **Return granularity**: Each trade order as one record\n- **Use cases**: Focus on \"what transactions occurred\"\n- **Examples**:\n   - \"Show all orders where Company A purchased LED\"\n   - \"Find soybean trade records imported/exported to US\"\n   - \"View specific transaction details within a time period\"\n- **Parameters**: See [Trade List](references/trade-list-api.md)\n\n\n**Company List Search** (`company_list_search.py`)\n- **Return granularity**: Trade orders aggregated by company, each company as one row\n- **Use cases**: Focus on \"which companies exist\"\n- **Examples**:\n  - \"Find companies that purchased LED\"\n  - \"Find US companies with electronics import/export business with China\"\n  - \"Find companies with China-US trade\" (logistics industry customer development)\n- **Parameters**: See [Company List](references/company-list-api.md)\n\n\n### Two Enhancement Features\n\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\n**Company Details** (`company_get_details.py --companyIds *`)\n- Get company information (excluding contact information)\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Company Details](references/company-detail-api.md)\n\n**Contact Information** (`company_get_contact.py --companyIds *`)\n- Get contact details: email, phone, social media, website\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\n\n## API Key and Top-up\n\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\n```bash\ncat ~/.upkuajing/.env\n```\n**Example file content**:\n```\nUPKUAJING_API_KEY=your_api_key_here\n```\n### **API Key Not Set**\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\n2. 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\nWait for user selection;\n\n### **Account Top-up**\nWhen API response indicates insufficient balance, explain and guide user to top up:\n1. Create top-up order (`auth.py --new_rec_order`)\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\n\n### **Get Account Information**\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\n\n## API Key and UpKuaJing Account\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n### **Report Skill Call Errors**\nWhen an API call fails or returns abnormal data (server error, timeout, malformed response, etc.), explain the anomaly to the user in natural language and ask whether to report it to the platform for troubleshooting. Only run the report after user confirmation:\n```bash\npython scripts/error_report.py --params '{\"requestPath\":\"/agent/customs/company/list\",\"requestId\":\"f47ac10b58cc4372a5670e02b2c3d479\",\"context\":\"Customs trade company search failed with a server error\"}'\n```\n- Do not report normal business conditions (insufficient balance, invalid API key, parameter errors) — handle them via their own flows\n- Error reporting does not incur query fees\n- **Parameters**: See [Error Report API](references/skill-error-report-api.md)\n\n## Fees\n\n**All API calls incur fees**, different interfaces have different billing methods.\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\n\n### List Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 20 records:\n- Number of calls: `ceil(query_count / 20)` times\n- **Whenever query_count > 20, must before execution:**\n  1. Inform user of expected number of calls\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Enhancement Interface Billing Rules\n\nBilled by **number of IDs passed**, max 20 IDs per call:\n- Pass 1 ID = billed 1 time\n- Pass 20 IDs = billed 20 times (single call limit)\n- **Before batch retrieval must:**\n  1. Inform user of number of IDs passed and corresponding fee count\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Fee Confirmation Principle\n\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\n\n\n## Workflow\n\nChoose the appropriate API based on user intent\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Analyze trade patterns/order data\" | Trade list |\n| \"Find companies purchasing XXX\" | Company list |\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\n| \"Get company detailed information\" | Company details |\n| \"Get contact information\" | Contact information |\n\n## Usage Examples\n\n### Scenario 1: Small Query — Trade Data Analysis\n\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\n```bash\npython scripts/trade_list_search.py \\\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\n  --query_count 20\n```\n\nTo further get supplier details (supports batch queries):\n```bash\npython scripts/company_get_details.py --companyIds 123456 789012 ...\n```\n\n### Scenario 2: Large Query — Big Data Analysis\n\n**User request**: \"Analyze 100 soybean trade records from 2024\"\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\n```bash\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\n```\n\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\n\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\n```bash\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\n```\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\n```bash\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\n```\n\n## Error Handling\n\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\n- **Skill call errors / abnormal responses**: Explain to the user and, with user confirmation, report to the platform via `python scripts/error_report.py` (see [Report Skill Call Errors](#report-skill-call-errors))\n\n### API Documentation Reference\n\n- Error Report: Check [references/skill-error-report-api.md](references/skill-error-report-api.md)\n\n## Best Practices\n\n### Choosing the Right Method\n\n1. **Understand user intent**:\n   - Analyze trade data? → Use **trade list search**\n   - Find customers/partners? → Use **company list search**\n\n2. **Check API documentation**:\n   - **Before executing list queries, must first check the corresponding API reference documentation**\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\n\n3. **Identify parameter conditions**:\n   - Set date range\n   - HS codes are usually more precise than product names for filtering\n   - Reduce noise by filtering specific countries\n   - Use ISO country codes: CN, US, JP, etc.\n   - Use filters to find companies with contact information\n\n### Handling Results\n\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\n\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\n   - If user only needs a few companies, don't get details for all companies\n\n## Notes\n- All timestamps are in milliseconds\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\n- File paths use forward slashes on all platforms\n- Product names and industry names must be in **English**\n- Search quantity affects API response time, recommend setting timeout:120\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\n\n## Related Skills\n\nOther UpKuaJing skills you might find useful:\n\n- linkedin-person-search — Search people from the LinkedIn source\n- global-company-person-search — Search people from the global company database\n- linkedin-company-search — Search companies from the LinkedIn source\n- global-company-search — Search companies from the global company database\n- global-company-shareholder — Query shareholder list from the global company database\n- global-company-employee — Query employee list from the global company database\n- global-company-person-colleague — Query colleague list from the global company database\n- global-company-person-alumni — Query alumni list from the global company database\n- global-company-person-experience — Query work experience list from the global company database\n- global-company-person-education — Query education history list from the global company database\n- global-company-person-school-detail — Query school detail from the global company database\n- upkuajing-global-company-people-search — Global company and people search\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-map-merchants-search — Map-based merchant search\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n- phone-validity-check — Check phone number validity\n- email-validity-check — Check email address validity\n- domain-validity-check — Check domain validity and security\n\nFile v1.0.10:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.10\",\n  \"publishedAt\": 1787562509260\n}\n\nFile v1.0.10:references/company-detail-api.md\n\n# 公司详情 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n\n### 基本信息\n- companyId：公司编号\n- name：公司名\n- logo：公司logo\n- introduce：公司介绍\n- industry：行业\n- scope：经营范围\n\n### 位置信息\n- location：公司位置\n- country：国家\n- province：省、州\n- city：城市\n- address：地址\n- postcode：邮编\n\n### 注册信息\n- registerPerson：注册法人\n- registerNumber：注册编号\n- registerDate：注册日期\n- registerType：注册类型\n- registerCapital：注册资金\n- registerState：注册状态\n\n### 贸易信息\n- companyType：公司贸易类型\n  - 0：未知\n  - 1：供应商\n  - 2：采购商\n  - 3：采购商和供应商\n\n### 国家信息\n- country.id：国家编号\n- country.name_cn：国家中文名\n- country.name_en：国家英文名\n- country.code_iso2：国家二字码\n- country.icon：国旗链接\n\nFile v1.0.10:references/company-list-api.md\n\n# 公司列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 必需参数\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（数组）：产品名称列表\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\n- productSuperordinate（数组）：产品的上游产品名称列表\n- productDownstream（数组）：产品的下游产品名称列表\n### 公司筛选\n- sellerIds（数组）：供应商公司ID列表\n- buyerIds（数组）：采购商公司ID列表\n- seller（字符串）：供应商公司名称\n- buyer（字符串）：采购商公司名称\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 联系方式筛选\n- existPhone：1（有电话），2（无电话），0（全部）\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\n- existWebsite：1（有网站），2（无网站），0（全部）\n- existSocial：1（有社媒），2（无社媒），0（全部）\n### 其他参数\n- tradeCode（字符串）：提关单号\n- minTradeCount（整数）：最小贸易频次数量\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n\n### 排序\n- sorting_field：tradeCount（默认）、latestTradeDate\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应\n\n### 公司标识\n- companyId：公司ID\n- companyType：1（供应商），2（采购商）\n- name：公司名称\n### 贸易统计\n- tradeTotal：贸易总量\n- tradeMatchTotal：匹配贸易量\n- tradeMatchPercent：匹配贸易占比（%）\n- latestTradeDate：最后贸易日期（毫秒时间戳）\n### 公司信息\n- countryInfo：所属国信息\n- scope：公司主营\n- address：公司地址\n### 产品信息\n- productDesc：产品描述\n- productTag：产品标签列表\n- productNames：标准化产品名称\n- productAlias：产品别名\n- productSuperordinate：产品的上游产品名称列表\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.10:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n- companyId：公司编号\n\n### 邮箱信息 emails\n- val：邮箱地址\n- is_valid：是否有效\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- reason：原因\n\n### 电话信息 phones\n- val：电话号码\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_ws：是否WhatsApp\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- phone_type：号码类型\n  - 0：未检测\n  - 1：固定电话\n  - 2：移动电话\n  - 3：已检测但未知\n- country_code：电话所属国家二字码\n- dialing_code：电话所属国际冠码\n- area_code：电话所属地区码\n- international_number：国际格式号码\n- telephone：号码(去除冠码与区码)\n- national_number：号码属国格式\n\n### 社交媒体信息 socials\n- val：社媒完整链接\n- social_url：社媒链接路径\n- social_type：社媒链接类型\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- reason：原因\n\n### 网站信息 websites\n- val：网址\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_sensitive：是否敏感\n  - 0：未检测\n  - 1：是（如电子商务网站）\n  - 2：否\n  - 3：不确定\n- reason：原因\n\nFile v1.0.10:references/skill-error-report-api.md\n\n# Agent调用Skill异常上报 API 参考\n\n> 上报 Agent 调用 Skill 异常，用于平台侧问题追踪与优化。异常上报不产生查询费用。\n> 接口路径：`POST /agent/skill/error/report`\n> 鉴权：需要 Bearer 令牌（UPKUAJING_API_KEY）\n\n## python脚本参数\n\n- `--params`：JSON格式的上报参数（必填）\n- 未传 `skillId`/`skillVersion` 时，脚本会自动从当前 Skill 目录名与 SKILL.md 读取并填充\n- 必填参数：`skillId`、`skillVersion`、`requestId`、`requestPath`、`context`；其中 `requestId` 从出问题的请求响应（ApiResp.requestId）中获取\n\n## API请求参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| skillId | string | 是 | Skill 标识（最大128字符），如\"customs-analysis-area\" |\n| skillVersion | string | 是 | Skill 版本（最大32字符） |\n| agentName | string | 否 | Agent 名称（最大128字符） |\n| modelName | string | 否 | 模型名称（最大128字符） |\n| requestPath | string | 是 | 出问题的站内接口路径，以 / 开头（最大255字符），如\"/agent/customs/analysis/area\" |\n| requestId | string | 是 | 全请求唯一关联号（最大128字符），取失败请求响应中的 requestId |\n| requestTime | long | 否 | 请求发起时间戳（毫秒，≥0） |\n| requestParams | object | 否 | 请求参数（原始入参，敏感字段会自动脱敏；序列化后≤64KB） |\n| responseData | object | 否 | 响应数据（异常发生时的返回内容，敏感字段会自动脱敏；序列化后≤64KB） |\n| durationMs | long | 否 | 本次调用耗时（毫秒，≥0） |\n| context | string | 是 | 异常上下文（堆栈/错误信息，用于定位根因，最大2000字符） |\n\n## 响应数据\n\n### 外层结构\n\n- code（integer）：状态码，0 表示成功\n- msg（string）：提示信息\n- requestId（string）：全请求唯一关联号（32位无横线，与 MDC traceId 同值）\n\n### data 字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| reportId | long | 上报记录 ID |\n\nFile v1.0.10:references/trade-list-api.md\n\n# 贸易列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（字符串数组）：产品名称列表\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\n- productTags（字符串数组）：产品类别标签\n### 公司筛选\n- seller（字符串）：供应商公司名称\n- sellerCompanyId（整数）：供应商公司ID\n- buyer（字符串）：采购商公司名称\n- buyerCompanyId（整数）：采购商公司ID\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 运输筛选\n- transportModeCodes（数组）：运输方式代码列表\n### 联系方式筛选\n供应商（exist*Seller）和采购商（exist*Buyer）：\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\n- 取值：1（有）、2（无）、0（全部）\n- 例如：existEmailSeller=1  需要供应商有邮箱\n### 其他参数\n- tradeCode（字符串）：提关单号\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n### 排序\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应参数\n\n### 标识字段\n- uuid：唯一标识，记录ID\n- tradeCode：提关单号\n- tradeDate：交易日期（毫秒时间戳）\n\n### 公司标识\n- sellerCompanyId/buyerCompanyId：公司ID\n- seller/buyer：公司名称\n\n### 贸易指标\n- amount：交易金额\n- quantity：交易数量\n- weight：交易重量\n- price：单价\n- *Unit: 指标的单位\n\n### 产品信息\n- productNames：产品名称列表\n- productDesc：产品描述\n- productHscode：产品HS编码\n- productHscodes6：产品HS编码（6位）\n- productCategory：产品类别列表\n- productAlias：产品相似词列表\n- productSuperordinate：产品上游词列表\n- productDownstream：产品下游词列表\n\n### 地理信息\n- sellerCountryInfo: 供应商国家信息\n- buyerCountryInfo: 采购商国家信息\n- originCountryInfo: 起运国信息\n- arrivalCountryInfo: 抵运国信息\n- productCountryInfo: 生产国信息\n- sellerPort/buyerPort: 起运港/抵运港口\n- transportModeCode：运输方式代码\n\nFile v1.0.10:skill-card.md\n\n## Description:\n\nAccess global customs trade data from 220+ countries to search import-export records by company, HS code, product, and country for buyer, supplier, and competitor research.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[upkuajing](https://clawhub.ai/user/upkuajing)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal trade teams and agents use this skill to search UpKuaJing customs shipment data, identify importers or suppliers, review trade records, and enrich selected companies with detail or contact data.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill requires an UpKuaJing API key and may read it from a local `.env` file.\n\nMitigation: Use a protected environment variable or locked-down secret file, and avoid printing API keys or `.env` contents in chat or logs.\n\nRisk: The skill can make paid API calls for searches, company details, and contact lookups.\n\nMitigation: Confirm costs before every query or contact lookup and use the pricing interface or pricing page when exact fee information is needed.\n\nRisk: The skill can retrieve emails, phone numbers, websites, and social profile links.\n\nMitigation: Handle contact data according to applicable privacy, consent, retention, and outreach rules.\n\nRisk: Large searches can persist task metadata and JSONL results locally.\n\nMitigation: Store result files only as needed, restrict access to generated task data, and remove local exports when they are no longer required.\n\nRisk: Error reports can include request context that may expose sensitive query or business information.\n\nMitigation: Send error reports only after user confirmation and exclude secrets, contact data, and unnecessary commercial details from the report context.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search)\n- [Publisher Profile](https://clawhub.ai/user/upkuajing)\n- [UpKuaJing Homepage](https://www.upkuajing.com)\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/)\n- [UpKuaJing API Pricing](https://www.upkuajing.com/web/openapi/price.html)\n- [Company List API Reference](references/company-list-api.md)\n- [Trade List API Reference](references/trade-list-api.md)\n- [Company Detail API Reference](references/company-detail-api.md)\n- [Contact Fetch API Reference](references/contact-fetch-api.md)\n- [Skill Error Report API Reference](references/skill-error-report-api.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, JSON, files]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON or JSONL API results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search scripts may write task metadata and result JSONL files for large queries.]\n\n## Skill Version(s):\n\n1.0.10 (source: server release evidence and skill metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.10:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.9: 15 files, 26388 bytes\n\nFiles: references/company-detail-api.md (1066b), references/company-list-api.md (2993b), references/contact-fetch-api.md (1540b), references/trade-list-api.md (3034b), requirements.txt (13b), scripts/auth.py (5885b), scripts/common.py (14512b), scripts/company_get_contact.py (1484b), scripts/company_get_details.py (1442b), scripts/company_list_search.py (6134b), scripts/trade_list_search.py (5792b), scripts/version_check.py (4933b), skill-card.md (2757b), SKILL.md (11414b), _meta.json (157b)\n\nFile v1.0.9:SKILL.md\n\n---\nname: upkuajing-customs-trade-company-search\ndescription: \"Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business.\\n\\nTrigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search\"\nmetadata: {\"version\":\"1.0.9\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Customs Trade Company Search\n\nSearch 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.\n\n## Overview\n\nThis 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).\nAPI key generation and top-up are provided through the `auth.py` script.\n\n## Running Scripts\n\n### Environment Setup\n\n1. **Check Python**: `python --version`\n2. **Install dependencies**: `pip install -r requirements.txt`\n\nScript directory: `scripts/*.py`\nRun example: `python scripts/*.py`\n\n**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`.\n\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\n\n### Two Search Methods\n\n**Trade List Search** (`trade_list_search.py`)\n- **Return granularity**: Each trade order as one record\n- **Use cases**: Focus on \"what transactions occurred\"\n- **Examples**:\n   - \"Show all orders where Company A purchased LED\"\n   - \"Find soybean trade records imported/exported to US\"\n   - \"View specific transaction details within a time period\"\n- **Parameters**: See [Trade List](references/trade-list-api.md)\n\n\n**Company List Search** (`company_list_search.py`)\n- **Return granularity**: Trade orders aggregated by company, each company as one row\n- **Use cases**: Focus on \"which companies exist\"\n- **Examples**:\n  - \"Find companies that purchased LED\"\n  - \"Find US companies with electronics import/export business with China\"\n  - \"Find companies with China-US trade\" (logistics industry customer development)\n- **Parameters**: See [Company List](references/company-list-api.md)\n\n\n### Two Enhancement Features\n\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\n**Company Details** (`company_get_details.py --companyIds *`)\n- Get company information (excluding contact information)\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Company Details](references/company-detail-api.md)\n\n**Contact Information** (`company_get_contact.py --companyIds *`)\n- Get contact details: email, phone, social media, website\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\n\n## API Key and Top-up\n\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\n```bash\ncat ~/.upkuajing/.env\n```\n**Example file content**:\n```\nUPKUAJING_API_KEY=your_api_key_here\n```\n### **API Key Not Set**\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\n2. 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\nWait for user selection;\n\n### **Account Top-up**\nWhen API response indicates insufficient balance, explain and guide user to top up:\n1. Create top-up order (`auth.py --new_rec_order`)\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\n\n### **Get Account Information**\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\n\n## API Key and UpKuaJing Account\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**All API calls incur fees**, different interfaces have different billing methods.\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\n\n### List Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 20 records:\n- Number of calls: `ceil(query_count / 20)` times\n- **Whenever query_count > 20, must before execution:**\n  1. Inform user of expected number of calls\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Enhancement Interface Billing Rules\n\nBilled by **number of IDs passed**, max 20 IDs per call:\n- Pass 1 ID = billed 1 time\n- Pass 20 IDs = billed 20 times (single call limit)\n- **Before batch retrieval must:**\n  1. Inform user of number of IDs passed and corresponding fee count\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Fee Confirmation Principle\n\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\n\n\n## Workflow\n\nChoose the appropriate API based on user intent\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Analyze trade patterns/order data\" | Trade list |\n| \"Find companies purchasing XXX\" | Company list |\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\n| \"Get company detailed information\" | Company details |\n| \"Get contact information\" | Contact information |\n\n## Usage Examples\n\n### Scenario 1: Small Query — Trade Data Analysis\n\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\n```bash\npython scripts/trade_list_search.py \\\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\n  --query_count 20\n```\n\nTo further get supplier details (supports batch queries):\n```bash\npython scripts/company_get_details.py --companyIds 123456 789012 ...\n```\n\n### Scenario 2: Large Query — Big Data Analysis\n\n**User request**: \"Analyze 100 soybean trade records from 2024\"\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\n```bash\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\n```\n\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\n\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\n```bash\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\n```\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\n```bash\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\n```\n\n## Error Handling\n\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\n\n## Best Practices\n\n### Choosing the Right Method\n\n1. **Understand user intent**:\n   - Analyze trade data? → Use **trade list search**\n   - Find customers/partners? → Use **company list search**\n\n2. **Check API documentation**:\n   - **Before executing list queries, must first check the corresponding API reference documentation**\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\n\n3. **Identify parameter conditions**:\n   - Set date range\n   - HS codes are usually more precise than product names for filtering\n   - Reduce noise by filtering specific countries\n   - Use ISO country codes: CN, US, JP, etc.\n   - Use filters to find companies with contact information\n\n### Handling Results\n\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\n\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\n   - If user only needs a few companies, don't get details for all companies\n\n## Notes\n- All timestamps are in milliseconds\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\n- File paths use forward slashes on all platforms\n- Product names and industry names must be in **English**\n- Search quantity affects API response time, recommend setting timeout:120\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\n\n## Related Skills\n\nOther UpKuaJing skills you might find useful:\n\n- linkedin-person-search — Search people from the LinkedIn source\n- global-company-person-search — Search people from the global company database\n- linkedin-company-search — Search companies from the LinkedIn source\n- global-company-search — Search companies from the global company database\n- global-company-shareholder — Query shareholder list from the global company database\n- global-company-employee — Query employee list from the global company database\n- global-company-person-colleague — Query colleague list from the global company database\n- global-company-person-alumni — Query alumni list from the global company database\n- global-company-person-experience — Query work experience list from the global company database\n- global-company-person-education — Query education history list from the global company database\n- global-company-person-school-detail — Query school detail from the global company database\n- upkuajing-global-company-people-search — Global company and people search\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-map-merchants-search — Map-based merchant search\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n- phone-validity-check — Check phone number validity\n- email-validity-check — Check email address validity\n- domain-validity-check — Check domain validity and security\n\nFile v1.0.9:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.9\",\n  \"publishedAt\": 1784192192115\n}\n\nFile v1.0.9:references/company-detail-api.md\n\n# 公司详情 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n\n### 基本信息\n- companyId：公司编号\n- name：公司名\n- logo：公司logo\n- introduce：公司介绍\n- industry：行业\n- scope：经营范围\n\n### 位置信息\n- location：公司位置\n- country：国家\n- province：省、州\n- city：城市\n- address：地址\n- postcode：邮编\n\n### 注册信息\n- registerPerson：注册法人\n- registerNumber：注册编号\n- registerDate：注册日期\n- registerType：注册类型\n- registerCapital：注册资金\n- registerState：注册状态\n\n### 贸易信息\n- companyType：公司贸易类型\n  - 0：未知\n  - 1：供应商\n  - 2：采购商\n  - 3：采购商和供应商\n\n### 国家信息\n- country.id：国家编号\n- country.name_cn：国家中文名\n- country.name_en：国家英文名\n- country.code_iso2：国家二字码\n- country.icon：国旗链接\n\nFile v1.0.9:references/company-list-api.md\n\n# 公司列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 必需参数\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（数组）：产品名称列表\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\n- productSuperordinate（数组）：产品的上游产品名称列表\n- productDownstream（数组）：产品的下游产品名称列表\n### 公司筛选\n- sellerIds（数组）：供应商公司ID列表\n- buyerIds（数组）：采购商公司ID列表\n- seller（字符串）：供应商公司名称\n- buyer（字符串）：采购商公司名称\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 联系方式筛选\n- existPhone：1（有电话），2（无电话），0（全部）\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\n- existWebsite：1（有网站），2（无网站），0（全部）\n- existSocial：1（有社媒），2（无社媒），0（全部）\n### 其他参数\n- tradeCode（字符串）：提关单号\n- minTradeCount（整数）：最小贸易频次数量\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n\n### 排序\n- sorting_field：tradeCount（默认）、latestTradeDate\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应\n\n### 公司标识\n- companyId：公司ID\n- companyType：1（供应商），2（采购商）\n- name：公司名称\n### 贸易统计\n- tradeTotal：贸易总量\n- tradeMatchTotal：匹配贸易量\n- tradeMatchPercent：匹配贸易占比（%）\n- latestTradeDate：最后贸易日期（毫秒时间戳）\n### 公司信息\n- countryInfo：所属国信息\n- scope：公司主营\n- address：公司地址\n### 产品信息\n- productDesc：产品描述\n- productTag：产品标签列表\n- productNames：标准化产品名称\n- productAlias：产品别名\n- productSuperordinate：产品的上游产品名称列表\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.9:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n- companyId：公司编号\n\n### 邮箱信息 emails\n- val：邮箱地址\n- is_valid：是否有效\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- reason：原因\n\n### 电话信息 phones\n- val：电话号码\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_ws：是否WhatsApp\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- phone_type：号码类型\n  - 0：未检测\n  - 1：固定电话\n  - 2：移动电话\n  - 3：已检测但未知\n- country_code：电话所属国家二字码\n- dialing_code：电话所属国际冠码\n- area_code：电话所属地区码\n- international_number：国际格式号码\n- telephone：号码(去除冠码与区码)\n- national_number：号码属国格式\n\n### 社交媒体信息 socials\n- val：社媒完整链接\n- social_url：社媒链接路径\n- social_type：社媒链接类型\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- reason：原因\n\n### 网站信息 websites\n- val：网址\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_sensitive：是否敏感\n  - 0：未检测\n  - 1：是（如电子商务网站）\n  - 2：否\n  - 3：不确定\n- reason：原因\n\nFile v1.0.9:references/trade-list-api.md\n\n# 贸易列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（字符串数组）：产品名称列表\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\n- productTags（字符串数组）：产品类别标签\n### 公司筛选\n- seller（字符串）：供应商公司名称\n- sellerCompanyId（整数）：供应商公司ID\n- buyer（字符串）：采购商公司名称\n- buyerCompanyId（整数）：采购商公司ID\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 运输筛选\n- transportModeCodes（数组）：运输方式代码列表\n### 联系方式筛选\n供应商（exist*Seller）和采购商（exist*Buyer）：\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\n- 取值：1（有）、2（无）、0（全部）\n- 例如：existEmailSeller=1  需要供应商有邮箱\n### 其他参数\n- tradeCode（字符串）：提关单号\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n### 排序\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应参数\n\n### 标识字段\n- uuid：唯一标识，记录ID\n- tradeCode：提关单号\n- tradeDate：交易日期（毫秒时间戳）\n\n### 公司标识\n- sellerCompanyId/buyerCompanyId：公司ID\n- seller/buyer：公司名称\n\n### 贸易指标\n- amount：交易金额\n- quantity：交易数量\n- weight：交易重量\n- price：单价\n- *Unit: 指标的单位\n\n### 产品信息\n- productNames：产品名称列表\n- productDesc：产品描述\n- productHscode：产品HS编码\n- productHscodes6：产品HS编码（6位）\n- productCategory：产品类别列表\n- productAlias：产品相似词列表\n- productSuperordinate：产品上游词列表\n- productDownstream：产品下游词列表\n\n### 地理信息\n- sellerCountryInfo: 供应商国家信息\n- buyerCountryInfo: 采购商国家信息\n- originCountryInfo: 起运国信息\n- arrivalCountryInfo: 抵运国信息\n- productCountryInfo: 生产国信息\n- sellerPort/buyerPort: 起运港/抵运港口\n- transportModeCode：运输方式代码\n\nFile v1.0.9:skill-card.md\n\n## Description: <br>\nAccess global customs trade data from 220+ countries to search import-export records by company, HS code, or product and identify buyers, suppliers, and competitor trade activity. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[upkuajing](https://clawhub.ai/user/upkuajing) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal trade, sales, and sourcing teams use this skill to find international buyers or suppliers, inspect customs shipment history, enrich company records, and monitor competitor cross-border activity. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill uses an UpKuaJing API key that may be stored locally. <br>\nMitigation: Protect ~/.upkuajing/.env as a secret file and avoid sharing API-key values in prompts, logs, or support requests. <br>\nRisk: Search and enrichment operations can incur paid API charges. <br>\nMitigation: Review fee prompts, expected call counts, pricing information, and account balance before approving searches or enrichment calls. <br>\nRisk: Company contact-data retrieval may raise privacy, outreach, or compliance obligations. <br>\nMitigation: Use retrieved emails, phone numbers, social profiles, and websites under applicable privacy, anti-spam, and business-outreach rules. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search) <br>\n- [UpKuaJing Homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html) <br>\n- [Company Detail API Reference](references/company-detail-api.md) <br>\n- [Company List API Reference](references/company-list-api.md) <br>\n- [Contact Fetch API Reference](references/contact-fetch-api.md) <br>\n- [Trade List API Reference](references/trade-list-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with shell commands and JSON or JSONL API results] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Search tasks may write JSONL result files and return task IDs, fee information, balances, and file paths.] <br>\n\n## Skill Version(s): <br>\n1.0.9 (source: evidence.release.version and SKILL.md metadata.version) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.9:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.8: 15 files, 26653 bytes\n\nFiles: references/company-detail-api.md (1066b), references/company-list-api.md (2993b), references/contact-fetch-api.md (1540b), references/trade-list-api.md (3034b), requirements.txt (13b), scripts/auth.py (5885b), scripts/common.py (14512b), scripts/company_get_contact.py (1484b), scripts/company_get_details.py (1442b), scripts/company_list_search.py (6134b), scripts/trade_list_search.py (5792b), scripts/version_check.py (4933b), skill-card.md (3403b), SKILL.md (11414b), _meta.json (157b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: upkuajing-customs-trade-company-search\ndescription: \"Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business.\\n\\nTrigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search\"\nmetadata: {\"version\":\"1.0.8\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Customs Trade Company Search\n\nSearch 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.\n\n## Overview\n\nThis 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).\nAPI key generation and top-up are provided through the `auth.py` script.\n\n## Running Scripts\n\n### Environment Setup\n\n1. **Check Python**: `python --version`\n2. **Install dependencies**: `pip install -r requirements.txt`\n\nScript directory: `scripts/*.py`\nRun example: `python scripts/*.py`\n\n**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`.\n\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\n\n### Two Search Methods\n\n**Trade List Search** (`trade_list_search.py`)\n- **Return granularity**: Each trade order as one record\n- **Use cases**: Focus on \"what transactions occurred\"\n- **Examples**:\n   - \"Show all orders where Company A purchased LED\"\n   - \"Find soybean trade records imported/exported to US\"\n   - \"View specific transaction details within a time period\"\n- **Parameters**: See [Trade List](references/trade-list-api.md)\n\n\n**Company List Search** (`company_list_search.py`)\n- **Return granularity**: Trade orders aggregated by company, each company as one row\n- **Use cases**: Focus on \"which companies exist\"\n- **Examples**:\n  - \"Find companies that purchased LED\"\n  - \"Find US companies with electronics import/export business with China\"\n  - \"Find companies with China-US trade\" (logistics industry customer development)\n- **Parameters**: See [Company List](references/company-list-api.md)\n\n\n### Two Enhancement Features\n\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\n**Company Details** (`company_get_details.py --companyIds *`)\n- Get company information (excluding contact information)\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Company Details](references/company-detail-api.md)\n\n**Contact Information** (`company_get_contact.py --companyIds *`)\n- Get contact details: email, phone, social media, website\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\n\n## API Key and Top-up\n\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\n```bash\ncat ~/.upkuajing/.env\n```\n**Example file content**:\n```\nUPKUAJING_API_KEY=your_api_key_here\n```\n### **API Key Not Set**\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\n2. 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\nWait for user selection;\n\n### **Account Top-up**\nWhen API response indicates insufficient balance, explain and guide user to top up:\n1. Create top-up order (`auth.py --new_rec_order`)\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\n\n### **Get Account Information**\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\n\n## API Key and UpKuaJing Account\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**All API calls incur fees**, different interfaces have different billing methods.\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\n\n### List Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 20 records:\n- Number of calls: `ceil(query_count / 20)` times\n- **Whenever query_count > 20, must before execution:**\n  1. Inform user of expected number of calls\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Enhancement Interface Billing Rules\n\nBilled by **number of IDs passed**, max 20 IDs per call:\n- Pass 1 ID = billed 1 time\n- Pass 20 IDs = billed 20 times (single call limit)\n- **Before batch retrieval must:**\n  1. Inform user of number of IDs passed and corresponding fee count\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Fee Confirmation Principle\n\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\n\n\n## Workflow\n\nChoose the appropriate API based on user intent\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Analyze trade patterns/order data\" | Trade list |\n| \"Find companies purchasing XXX\" | Company list |\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\n| \"Get company detailed information\" | Company details |\n| \"Get contact information\" | Contact information |\n\n## Usage Examples\n\n### Scenario 1: Small Query — Trade Data Analysis\n\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\n```bash\npython scripts/trade_list_search.py \\\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\n  --query_count 20\n```\n\nTo further get supplier details (supports batch queries):\n```bash\npython scripts/company_get_details.py --companyIds 123456 789012 ...\n```\n\n### Scenario 2: Large Query — Big Data Analysis\n\n**User request**: \"Analyze 100 soybean trade records from 2024\"\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\n```bash\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\n```\n\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\n\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\n```bash\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\n```\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\n```bash\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\n```\n\n## Error Handling\n\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\n\n## Best Practices\n\n### Choosing the Right Method\n\n1. **Understand user intent**:\n   - Analyze trade data? → Use **trade list search**\n   - Find customers/partners? → Use **company list search**\n\n2. **Check API documentation**:\n   - **Before executing list queries, must first check the corresponding API reference documentation**\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\n\n3. **Identify parameter conditions**:\n   - Set date range\n   - HS codes are usually more precise than product names for filtering\n   - Reduce noise by filtering specific countries\n   - Use ISO country codes: CN, US, JP, etc.\n   - Use filters to find companies with contact information\n\n### Handling Results\n\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\n\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\n   - If user only needs a few companies, don't get details for all companies\n\n## Notes\n- All timestamps are in milliseconds\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\n- File paths use forward slashes on all platforms\n- Product names and industry names must be in **English**\n- Search quantity affects API response time, recommend setting timeout:120\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\n\n## Related Skills\n\nOther UpKuaJing skills you might find useful:\n\n- linkedin-person-search — Search people from the LinkedIn source\n- global-company-person-search — Search people from the global company database\n- linkedin-company-search — Search companies from the LinkedIn source\n- global-company-search — Search companies from the global company database\n- global-company-shareholder — Query shareholder list from the global company database\n- global-company-employee — Query employee list from the global company database\n- global-company-person-colleague — Query colleague list from the global company database\n- global-company-person-alumni — Query alumni list from the global company database\n- global-company-person-experience — Query work experience list from the global company database\n- global-company-person-education — Query education history list from the global company database\n- global-company-person-school-detail — Query school detail from the global company database\n- upkuajing-global-company-people-search — Global company and people search\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-map-merchants-search — Map-based merchant search\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n- phone-validity-check — Check phone number validity\n- email-validity-check — Check email address validity\n- domain-validity-check — Check domain validity and security\n\nFile v1.0.8:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.8\",\n  \"publishedAt\": 1784182619548\n}\n\nFile v1.0.8:references/company-detail-api.md\n\n# 公司详情 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n\n### 基本信息\n- companyId：公司编号\n- name：公司名\n- logo：公司logo\n- introduce：公司介绍\n- industry：行业\n- scope：经营范围\n\n### 位置信息\n- location：公司位置\n- country：国家\n- province：省、州\n- city：城市\n- address：地址\n- postcode：邮编\n\n### 注册信息\n- registerPerson：注册法人\n- registerNumber：注册编号\n- registerDate：注册日期\n- registerType：注册类型\n- registerCapital：注册资金\n- registerState：注册状态\n\n### 贸易信息\n- companyType：公司贸易类型\n  - 0：未知\n  - 1：供应商\n  - 2：采购商\n  - 3：采购商和供应商\n\n### 国家信息\n- country.id：国家编号\n- country.name_cn：国家中文名\n- country.name_en：国家英文名\n- country.code_iso2：国家二字码\n- country.icon：国旗链接\n\nFile v1.0.8:references/company-list-api.md\n\n# 公司列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 必需参数\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（数组）：产品名称列表\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\n- productSuperordinate（数组）：产品的上游产品名称列表\n- productDownstream（数组）：产品的下游产品名称列表\n### 公司筛选\n- sellerIds（数组）：供应商公司ID列表\n- buyerIds（数组）：采购商公司ID列表\n- seller（字符串）：供应商公司名称\n- buyer（字符串）：采购商公司名称\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 联系方式筛选\n- existPhone：1（有电话），2（无电话），0（全部）\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\n- existWebsite：1（有网站），2（无网站），0（全部）\n- existSocial：1（有社媒），2（无社媒），0（全部）\n### 其他参数\n- tradeCode（字符串）：提关单号\n- minTradeCount（整数）：最小贸易频次数量\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n\n### 排序\n- sorting_field：tradeCount（默认）、latestTradeDate\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应\n\n### 公司标识\n- companyId：公司ID\n- companyType：1（供应商），2（采购商）\n- name：公司名称\n### 贸易统计\n- tradeTotal：贸易总量\n- tradeMatchTotal：匹配贸易量\n- tradeMatchPercent：匹配贸易占比（%）\n- latestTradeDate：最后贸易日期（毫秒时间戳）\n### 公司信息\n- countryInfo：所属国信息\n- scope：公司主营\n- address：公司地址\n### 产品信息\n- productDesc：产品描述\n- productTag：产品标签列表\n- productNames：标准化产品名称\n- productAlias：产品别名\n- productSuperordinate：产品的上游产品名称列表\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.8:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n- companyId：公司编号\n\n### 邮箱信息 emails\n- val：邮箱地址\n- is_valid：是否有效\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- reason：原因\n\n### 电话信息 phones\n- val：电话号码\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_ws：是否WhatsApp\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- phone_type：号码类型\n  - 0：未检测\n  - 1：固定电话\n  - 2：移动电话\n  - 3：已检测但未知\n- country_code：电话所属国家二字码\n- dialing_code：电话所属国际冠码\n- area_code：电话所属地区码\n- international_number：国际格式号码\n- telephone：号码(去除冠码与区码)\n- national_number：号码属国格式\n\n### 社交媒体信息 socials\n- val：社媒完整链接\n- social_url：社媒链接路径\n- social_type：社媒链接类型\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- reason：原因\n\n### 网站信息 websites\n- val：网址\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_sensitive：是否敏感\n  - 0：未检测\n  - 1：是（如电子商务网站）\n  - 2：否\n  - 3：不确定\n- reason：原因\n\nFile v1.0.8:references/trade-list-api.md\n\n# 贸易列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（字符串数组）：产品名称列表\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\n- productTags（字符串数组）：产品类别标签\n### 公司筛选\n- seller（字符串）：供应商公司名称\n- sellerCompanyId（整数）：供应商公司ID\n- buyer（字符串）：采购商公司名称\n- buyerCompanyId（整数）：采购商公司ID\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 运输筛选\n- transportModeCodes（数组）：运输方式代码列表\n### 联系方式筛选\n供应商（exist*Seller）和采购商（exist*Buyer）：\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\n- 取值：1（有）、2（无）、0（全部）\n- 例如：existEmailSeller=1  需要供应商有邮箱\n### 其他参数\n- tradeCode（字符串）：提关单号\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n### 排序\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应参数\n\n### 标识字段\n- uuid：唯一标识，记录ID\n- tradeCode：提关单号\n- tradeDate：交易日期（毫秒时间戳）\n\n### 公司标识\n- sellerCompanyId/buyerCompanyId：公司ID\n- seller/buyer：公司名称\n\n### 贸易指标\n- amount：交易金额\n- quantity：交易数量\n- weight：交易重量\n- price：单价\n- *Unit: 指标的单位\n\n### 产品信息\n- productNames：产品名称列表\n- productDesc：产品描述\n- productHscode：产品HS编码\n- productHscodes6：产品HS编码（6位）\n- productCategory：产品类别列表\n- productAlias：产品相似词列表\n- productSuperordinate：产品上游词列表\n- productDownstream：产品下游词列表\n\n### 地理信息\n- sellerCountryInfo: 供应商国家信息\n- buyerCountryInfo: 采购商国家信息\n- originCountryInfo: 起运国信息\n- arrivalCountryInfo: 抵运国信息\n- productCountryInfo: 生产国信息\n- sellerPort/buyerPort: 起运港/抵运港口\n- transportModeCode：运输方式代码\n\nFile v1.0.8:skill-card.md\n\n## Description: <br>\nAccess global customs trade data from 220+ countries to search import-export records by company, HS code, and product, find potential buyers or suppliers, enrich company details, and retrieve contact information through the UpKuaJing Open Platform API. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[upkuajing](https://clawhub.ai/user/upkuajing) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal trade teams and agents use this skill to search customs transaction records, identify product-specific buyers and suppliers, monitor competitors, and enrich company records with details or contact channels. It is suited to paid UpKuaJing API workflows where the user has authorized API access and confirms fee-incurring queries before execution. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill uses a paid API and large searches or contact-enrichment calls can incur charges. <br>\nMitigation: Confirm the expected number of API calls or company IDs with the user before running fee-incurring queries, and use the pricing command or published pricing page rather than estimating fees. <br>\nRisk: The API key is sensitive and may be stored in ~/.upkuajing/.env. <br>\nMitigation: Treat the local environment file as secret material, avoid printing or sharing the full key, and prefer existing configured credentials when available. <br>\nRisk: Search results may contain business contact data and trade records that require careful handling. <br>\nMitigation: Share only the fields needed for the user's task, avoid unnecessary batch enrichment, and handle generated JSONL result files as potentially sensitive data. <br>\nRisk: Top-up workflows can return payment URLs. <br>\nMitigation: Review payment URLs before opening them and require user confirmation before payment-related actions. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search) <br>\n- [UpKuaJing homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html) <br>\n- [Trade List API Reference](references/trade-list-api.md) <br>\n- [Company List API Reference](references/company-list-api.md) <br>\n- [Company Detail API Reference](references/company-detail-api.md) <br>\n- [Contact Fetch API Reference](references/contact-fetch-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, API calls, files] <br>\n**Output Format:** [Markdown guidance with inline shell commands; scripts emit JSON summaries and JSONL result files for search tasks.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires Python, httpx, and UPKUAJING_API_KEY; list searches write task metadata and result.jsonl files under the skill task_data directory.] <br>\n\n## Skill Version(s): <br>\n1.0.8 (source: server release evidence and SKILL.md metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.8:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.7: 15 files, 26190 bytes\n\nFiles: references/company-detail-api.md (1066b), references/company-list-api.md (2993b), references/contact-fetch-api.md (1540b), references/trade-list-api.md (3034b), requirements.txt (13b), scripts/auth.py (5885b), scripts/common.py (14512b), scripts/company_get_contact.py (1484b), scripts/company_get_details.py (1442b), scripts/company_list_search.py (6134b), scripts/trade_list_search.py (5792b), scripts/version_check.py (4933b), skill-card.md (2827b), SKILL.md (10190b), _meta.json (157b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: upkuajing-customs-trade-company-search\ndescription: Official skill for upkuajing (跨境魔方). Find companies (找公司) and global buyers using customs trade data. Get trade order details, business contact info, and lead generation tools for import/export market research and supply chain analysis.\nmetadata: {\"version\":\"1.0.7\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Customs Trade Company Search\n\nSearch 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.\n\n## Overview\n\nThis 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).\nAPI key generation and top-up are provided through the `auth.py` script.\n\n## Running Scripts\n\n### Environment Setup\n\n1. **Check Python**: `python --version`\n2. **Install dependencies**: `pip install -r requirements.txt`\n\nScript directory: `scripts/*.py`\nRun example: `python scripts/*.py`\n\n**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`.\n\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\n\n### Two Search Methods\n\n**Trade List Search** (`trade_list_search.py`)\n- **Return granularity**: Each trade order as one record\n- **Use cases**: Focus on \"what transactions occurred\"\n- **Examples**:\n   - \"Show all orders where Company A purchased LED\"\n   - \"Find soybean trade records imported/exported to US\"\n   - \"View specific transaction details within a time period\"\n- **Parameters**: See [Trade List](references/trade-list-api.md)\n\n\n**Company List Search** (`company_list_search.py`)\n- **Return granularity**: Trade orders aggregated by company, each company as one row\n- **Use cases**: Focus on \"which companies exist\"\n- **Examples**:\n  - \"Find companies that purchased LED\"\n  - \"Find US companies with electronics import/export business with China\"\n  - \"Find companies with China-US trade\" (logistics industry customer development)\n- **Parameters**: See [Company List](references/company-list-api.md)\n\n\n### Two Enhancement Features\n\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\n**Company Details** (`company_get_details.py --companyIds *`)\n- Get company information (excluding contact information)\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Company Details](references/company-detail-api.md)\n\n**Contact Information** (`company_get_contact.py --companyIds *`)\n- Get contact details: email, phone, social media, website\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\n\n## API Key and Top-up\n\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\n```bash\ncat ~/.upkuajing/.env\n```\n**Example file content**:\n```\nUPKUAJING_API_KEY=your_api_key_here\n```\n### **API Key Not Set**\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\n2. 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\nWait for user selection;\n\n### **Account Top-up**\nWhen API response indicates insufficient balance, explain and guide user to top up:\n1. Create top-up order (`auth.py --new_rec_order`)\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\n\n### **Get Account Information**\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\n\n## API Key and UpKuaJing Account\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**All API calls incur fees**, different interfaces have different billing methods.\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\n\n### List Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 20 records:\n- Number of calls: `ceil(query_count / 20)` times\n- **Whenever query_count > 20, must before execution:**\n  1. Inform user of expected number of calls\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Enhancement Interface Billing Rules\n\nBilled by **number of IDs passed**, max 20 IDs per call:\n- Pass 1 ID = billed 1 time\n- Pass 20 IDs = billed 20 times (single call limit)\n- **Before batch retrieval must:**\n  1. Inform user of number of IDs passed and corresponding fee count\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\n\n### Fee Confirmation Principle\n\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\n\n\n## Workflow\n\nChoose the appropriate API based on user intent\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Analyze trade patterns/order data\" | Trade list |\n| \"Find companies purchasing XXX\" | Company list |\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\n| \"Get company detailed information\" | Company details |\n| \"Get contact information\" | Contact information |\n\n## Usage Examples\n\n### Scenario 1: Small Query — Trade Data Analysis\n\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\n```bash\npython scripts/trade_list_search.py \\\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\n  --query_count 20\n```\n\nTo further get supplier details (supports batch queries):\n```bash\npython scripts/company_get_details.py --companyIds 123456 789012 ...\n```\n\n### Scenario 2: Large Query — Big Data Analysis\n\n**User request**: \"Analyze 100 soybean trade records from 2024\"\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\n```bash\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\n```\n\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\n\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\n```bash\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\n```\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\n```bash\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\n```\n\n## Error Handling\n\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\n\n## Best Practices\n\n### Choosing the Right Method\n\n1. **Understand user intent**:\n   - Analyze trade data? → Use **trade list search**\n   - Find customers/partners? → Use **company list search**\n\n2. **Check API documentation**:\n   - **Before executing list queries, must first check the corresponding API reference documentation**\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\n\n3. **Identify parameter conditions**:\n   - Set date range\n   - HS codes are usually more precise than product names for filtering\n   - Reduce noise by filtering specific countries\n   - Use ISO country codes: CN, US, JP, etc.\n   - Use filters to find companies with contact information\n\n### Handling Results\n\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\n\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\n   - If user only needs a few companies, don't get details for all companies\n\n## Notes\n- All timestamps are in milliseconds\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\n- File paths use forward slashes on all platforms\n- Product names and industry names must be in **English**\n- Search quantity affects API response time, recommend setting timeout:120\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\n\n## Related Skills\n\nOther UpKuaJing skills you might find useful:\n\n- upkuajing-global-company-people-search — Global company and people search\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-map-merchants-search — Map-based merchant search\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n\nFile v1.0.7:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.7\",\n  \"publishedAt\": 1783310348850\n}\n\nFile v1.0.7:references/company-detail-api.md\n\n# 公司详情 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n\n### 基本信息\n- companyId：公司编号\n- name：公司名\n- logo：公司logo\n- introduce：公司介绍\n- industry：行业\n- scope：经营范围\n\n### 位置信息\n- location：公司位置\n- country：国家\n- province：省、州\n- city：城市\n- address：地址\n- postcode：邮编\n\n### 注册信息\n- registerPerson：注册法人\n- registerNumber：注册编号\n- registerDate：注册日期\n- registerType：注册类型\n- registerCapital：注册资金\n- registerState：注册状态\n\n### 贸易信息\n- companyType：公司贸易类型\n  - 0：未知\n  - 1：供应商\n  - 2：采购商\n  - 3：采购商和供应商\n\n### 国家信息\n- country.id：国家编号\n- country.name_cn：国家中文名\n- country.name_en：国家英文名\n- country.code_iso2：国家二字码\n- country.icon：国旗链接\n\nFile v1.0.7:references/company-list-api.md\n\n# 公司列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 必需参数\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（数组）：产品名称列表\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\n- productSuperordinate（数组）：产品的上游产品名称列表\n- productDownstream（数组）：产品的下游产品名称列表\n### 公司筛选\n- sellerIds（数组）：供应商公司ID列表\n- buyerIds（数组）：采购商公司ID列表\n- seller（字符串）：供应商公司名称\n- buyer（字符串）：采购商公司名称\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 联系方式筛选\n- existPhone：1（有电话），2（无电话），0（全部）\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\n- existWebsite：1（有网站），2（无网站），0（全部）\n- existSocial：1（有社媒），2（无社媒），0（全部）\n### 其他参数\n- tradeCode（字符串）：提关单号\n- minTradeCount（整数）：最小贸易频次数量\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n\n### 排序\n- sorting_field：tradeCount（默认）、latestTradeDate\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应\n\n### 公司标识\n- companyId：公司ID\n- companyType：1（供应商），2（采购商）\n- name：公司名称\n### 贸易统计\n- tradeTotal：贸易总量\n- tradeMatchTotal：匹配贸易量\n- tradeMatchPercent：匹配贸易占比（%）\n- latestTradeDate：最后贸易日期（毫秒时间戳）\n### 公司信息\n- countryInfo：所属国信息\n- scope：公司主营\n- address：公司地址\n### 产品信息\n- productDesc：产品描述\n- productTag：产品标签列表\n- productNames：标准化产品名称\n- productAlias：产品别名\n- productSuperordinate：产品的上游产品名称列表\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.7:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n- companyId：公司编号\n\n### 邮箱信息 emails\n- val：邮箱地址\n- is_valid：是否有效\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- reason：原因\n\n### 电话信息 phones\n- val：电话号码\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_ws：是否WhatsApp\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- phone_type：号码类型\n  - 0：未检测\n  - 1：固定电话\n  - 2：移动电话\n  - 3：已检测但未知\n- country_code：电话所属国家二字码\n- dialing_code：电话所属国际冠码\n- area_code：电话所属地区码\n- international_number：国际格式号码\n- telephone：号码(去除冠码与区码)\n- national_number：号码属国格式\n\n### 社交媒体信息 socials\n- val：社媒完整链接\n- social_url：社媒链接路径\n- social_type：社媒链接类型\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- reason：原因\n\n### 网站信息 websites\n- val：网址\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_sensitive：是否敏感\n  - 0：未检测\n  - 1：是（如电子商务网站）\n  - 2：否\n  - 3：不确定\n- reason：原因\n\nFile v1.0.7:references/trade-list-api.md\n\n# 贸易列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（字符串数组）：产品名称列表\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\n- productTags（字符串数组）：产品类别标签\n### 公司筛选\n- seller（字符串）：供应商公司名称\n- sellerCompanyId（整数）：供应商公司ID\n- buyer（字符串）：采购商公司名称\n- buyerCompanyId（整数）：采购商公司ID\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 运输筛选\n- transportModeCodes（数组）：运输方式代码列表\n### 联系方式筛选\n供应商（exist*Seller）和采购商（exist*Buyer）：\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\n- 取值：1（有）、2（无）、0（全部）\n- 例如：existEmailSeller=1  需要供应商有邮箱\n### 其他参数\n- tradeCode（字符串）：提关单号\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n### 排序\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应参数\n\n### 标识字段\n- uuid：唯一标识，记录ID\n- tradeCode：提关单号\n- tradeDate：交易日期（毫秒时间戳）\n\n### 公司标识\n- sellerCompanyId/buyerCompanyId：公司ID\n- seller/buyer：公司名称\n\n### 贸易指标\n- amount：交易金额\n- quantity：交易数量\n- weight：交易重量\n- price：单价\n- *Unit: 指标的单位\n\n### 产品信息\n- productNames：产品名称列表\n- productDesc：产品描述\n- productHscode：产品HS编码\n- productHscodes6：产品HS编码（6位）\n- productCategory：产品类别列表\n- productAlias：产品相似词列表\n- productSuperordinate：产品上游词列表\n- productDownstream：产品下游词列表\n\n### 地理信息\n- sellerCountryInfo: 供应商国家信息\n- buyerCountryInfo: 采购商国家信息\n- originCountryInfo: 起运国信息\n- arrivalCountryInfo: 抵运国信息\n- productCountryInfo: 生产国信息\n- sellerPort/buyerPort: 起运港/抵运港口\n- transportModeCode：运输方式代码\n\nFile v1.0.7:skill-card.md\n\n## Description: <br>\nUpKuaJing helps foreign trade teams search global customs records to find active buyers, verify suppliers, analyze shipment flows, and turn trade intelligence into high-intent B2B leads. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[upkuajing](https://clawhub.ai/user/upkuajing) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal trade, sourcing, and business-development teams use this skill to query UpKuaJing customs trade data, identify import/export companies, enrich company records, and retrieve contact details when appropriate. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill uses a paid UpKuaJing API account, so searches and enrichment calls can incur costs. <br>\nMitigation: Confirm fee-bearing queries with the user before execution and use the pricing script or pricing page for current fee details. <br>\nRisk: The UpKuaJing API key can be exposed if local environment files are shared or logged. <br>\nMitigation: Set UPKUAJING_API_KEY through a normal secret manager where possible, restrict access to ~/.upkuajing/.env, and avoid sharing that file. <br>\nRisk: Saved task_data result files may contain sensitive trade leads or company contact details. <br>\nMitigation: Review, protect, and clean up saved result files after use according to the user's data-handling requirements. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/upkuajing/skills/upkuajing-customs-trade-company-search) <br>\n- [UpKuaJing Homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [UpKuaJing API Pricing](https://www.upkuajing.com/web/openapi/price.html) <br>\n- [Company Detail API Reference](references/company-detail-api.md) <br>\n- [Company List API Reference](references/company-list-api.md) <br>\n- [Contact Fetch API Reference](references/contact-fetch-api.md) <br>\n- [Trade List API Reference](references/trade-list-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with inline shell commands and references to JSONL result files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires Python and UPKUAJING_API_KEY; paid API queries require explicit user confirmation before execution.] <br>\n\n## Skill Version(s): <br>\n1.0.7 (source: server release metadata and skill metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.7:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.6: 15 files, 26354 bytes\n\nFiles: references/company-detail-api.md (1115b), references/company-list-api.md (3062b), references/contact-fetch-api.md (1599b), references/trade-list-api.md (3112b), requirements.txt (13b), scripts/auth.py (6058b), scripts/common.py (14512b), scripts/company_get_contact.py (1478b), scripts/company_get_details.py (1436b), scripts/company_list_search.py (6128b), scripts/trade_list_search.py (5786b), scripts/version_check.py (4927b), skill-card.md (2947b), SKILL.md (10414b), _meta.json (157b)\n\nFile v1.0.6:SKILL.md\n\n---\r\nname: upkuajing-customs-trade-company-search\r\ndescription: Official skill for upkuajing (跨境魔方). Find companies (找公司) and global buyers using customs trade data. Get trade order details, business contact info, and lead generation tools for import/export market research and supply chain analysis.\r\nmetadata: {\"version\":\"1.0.6\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\r\n---\r\n\r\n# UpKuaJing Customs Trade Company Search\r\n\r\nSearch 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.\r\n\r\n## Overview\r\n\r\nThis 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).\r\nAPI key generation and top-up are provided through the `auth.py` script.\r\n\r\n## Running Scripts\r\n\r\n### Environment Setup\r\n\r\n1. **Check Python**: `python --version`\r\n2. **Install dependencies**: `pip install -r requirements.txt`\r\n\r\nScript directory: `scripts/*.py`\r\nRun example: `python scripts/*.py`\r\n\r\n**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`.\r\n\r\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\r\n\r\n### Two Search Methods\r\n\r\n**Trade List Search** (`trade_list_search.py`)\r\n- **Return granularity**: Each trade order as one record\r\n- **Use cases**: Focus on \"what transactions occurred\"\r\n- **Examples**:\r\n   - \"Show all orders where Company A purchased LED\"\r\n   - \"Find soybean trade records imported/exported to US\"\r\n   - \"View specific transaction details within a time period\"\r\n- **Parameters**: See [Trade List](references/trade-list-api.md)\r\n\r\n\r\n**Company List Search** (`company_list_search.py`)\r\n- **Return granularity**: Trade orders aggregated by company, each company as one row\r\n- **Use cases**: Focus on \"which companies exist\"\r\n- **Examples**:\r\n  - \"Find companies that purchased LED\"\r\n  - \"Find US companies with electronics import/export business with China\"\r\n  - \"Find companies with China-US trade\" (logistics industry customer development)\r\n- **Parameters**: See [Company List](references/company-list-api.md)\r\n\r\n\r\n### Two Enhancement Features\r\n\r\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\r\n**Company Details** (`company_get_details.py --companyIds *`)\r\n- Get company information (excluding contact information)\r\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\r\n- **API business parameters**: [Company Details](references/company-detail-api.md)\r\n\r\n**Contact Information** (`company_get_contact.py --companyIds *`)\r\n- Get contact details: email, phone, social media, website\r\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\r\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\r\n\r\n## API Key and Top-up\r\n\r\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\r\n```bash\r\ncat ~/.upkuajing/.env\r\n```\r\n**Example file content**:\r\n```\r\nUPKUAJING_API_KEY=your_api_key_here\r\n```\r\n### **API Key Not Set**\r\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\r\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\r\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\r\n2. 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\r\nWait for user selection;\r\n\r\n### **Account Top-up**\r\nWhen API response indicates insufficient balance, explain and guide user to top up:\r\n1. Create top-up order (`auth.py --new_rec_order`)\r\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\r\n\r\n### **Get Account Information**\r\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\r\n\r\n## API Key and UpKuaJing Account\r\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\r\n\r\n## Fees\r\n\r\n**All API calls incur fees**, different interfaces have different billing methods.\r\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\r\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\r\n\r\n### List Search Billing Rules\r\n\r\nBilled by **number of calls**, each call returns up to 20 records:\r\n- Number of calls: `ceil(query_count / 20)` times\r\n- **Whenever query_count > 20, must before execution:**\r\n  1. Inform user of expected number of calls\r\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\r\n\r\n### Enhancement Interface Billing Rules\r\n\r\nBilled by **number of IDs passed**, max 20 IDs per call:\r\n- Pass 1 ID = billed 1 time\r\n- Pass 20 IDs = billed 20 times (single call limit)\r\n- **Before batch retrieval must:**\r\n  1. Inform user of number of IDs passed and corresponding fee count\r\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\r\n\r\n### Fee Confirmation Principle\r\n\r\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\r\n\r\n\r\n## Workflow\r\n\r\nChoose the appropriate API based on user intent\r\n\r\n### Decision Guide\r\n\r\n| User Intent | Use API |\r\n|-------------|---------|\r\n| \"Analyze trade patterns/order data\" | Trade list |\r\n| \"Find companies purchasing XXX\" | Company list |\r\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\r\n| \"Get company detailed information\" | Company details |\r\n| \"Get contact information\" | Contact information |\r\n\r\n## Usage Examples\r\n\r\n### Scenario 1: Small Query — Trade Data Analysis\r\n\r\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\r\n```bash\r\npython scripts/trade_list_search.py \\\r\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\r\n  --query_count 20\r\n```\r\n\r\nTo further get supplier details (supports batch queries):\r\n```bash\r\npython scripts/company_get_details.py --companyIds 123456 789012 ...\r\n```\r\n\r\n### Scenario 2: Large Query — Big Data Analysis\r\n\r\n**User request**: \"Analyze 100 soybean trade records from 2024\"\r\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\r\n```bash\r\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\r\n```\r\n\r\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\r\n\r\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\r\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\r\n```bash\r\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\r\n```\r\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\r\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\r\n```bash\r\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\r\n```\r\n\r\n## Error Handling\r\n\r\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\r\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\r\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\r\n\r\n## Best Practices\r\n\r\n### Choosing the Right Method\r\n\r\n1. **Understand user intent**:\r\n   - Analyze trade data? → Use **trade list search**\r\n   - Find customers/partners? → Use **company list search**\r\n\r\n2. **Check API documentation**:\r\n   - **Before executing list queries, must first check the corresponding API reference documentation**\r\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\r\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\r\n\r\n3. **Identify parameter conditions**:\r\n   - Set date range\r\n   - HS codes are usually more precise than product names for filtering\r\n   - Reduce noise by filtering specific countries\r\n   - Use ISO country codes: CN, US, JP, etc.\r\n   - Use filters to find companies with contact information\r\n\r\n### Handling Results\r\n\r\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\r\n\r\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\r\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\r\n   - If user only needs a few companies, don't get details for all companies\r\n\r\n## Notes\r\n- All timestamps are in milliseconds\r\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\r\n- File paths use forward slashes on all platforms\r\n- Product names and industry names must be in **English**\r\n- Search quantity affects API response time, recommend setting timeout:120\r\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\r\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\r\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\r\n\r\n## Related Skills\r\n\r\nOther UpKuaJing skills you might find useful:\r\n\r\n- upkuajing-global-company-people-search — Global company and people search\r\n- upkuajing-email-tool — Send emails and manage email tasks\r\n- upkuajing-map-merchants-search — Map-based merchant search\r\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\r\n- upkuajing-contact-info-validity-check — Check contact info validity\n\nFile v1.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1776425838979\n}\n\nFile v1.0.6:references/company-detail-api.md\n\n# 公司详情 API 参考\r\n\r\n## python脚本参数\r\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\r\n\r\n## 请求参数\r\n\r\n### 必需参数\r\n- companyIds（整数数组）：公司编号列表（最多20个）\r\n\r\n## 响应参数\r\n\r\n### 基本信息\r\n- companyId：公司编号\r\n- name：公司名\r\n- logo：公司logo\r\n- introduce：公司介绍\r\n- industry：行业\r\n- scope：经营范围\r\n\r\n### 位置信息\r\n- location：公司位置\r\n- country：国家\r\n- province：省、州\r\n- city：城市\r\n- address：地址\r\n- postcode：邮编\r\n\r\n### 注册信息\r\n- registerPerson：注册法人\r\n- registerNumber：注册编号\r\n- registerDate：注册日期\r\n- registerType：注册类型\r\n- registerCapital：注册资金\r\n- registerState：注册状态\r\n\r\n### 贸易信息\r\n- companyType：公司贸易类型\r\n  - 0：未知\r\n  - 1：供应商\r\n  - 2：采购商\r\n  - 3：采购商和供应商\r\n\r\n### 国家信息\r\n- country.id：国家编号\r\n- country.name_cn：国家中文名\r\n- country.name_en：国家英文名\r\n- country.code_iso2：国家二字码\r\n- country.icon：国旗链接\n\nFile v1.0.6:references/company-list-api.md\n\n# 公司列表 API 参考\r\n\r\n## python脚本参数\r\n- `--params`: API业务参数\r\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\r\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\r\nparams、task_id 必须指定其一，不能同时指定时\r\n\r\n## params API业务参数\r\n### 必需参数\r\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\r\n### 贸易时间\r\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\r\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\r\n### 产品筛选\r\n- products（数组）：产品名称列表\r\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\r\n- productSuperordinate（数组）：产品的上游产品名称列表\r\n- productDownstream（数组）：产品的下游产品名称列表\r\n### 公司筛选\r\n- sellerIds（数组）：供应商公司ID列表\r\n- buyerIds（数组）：采购商公司ID列表\r\n- seller（字符串）：供应商公司名称\r\n- buyer（字符串）：采购商公司名称\r\n### 地理筛选\r\n- sellerCountryCodes（数组）：供应商国家代码\r\n- buyerCountryCodes（数组）：采购商国家代码\r\n- originCountryCodes（数组）：起运国国家代码\r\n- arrivalCountryCodes（数组）：抵运国国家代码\r\n- sellerPort（字符串）：装运港\r\n- buyerPort（字符串）：卸货港\r\n### 联系方式筛选\r\n- existPhone：1（有电话），2（无电话），0（全部）\r\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\r\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\r\n- existWebsite：1（有网站），2（无网站），0（全部）\r\n- existSocial：1（有社媒），2（无社媒），0（全部）\r\n### 其他参数\r\n- tradeCode（字符串）：提关单号\r\n- minTradeCount（整数）：最小贸易频次数量\r\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\r\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\r\n\r\n### 排序\r\n- sorting_field：tradeCount（默认）、latestTradeDate\r\n- sorting_direction：asc、desc（默认：desc）\r\n\r\n## 响应\r\n\r\n### 公司标识\r\n- companyId：公司ID\r\n- companyType：1（供应商），2（采购商）\r\n- name：公司名称\r\n### 贸易统计\r\n- tradeTotal：贸易总量\r\n- tradeMatchTotal：匹配贸易量\r\n- tradeMatchPercent：匹配贸易占比（%）\r\n- latestTradeDate：最后贸易日期（毫秒时间戳）\r\n### 公司信息\r\n- countryInfo：所属国信息\r\n- scope：公司主营\r\n- address：公司地址\r\n### 产品信息\r\n- productDesc：产品描述\r\n- productTag：产品标签列表\r\n- productNames：标准化产品名称\r\n- productAlias：产品别名\r\n- productSuperordinate：产品的上游产品名称列表\r\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.6:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\r\n\r\n## python脚本参数\r\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\r\n\r\n## 请求参数\r\n\r\n### 必需参数\r\n- companyIds（整数数组）：公司编号列表（最多20个）\r\n\r\n## 响应参数\r\n- companyId：公司编号\r\n\r\n### 邮箱信息 emails\r\n- val：邮箱地址\r\n- is_valid：是否有效\r\n  - 0：未检测\r\n  - 1：是\r\n  - 2：否\r\n  - 3：不确定\r\n- reason：原因\r\n\r\n### 电话信息 phones\r\n- val：电话号码\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- is_ws：是否WhatsApp\r\n  - 0：未检测\r\n  - 1：是\r\n  - 2：否\r\n  - 3：不确定\r\n- phone_type：号码类型\r\n  - 0：未检测\r\n  - 1：固定电话\r\n  - 2：移动电话\r\n  - 3：已检测但未知\r\n- country_code：电话所属国家二字码\r\n- dialing_code：电话所属国际冠码\r\n- area_code：电话所属地区码\r\n- international_number：国际格式号码\r\n- telephone：号码(去除冠码与区码)\r\n- national_number：号码属国格式\r\n\r\n### 社交媒体信息 socials\r\n- val：社媒完整链接\r\n- social_url：社媒链接路径\r\n- social_type：社媒链接类型\r\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- reason：原因\r\n\r\n### 网站信息 websites\r\n- val：网址\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- is_sensitive：是否敏感\r\n  - 0：未检测\r\n  - 1：是（如电子商务网站）\r\n  - 2：否\r\n  - 3：不确定\r\n- reason：原因\n\nFile v1.0.6:references/trade-list-api.md\n\n# 贸易列表 API 参考\r\n\r\n## python脚本参数\r\n- `--params`: API业务参数\r\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\r\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\r\nparams、task_id 必须指定其一，不能同时指定时\r\n\r\n## params API业务参数\r\n### 贸易时间\r\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\r\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\r\n### 产品筛选\r\n- products（字符串数组）：产品名称列表\r\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\r\n- productTags（字符串数组）：产品类别标签\r\n### 公司筛选\r\n- seller（字符串）：供应商公司名称\r\n- sellerCompanyId（整数）：供应商公司ID\r\n- buyer（字符串）：采购商公司名称\r\n- buyerCompanyId（整数）：采购商公司ID\r\n### 地理筛选\r\n- sellerCountryCodes（数组）：供应商国家代码\r\n- buyerCountryCodes（数组）：采购商国家代码\r\n- originCountryCodes（数组）：起运国国家代码\r\n- arrivalCountryCodes（数组）：抵运国国家代码\r\n- sellerPort（字符串）：装运港\r\n- buyerPort（字符串）：卸货港\r\n### 运输筛选\r\n- transportModeCodes（数组）：运输方式代码列表\r\n### 联系方式筛选\r\n供应商（exist*Seller）和采购商（exist*Buyer）：\r\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\r\n- 取值：1（有）、2（无）、0（全部）\r\n- 例如：existEmailSeller=1  需要供应商有邮箱\r\n### 其他参数\r\n- tradeCode（字符串）：提关单号\r\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\r\n### 排序\r\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\r\n- sorting_direction：asc、desc（默认：desc）\r\n\r\n## 响应参数\r\n\r\n### 标识字段\r\n- uuid：唯一标识，记录ID\r\n- tradeCode：提关单号\r\n- tradeDate：交易日期（毫秒时间戳）\r\n\r\n### 公司标识\r\n- sellerCompanyId/buyerCompanyId：公司ID\r\n- seller/buyer：公司名称\r\n\r\n### 贸易指标\r\n- amount：交易金额\r\n- quantity：交易数量\r\n- weight：交易重量\r\n- price：单价\r\n- *Unit: 指标的单位\r\n\r\n### 产品信息\r\n- productNames：产品名称列表\r\n- productDesc：产品描述\r\n- productHscode：产品HS编码\r\n- productHscodes6：产品HS编码（6位）\r\n- productCategory：产品类别列表\r\n- productAlias：产品相似词列表\r\n- productSuperordinate：产品上游词列表\r\n- productDownstream：产品下游词列表\r\n\r\n### 地理信息\r\n- sellerCountryInfo: 供应商国家信息\r\n- buyerCountryInfo: 采购商国家信息\r\n- originCountryInfo: 起运国信息\r\n- arrivalCountryInfo: 抵运国信息\r\n- productCountryInfo: 生产国信息\r\n- sellerPort/buyerPort: 起运港/抵运港口\r\n- transportModeCode：运输方式代码\n\nFile v1.0.6:skill-card.md\n\n## Description: <br>\nOfficial skill for upkuajing (跨境魔方). Find companies (找公司) and global buyers using customs trade data. Get trade order details, business contact info, and lead generation tools for import/export market research and supply chain analysis. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[upkuajing](https://clawhub.ai/user/upkuajing) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal trade, sales, and supply-chain teams use this skill to search customs trade records, identify buyer and supplier companies, inspect shipment patterns, and enrich selected company records with details or contact information. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill uses a paid UpKuaJing API key and can create paid searches, contact-detail batches, and recharge flows. <br>\nMitigation: Review current pricing, disclose the expected call or ID count, and require explicit user confirmation before any paid API call or top-up order. <br>\nRisk: The API key is sensitive and may be stored in ~/.upkuajing/.env. <br>\nMitigation: Keep the file private, do not paste or display the key in chat, and rotate the key if it is exposed. <br>\nRisk: Searches and enrichment calls can retrieve business contact data such as email, phone, social links, and websites. <br>\nMitigation: Limit retrieval to records needed for the user's task and handle exported JSON or JSONL files according to applicable contact-data and sales-outreach policies. <br>\n\n\n## Reference(s): <br>\n- [UpKuaJing Homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html) <br>\n- [Company List API Reference](references/company-list-api.md) <br>\n- [Trade List API Reference](references/trade-list-api.md) <br>\n- [Company Detail API Reference](references/company-detail-api.md) <br>\n- [Contact Fetch API Reference](references/contact-fetch-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with shell commands; scripts return JSON summaries and may write JSONL task result files.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires Python and UPKUAJING_API_KEY; paid API calls can retrieve trade records, company details, contact data, account information, pricing, and top-up order links.] <br>\n\n## Skill Version(s): <br>\n1.0.6 (source: server evidence and SKILL.md metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.6:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.5: 13 files, 22462 bytes\n\nFiles: references/company-detail-api.md (1115b), references/company-list-api.md (3062b), references/contact-fetch-api.md (1599b), references/trade-list-api.md (3112b), requirements.txt (13b), scripts/auth.py (5952b), scripts/common.py (14448b), scripts/company_get_contact.py (1478b), scripts/company_get_details.py (1436b), scripts/company_list_search.py (6128b), scripts/trade_list_search.py (5786b), SKILL.md (9629b), _meta.json (157b)\n\nFile v1.0.5:SKILL.md\n\n---\r\nname: upkuajing-customs-trade-company-search\r\ndescription: Official skill for upkuajing (跨境魔方). Find companies (找公司) and global buyers using customs trade data. Get trade order details, business contact info, and lead generation tools for import/export market research and supply chain analysis.\r\nmetadata: {\"version\":\"1.0.5\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\r\n---\r\n\r\n# UpKuaJing Customs Trade Company Search\r\n\r\nSearch 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.\r\n\r\n## Overview\r\n\r\nThis 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).\r\nAPI key generation and top-up are provided through the `auth.py` script.\r\n\r\n## Running Scripts\r\n\r\n### Environment Setup\r\n\r\n1. **Check Python**: `python --version`\r\n2. **Install dependencies**: `pip install -r requirements.txt`\r\n\r\nScript directory: `scripts/*.py`\r\nRun example: `python scripts/*.py`\r\n\r\n### Two Search Methods\r\n\r\n**Trade List Search** (`trade_list_search.py`)\r\n- **Return granularity**: Each trade order as one record\r\n- **Use cases**: Focus on \"what transactions occurred\"\r\n- **Examples**:\r\n   - \"Show all orders where Company A purchased LED\"\r\n   - \"Find soybean trade records imported/exported to US\"\r\n   - \"View specific transaction details within a time period\"\r\n- **Parameters**: See [Trade List](references/trade-list-api.md)\r\n\r\n\r\n**Company List Search** (`company_list_search.py`)\r\n- **Return granularity**: Trade orders aggregated by company, each company as one row\r\n- **Use cases**: Focus on \"which companies exist\"\r\n- **Examples**:\r\n  - \"Find companies that purchased LED\"\r\n  - \"Find US companies with electronics import/export business with China\"\r\n  - \"Find companies with China-US trade\" (logistics industry customer development)\r\n- **Parameters**: See [Company List](references/company-list-api.md)\r\n\r\n\r\n### Two Enhancement Features\r\n\r\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\r\n**Company Details** (`company_get_details.py --companyIds *`)\r\n- Get company information (excluding contact information)\r\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\r\n- **API business parameters**: [Company Details](references/company-detail-api.md)\r\n\r\n**Contact Information** (`company_get_contact.py --companyIds *`)\r\n- Get contact details: email, phone, social media, website\r\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time\r\n- **API business parameters**: [Get Contact Information](references/contact-fetch-api.md)\r\n\r\n## API Key and Top-up\r\n\r\nThis skill requires an API key. The API key is stored in the `~/.upkuajing/.env` file:\r\n```bash\r\ncat ~/.upkuajing/.env\r\n```\r\n**Example file content**:\r\n```\r\nUPKUAJING_API_KEY=your_api_key_here\r\n```\r\n### **API Key Not Set**\r\nFirst check if the `~/.upkuajing/.env` file has UPKUAJING_API_KEY;\r\nIf UPKUAJING_API_KEY is not set, prompt the user to choose:\r\n1. User has one: User provides it (manually add to ~/.upkuajing/.env file)\r\n2. 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\r\nWait for user selection;\r\n\r\n### **Account Top-up**\r\nWhen API response indicates insufficient balance, explain and guide user to top up:\r\n1. Create top-up order (`auth.py --new_rec_order`)\r\n2. Based on order response, send payment page URL to user, guide user to open URL and pay, user confirms after successful payment;\r\n\r\n### **Get Account Information**\r\nUse this script to get account information for UPKUAJING_API_KEY: `auth.py --account_info`\r\n\r\n## API Key and UpKuaJing Account\r\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\r\n\r\n## Fees\r\n\r\n**All API calls incur fees**, different interfaces have different billing methods.\r\n**Latest pricing**: Users can visit [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\r\nOr use: `python scripts/auth.py --price_info` (returns complete pricing for all interfaces)\r\n\r\n### List Search Billing Rules\r\n\r\nBilled by **number of calls**, each call returns up to 20 records:\r\n- Number of calls: `ceil(query_count / 20)` times\r\n- **Whenever query_count > 20, must before execution:**\r\n  1. Inform user of expected number of calls\r\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\r\n\r\n### Enhancement Interface Billing Rules\r\n\r\nBilled by **number of IDs passed**, max 20 IDs per call:\r\n- Pass 1 ID = billed 1 time\r\n- Pass 20 IDs = billed 20 times (single call limit)\r\n- **Before batch retrieval must:**\r\n  1. Inform user of number of IDs passed and corresponding fee count\r\n  2. Stop, wait for explicit user confirmation in a separate message, then execute script\r\n\r\n### Fee Confirmation Principle\r\n\r\n**Any operation that incurs fees must first inform and wait for explicit user confirmation. Do not execute in the same message as the notification.**\r\n\r\n\r\n## Workflow\r\n\r\nChoose the appropriate API based on user intent\r\n\r\n### Decision Guide\r\n\r\n| User Intent | Use API |\r\n|-------------|---------|\r\n| \"Analyze trade patterns/order data\" | Trade list |\r\n| \"Find companies purchasing XXX\" | Company list |\r\n| \"Find suppliers for XXX with email\" | Company list existEmail=1 |\r\n| \"Get company detailed information\" | Company details |\r\n| \"Get contact information\" | Contact information |\r\n\r\n## Usage Examples\r\n\r\n### Scenario 1: Small Query — Trade Data Analysis\r\n\r\n**User request**: \"Show 2024 LED lighting fixture trade data exported to US\"\r\n```bash\r\npython scripts/trade_list_search.py \\\r\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\r\n  --query_count 20\r\n```\r\n\r\nTo further get supplier details (supports batch queries):\r\n```bash\r\npython scripts/company_get_details.py --companyIds 123456 789012 ...\r\n```\r\n\r\n### Scenario 2: Large Query — Big Data Analysis\r\n\r\n**User request**: \"Analyze 100 soybean trade records from 2024\"\r\n**Before execution** inform user: ceil(100/20) = 5 API calls, confirm before executing;\r\n```bash\r\npython scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100\r\n```\r\n\r\n### Scenario 3: Ultra Large Query - Multiple Script Calls Required\r\n\r\n**User request**: \"Find 2000 companies importing electronics from China, with email addresses\"\r\n**Before execution** inform user: ceil(2000/20) = 100 API calls, confirm before executing;\r\n```bash\r\npython scripts/company_list_search.py --params '{\"companyType\": 2, \"sellerCountryCodes\": [\"CN\"], \"existEmail\": 1}' --query_count 1000\r\n```\r\n**After execution**: Script responds {\"task_id\":\"a1b2-c3d4\", \"file_url\": \"xxxxx\", ……}\r\n**Continue execution, append data**: Specify task_id, script continues query from last cursor and appends to file\r\n```bash\r\npython scripts/company_list_search.py --task_id 'a1b2-c3d4' --query_count 1000\r\n```\r\n\r\n## Error Handling\r\n\r\n- **API key invalid/non-existent**: Check `UPKUAJING_API_KEY` in `~/.upkuajing/.env` file\r\n- **Insufficient balance**: Guide user to top up according to **Account Top-up** steps\r\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, check parameter names and formats, do not guess\r\n\r\n## Best Practices\r\n\r\n### Choosing the Right Method\r\n\r\n1. **Understand user intent**:\r\n   - Analyze trade data? → Use **trade list search**\r\n   - Find customers/partners? → Use **company list search**\r\n\r\n2. **Check API documentation**:\r\n   - **Before executing list queries, must first check the corresponding API reference documentation**\r\n   - Trade list: Check [references/trade-list-api.md](references/trade-list-api.md)\r\n   - Company list: Check [references/company-list-api.md](references/company-list-api.md)\r\n\r\n3. **Identify parameter conditions**:\r\n   - Set date range\r\n   - HS codes are usually more precise than product names for filtering\r\n   - Reduce noise by filtering specific countries\r\n   - Use ISO country codes: CN, US, JP, etc.\r\n   - Use filters to find companies with contact information\r\n\r\n### Handling Results\r\n\r\n3. **Handle jsonl files carefully**: For large data queries, pay attention to file size\r\n\r\n4. **Gradually enrich information**: Only call details/contact interfaces when needed\r\n   - Company IDs returned by both list interfaces can be used for both detail interfaces\r\n   - If user only needs a few companies, don't get details for all companies\r\n\r\n## Notes\r\n- All timestamps are in milliseconds\r\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, JP)\r\n- File paths use forward slashes on all platforms\r\n- Product names and industry names must be in **English**\r\n- Search quantity affects API response time, recommend setting timeout:120\r\n- **Prohibit outputting technical parameter format**: Do not display code-style parameters in responses, convert to natural language\r\n- **Do not estimate or guess per-call fees** — use `python scripts/auth.py --price_info` to get accurate pricing information\r\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1775790185812\n}\n\nFile v1.0.5:references/company-detail-api.md\n\n# 公司详情 API 参考\r\n\r\n## python脚本参数\r\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\r\n\r\n## 请求参数\r\n\r\n### 必需参数\r\n- companyIds（整数数组）：公司编号列表（最多20个）\r\n\r\n## 响应参数\r\n\r\n### 基本信息\r\n- companyId：公司编号\r\n- name：公司名\r\n- logo：公司logo\r\n- introduce：公司介绍\r\n- industry：行业\r\n- scope：经营范围\r\n\r\n### 位置信息\r\n- location：公司位置\r\n- country：国家\r\n- province：省、州\r\n- city：城市\r\n- address：地址\r\n- postcode：邮编\r\n\r\n### 注册信息\r\n- registerPerson：注册法人\r\n- registerNumber：注册编号\r\n- registerDate：注册日期\r\n- registerType：注册类型\r\n- registerCapital：注册资金\r\n- registerState：注册状态\r\n\r\n### 贸易信息\r\n- companyType：公司贸易类型\r\n  - 0：未知\r\n  - 1：供应商\r\n  - 2：采购商\r\n  - 3：采购商和供应商\r\n\r\n### 国家信息\r\n- country.id：国家编号\r\n- country.name_cn：国家中文名\r\n- country.name_en：国家英文名\r\n- country.code_iso2：国家二字码\r\n- country.icon：国旗链接\n\nFile v1.0.5:references/company-list-api.md\n\n# 公司列表 API 参考\r\n\r\n## python脚本参数\r\n- `--params`: API业务参数\r\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\r\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\r\nparams、task_id 必须指定其一，不能同时指定时\r\n\r\n## params API业务参数\r\n### 必需参数\r\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\r\n### 贸易时间\r\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\r\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\r\n### 产品筛选\r\n- products（数组）：产品名称列表\r\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\r\n- productSuperordinate（数组）：产品的上游产品名称列表\r\n- productDownstream（数组）：产品的下游产品名称列表\r\n### 公司筛选\r\n- sellerIds（数组）：供应商公司ID列表\r\n- buyerIds（数组）：采购商公司ID列表\r\n- seller（字符串）：供应商公司名称\r\n- buyer（字符串）：采购商公司名称\r\n### 地理筛选\r\n- sellerCountryCodes（数组）：供应商国家代码\r\n- buyerCountryCodes（数组）：采购商国家代码\r\n- originCountryCodes（数组）：起运国国家代码\r\n- arrivalCountryCodes（数组）：抵运国国家代码\r\n- sellerPort（字符串）：装运港\r\n- buyerPort（字符串）：卸货港\r\n### 联系方式筛选\r\n- existPhone：1（有电话），2（无电话），0（全部）\r\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\r\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\r\n- existWebsite：1（有网站），2（无网站），0（全部）\r\n- existSocial：1（有社媒），2（无社媒），0（全部）\r\n### 其他参数\r\n- tradeCode（字符串）：提关单号\r\n- minTradeCount（整数）：最小贸易频次数量\r\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\r\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\r\n\r\n### 排序\r\n- sorting_field：tradeCount（默认）、latestTradeDate\r\n- sorting_direction：asc、desc（默认：desc）\r\n\r\n## 响应\r\n\r\n### 公司标识\r\n- companyId：公司ID\r\n- companyType：1（供应商），2（采购商）\r\n- name：公司名称\r\n### 贸易统计\r\n- tradeTotal：贸易总量\r\n- tradeMatchTotal：匹配贸易量\r\n- tradeMatchPercent：匹配贸易占比（%）\r\n- latestTradeDate：最后贸易日期（毫秒时间戳）\r\n### 公司信息\r\n- countryInfo：所属国信息\r\n- scope：公司主营\r\n- address：公司地址\r\n### 产品信息\r\n- productDesc：产品描述\r\n- productTag：产品标签列表\r\n- productNames：标准化产品名称\r\n- productAlias：产品别名\r\n- productSuperordinate：产品的上游产品名称列表\r\n- productDownstream：产品的下游产品名称列表\n\nFile v1.0.5:references/contact-fetch-api.md\n\n# 联系方式获取 API 参考\r\n\r\n## python脚本参数\r\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\r\n\r\n## 请求参数\r\n\r\n### 必需参数\r\n- companyIds（整数数组）：公司编号列表（最多20个）\r\n\r\n## 响应参数\r\n- companyId：公司编号\r\n\r\n### 邮箱信息 emails\r\n- val：邮箱地址\r\n- is_valid：是否有效\r\n  - 0：未检测\r\n  - 1：是\r\n  - 2：否\r\n  - 3：不确定\r\n- reason：原因\r\n\r\n### 电话信息 phones\r\n- val：电话号码\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- is_ws：是否WhatsApp\r\n  - 0：未检测\r\n  - 1：是\r\n  - 2：否\r\n  - 3：不确定\r\n- phone_type：号码类型\r\n  - 0：未检测\r\n  - 1：固定电话\r\n  - 2：移动电话\r\n  - 3：已检测但未知\r\n- country_code：电话所属国家二字码\r\n- dialing_code：电话所属国际冠码\r\n- area_code：电话所属地区码\r\n- international_number：国际格式号码\r\n- telephone：号码(去除冠码与区码)\r\n- national_number：号码属国格式\r\n\r\n### 社交媒体信息 socials\r\n- val：社媒完整链接\r\n- social_url：社媒链接路径\r\n- social_type：社媒链接类型\r\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- reason：原因\r\n\r\n### 网站信息 websites\r\n- val：网址\r\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\r\n- is_sensitive：是否敏感\r\n  - 0：未检测\r\n  - 1：是（如电子商务网站）\r\n  - 2：否\r\n  - 3：不确定\r\n- reason：原因\n\nFile v1.0.5:references/trade-list-api.md\n\n# 贸易列表 API 参考\r\n\r\n## python脚本参数\r\n- `--params`: API业务参数\r\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\r\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\r\nparams、task_id 必须指定其一，不能同时指定时\r\n\r\n## params API业务参数\r\n### 贸易时间\r\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\r\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\r\n### 产品筛选\r\n- products（字符串数组）：产品名称列表\r\n- hscodes（字符串数组）：HS海关编码（超过6位，只取前6位）\r\n- productTags（字符串数组）：产品类别标签\r\n### 公司筛选\r\n- seller（字符串）：供应商公司名称\r\n- sellerCompanyId（整数）：供应商公司ID\r\n- buyer（字符串）：采购商公司名称\r\n- buyerCompanyId（整数）：采购商公司ID\r\n### 地理筛选\r\n- sellerCountryCodes（数组）：供应商国家代码\r\n- buyerCountryCodes（数组）：采购商国家代码\r\n- originCountryCodes（数组）：起运国国家代码\r\n- arrivalCountryCodes（数组）：抵运国国家代码\r\n- sellerPort（字符串）：装运港\r\n- buyerPort（字符串）：卸货港\r\n### 运输筛选\r\n- transportModeCodes（数组）：运输方式代码列表\r\n### 联系方式筛选\r\n供应商（exist*Seller）和采购商（exist*Buyer）：\r\n- existEmail*、existPhone*、existWhatsapp*、existWebsite*、existSocial*\r\n- 取值：1（有）、2（无）、0（全部）\r\n- 例如：existEmailSeller=1  需要供应商有邮箱\r\n### 其他参数\r\n- tradeCode（字符串）：提关单号\r\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\r\n### 排序\r\n- sorting_field：tradeDate、quantity、weight、amount（默认：tradeDate）\r\n- sorting_direction：asc、desc（默认：desc）\r\n\r\n## 响应参数\r\n\r\n### 标识字段\r\n- uuid：唯一标识，记录ID\r\n- tradeCode：提关单号\r\n- tradeDate：交易日期（毫秒时间戳）\r\n\r\n### 公司标识\r\n- sellerCompanyId/buyerCompanyId：公司ID\r\n- seller/buyer：公司名称\r\n\r\n### 贸易指标\r\n- amount：交易金额\r\n- quantity：交易数量\r\n- weight：交易重量\r\n- price：单价\r\n- *Unit: 指标的单位\r\n\r\n### 产品信息\r\n- productNames：产品名称列表\r\n- productDesc：产品描述\r\n- productHscode：产品HS编码\r\n- productHscodes6：产品HS编码（6位）\r\n- productCategory：产品类别列表\r\n- productAlias：产品相似词列表\r\n- productSuperordinate：产品上游词列表\r\n- productDownstream：产品下游词列表\r\n\r\n### 地理信息\r\n- sellerCountryInfo: 供应商国家信息\r\n- buyerCountryInfo: 采购商国家信息\r\n- originCountryInfo: 起运国信息\r\n- arrivalCountryInfo: 抵运国信息\r\n- productCountryInfo: 生产国信息\r\n- sellerPort/buyerPort: 起运港/抵运港口\r\n- transportModeCode：运输方式代码\n\nFile v1.0.5:requirements.txt\n\nhttpx>=0.23.0","readmeExcerpt":"Skill: Global customs trade data aggregated across 220+ countries with integrated bulk search functionality for global B2B prospecting. Accelerate discovery ofverified genuine buyers and qualified international suppliers for export businesses. Dig into official import & export shipment records to pinpointproduct-matching importers and full historical transaction logs. Run targeted lookups filtered by company profiles","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"cat ~/.upkuajing/.env"},{"language":"text","snippet":"UPKUAJING_API_KEY=your_api_key_here"},{"language":"bash","snippet":"python scripts/error_report.py --params '{\"requestPath\":\"/agent/customs/company/list\",\"requestId\":\"f47ac10b58cc4372a5670e02b2c3d479\",\"context\":\"Customs trade company search failed with a server error\"}'"},{"language":"bash","snippet":"python scripts/trade_list_search.py \\\n  --params '{\"products\": [\"LED lights\"], \"buyerCountryCodes\": [\"US\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' \\\n  --query_count 20"},{"language":"bash","snippet":"python scripts/company_get_details.py --companyIds 123456 789012 ..."},{"language":"bash","snippet":"python scripts/trade_list_search.py --params '{\"products\": [\"soybean\"], \"dateStart\": 1704067200000, \"dateEnd\": 1735689599999}' --query_count 100"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: upkuajing-customs-trade-company-search\ndescription: \"Access global customs trade data from 220+ countries. Search import‑export records via companies, HS codes and products. Find genuine buyers and monitor competitors for your export business.\\n\\nTrigger: global customs trade data, import export records lookup, HS‑code search, find overseas buyers, competitor trade monitoring, bulk trade‑data search\"\nmetadata: {\"version\":\"1.0.10\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"🏢\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Customs Trade Company Search\n\nSearch 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.\n\n## Overview\n\nThis 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).\nAPI key generation and top-up are provided through the `auth.py` script.\n\n## Running Scripts\n\n### Environment Setup\n\n1. **Check Python**: `python --version`\n2. **Install dependencies**: `pip install -r requirements.txt`\n\nScript directory: `scripts/*.py`\nRun example: `python scripts/*.py`\n\n**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`.\n\n**Important**: Always use direct script invocation like `python scripts/company_list_search.py`. **Do NOT use** shell compound commands like `cd scripts && python company_list_search.py`.\n\n### Two Search Methods\n\n**Trade List Search** (`trade_list_search.py`)\n- **Return granularity**: Each trade order as one record\n- **Use cases**: Focus on \"what transactions occurred\"\n- **Examples**:\n   - \"Show all orders where Company A purchased LED\"\n   - \"Find soybean trade records imported/exported to US\"\n   - \"View specific transaction details within a time period\"\n- **Parameters**: See [Trade List](references/trade-list-api.md)\n\n\n**Company List Search** (`company_list_search.py`)\n- **Return granularity**: Trade orders aggregated by company, each company as one row\n- **Use cases**: Focus on \"which companies exist\"\n- **Examples**:\n  - \"Find companies that purchased LED\"\n  - \"Find US companies with electronics import/export business with China\"\n  - \"Find companies with China-US trade\" (logistics industry customer development)\n- **Parameters**: See [Company List](references/company-list-api.md)\n\n\n### Two Enhancement Features\n\nAfter obtaining trade list or company list, use these interfaces to enrich company IDs in the results when necessary:\n**Company Details** (`company_get_details.py --companyIds *`)\n- Get company information (excluding contact information)\n- **Parameters**: `--companyIds` List of company IDs (space-separated), max 20 at a time"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-customs-trade-company-search\",\n  \"version\": \"1.0.10\",\n  \"publishedAt\": 1787562509260\n}"},{"path":"references/company-detail-api.md","content":"# 公司详情 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n\n### 基本信息\n- companyId：公司编号\n- name：公司名\n- logo：公司logo\n- introduce：公司介绍\n- industry：行业\n- scope：经营范围\n\n### 位置信息\n- location：公司位置\n- country：国家\n- province：省、州\n- city：城市\n- address：地址\n- postcode：邮编\n\n### 注册信息\n- registerPerson：注册法人\n- registerNumber：注册编号\n- registerDate：注册日期\n- registerType：注册类型\n- registerCapital：注册资金\n- registerState：注册状态\n\n### 贸易信息\n- companyType：公司贸易类型\n  - 0：未知\n  - 1：供应商\n  - 2：采购商\n  - 3：采购商和供应商\n\n### 国家信息\n- country.id：国家编号\n- country.name_cn：国家中文名\n- country.name_en：国家英文名\n- country.code_iso2：国家二字码\n- country.icon：国旗链接"},{"path":"references/company-list-api.md","content":"# 公司列表 API 参考\n\n## python脚本参数\n- `--params`: API业务参数\n- `--task_id`：任务ID；指定task_id时，脚本会找到task_id的执行参数，从最后一条数据继续游标查询；一般用于大数据量查询、异常中断后继续查询；\n- `--query_count`：期望获取的总记录数，脚本据此自动计算次数并轮询调用API；非必填；默认值20；取值范围 20~1000；\nparams、task_id 必须指定其一，不能同时指定时\n\n## params API业务参数\n### 必需参数\n- companyType（整数）：公司类型`1`：供应商，`2`：采购商\n### 贸易时间\n- dateStart（整数）：贸易开始时间（毫秒级时间戳）\n- dateEnd（整数）：贸易截止时间（毫秒级时间戳）\n### 产品筛选\n- products（数组）：产品名称列表\n- hscodes（数组）：HS海关编码（超过6位，只取前6位）\n- productSuperordinate（数组）：产品的上游产品名称列表\n- productDownstream（数组）：产品的下游产品名称列表\n### 公司筛选\n- sellerIds（数组）：供应商公司ID列表\n- buyerIds（数组）：采购商公司ID列表\n- seller（字符串）：供应商公司名称\n- buyer（字符串）：采购商公司名称\n### 地理筛选\n- sellerCountryCodes（数组）：供应商国家代码\n- buyerCountryCodes（数组）：采购商国家代码\n- originCountryCodes（数组）：起运国国家代码\n- arrivalCountryCodes（数组）：抵运国国家代码\n- sellerPort（字符串）：装运港\n- buyerPort（字符串）：卸货港\n### 联系方式筛选\n- existPhone：1（有电话），2（无电话），0（全部）\n- existEmail：1（有邮箱），2（无邮箱），0（全部）\n- existWhatsApp：1（有WhatsApp），2（无WhatsApp），0（全部）\n- existWebsite：1（有网站），2（无网站），0（全部）\n- existSocial：1（有社媒），2（无社媒），0（全部）\n### 其他参数\n- tradeCode（字符串）：提关单号\n- minTradeCount（整数）：最小贸易频次数量\n- createTimeStart/createTimeEnd（整数）：数据创建日期范围\n- isExact（布尔值）：true=精确匹配，false=模糊匹配（默认true）\n\n### 排序\n- sorting_field：tradeCount（默认）、latestTradeDate\n- sorting_direction：asc、desc（默认：desc）\n\n## 响应\n\n### 公司标识\n- companyId：公司ID\n- companyType：1（供应商），2（采购商）\n- name：公司名称\n### 贸易统计\n- tradeTotal：贸易总量\n- tradeMatchTotal：匹配贸易量\n- tradeMatchPercent：匹配贸易占比（%）\n- latestTradeDate：最后贸易日期（毫秒时间戳）\n### 公司信息\n- countryInfo：所属国信息\n- scope：公司主营\n- address：公司地址\n### 产品信息\n- productDesc：产品描述\n- productTag：产品标签列表\n- productNames：标准化产品名称\n- productAlias：产品别名\n- productSuperordinate：产品的上游产品名称列表\n- productDownstream：产品的下游产品名称列表"},{"path":"references/contact-fetch-api.md","content":"# 联系方式获取 API 参考\n\n## python脚本参数\n- `--companyIds`：公司ID列表（空格分隔，必需，最多20个）\n\n## 请求参数\n\n### 必需参数\n- companyIds（整数数组）：公司编号列表（最多20个）\n\n## 响应参数\n- companyId：公司编号\n\n### 邮箱信息 emails\n- val：邮箱地址\n- is_valid：是否有效\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- reason：原因\n\n### 电话信息 phones\n- val：电话号码\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_ws：是否WhatsApp\n  - 0：未检测\n  - 1：是\n  - 2：否\n  - 3：不确定\n- phone_type：号码类型\n  - 0：未检测\n  - 1：固定电话\n  - 2：移动电话\n  - 3：已检测但未知\n- country_code：电话所属国家二字码\n- dialing_code：电话所属国际冠码\n- area_code：电话所属地区码\n- international_number：国际格式号码\n- telephone：号码(去除冠码与区码)\n- national_number：号码属国格式\n\n### 社交媒体信息 socials\n- val：社媒完整链接\n- social_url：社媒链接路径\n- social_type：社媒链接类型\n  - linkedin、facebook、twitter、youtube、instagram、pinterest、github、tiktok\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- reason：原因\n\n### 网站信息 websites\n- val：网址\n- is_valid：是否有效（0未检测，1是，2否，3不确定）\n- is_sensitive：是否敏感\n  - 0：未检测\n  - 1：是（如电子商务网站）\n  - 2：否\n  - 3：不确定\n- reason：原因"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1330,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:23:59.312Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:29:40.459Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}