{"id":"58186540-6fd0-4f64-9b28-2926a04843aa","entityType":"agent","slug":"clawhub-upkuajing-upkuajing-map-merchants-search","name":"Google Maps business data extraction paired with bulk search and batch data download capabilities for global B2B lead generation. Filter search results bycountry, state, city, district, search radius, industry and product keywords to batch collect busines","canonicalUrl":"https://www.xpersona.co/agent/clawhub-upkuajing-upkuajing-map-merchants-search","canonicalPath":"/agent/clawhub-upkuajing-upkuajing-map-merchants-search","generatedAt":"2026-10-10T08:54:42.373Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:48:39.685Z","emptyReason":null},"description":"Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion. Trigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation","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-map-merchants-search","sourceUrl":"https://clawhub.ai/upkuajing/upkuajing-map-merchants-search","homepage":"https://clawhub.ai/upkuajing/skills/upkuajing-map-merchants-search","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/upkuajing/upkuajing-map-merchants-search","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/upkuajing/skills/upkuajing-map-merchants-search","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Google Maps business data extraction paired with bulk search and batch data download capabilities for global B2B lead generation. Filter search results bycountr"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:48:39.685Z","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:48:39.685Z","emptyReason":null},"stars":null,"forks":null,"downloads":1869,"packageName":null,"latestVersion":"1.0.6","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:48:39.685Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:48:39.685Z","lastCrawledAt":"2026-10-09T23:48:39.685Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:48:39.685Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.6","createdAt":"2026-08-24T09:11:32.267Z","changelog":"updated","fileCount":15,"zipByteSize":23823},{"version":"1.0.5","createdAt":"2026-07-16T08:56:50.736Z","changelog":"updated","fileCount":13,"zipByteSize":20951},{"version":"1.0.4","createdAt":"2026-07-16T06:17:48.375Z","changelog":"updated","fileCount":13,"zipByteSize":20940},{"version":"1.0.3","createdAt":"2026-07-06T03:59:41.511Z","changelog":"updated","fileCount":13,"zipByteSize":20527},{"version":"1.0.2","createdAt":"2026-04-17T11:40:29.040Z","changelog":"updated","fileCount":13,"zipByteSize":20544},{"version":"1.0.1","createdAt":"2026-04-10T08:07:00.884Z","changelog":"Initial release","fileCount":11,"zipByteSize":16870},{"version":"1.0.0","createdAt":"2026-04-10T02:20:50.729Z","changelog":"Initial release","fileCount":11,"zipByteSize":16424}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17304xrt0p2xssnmr7datqzks83gvsr:upkuajing-map-merchants-search","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17304xrt0p2xssnmr7datqzks83gvsr:upkuajing-map-merchants-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-map-merchants-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-map-merchants-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-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:54:42.370Z"}},"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-map-merchants-search/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-upkuajing-upkuajing-map-merchants-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:48:39.685Z","emptyReason":null},"readme":"Skill: Google Maps business data extraction paired with bulk search and batch data download capabilities for global B2B lead generation. Filter search results bycountry, state, city, district, search radius, industry and product keywords to batch collect business names, physical addresses and full contact details.Precisely pinpoint overseas buyers and local enterprises to streamline end-to-end lead development workflows. Support field sales reps, distributors, brandoperation teams and regional managers to target merchants in designated zones and commercial districts. Analyze regional market density and coverage data togenerate high-qualified sales prospects. Fully optimized for regional business expansion, new outlet setup, distributor recruitment, competitor locationtracking and territory planning for offline channel development.\n\nOwner: upkuajing\n\nSummary: Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion. Trigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation\n\nTags: Google Maps data:1.0.6, bulk merchant leads:1.0.6, distributor sourcing:1.0.6, google-maps:1.0.6, latest:1.0.6, local-business:1.0.6, map:1.0.6, merchant:1.0.6, nearby:1.0.6, offline sales prospecting:1.0.6, regional market analysis:1.0.6, retail:1.0.6\n\nVersion history:\n\nv1.0.6 | 2026-08-24T09:11:32.267Z | user\n\nupdated\n\nv1.0.5 | 2026-07-16T08:56:50.736Z | user\n\nupdated\n\nv1.0.4 | 2026-07-16T06:17:48.375Z | user\n\nupdated\n\nv1.0.3 | 2026-07-06T03:59:41.511Z | user\n\nupdated\n\nv1.0.2 | 2026-04-17T11:40:29.040Z | user\n\nupdated\n\nv1.0.1 | 2026-04-10T08:07:00.884Z | user\n\nInitial release\n\nv1.0.0 | 2026-04-10T02:20:50.729Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.6: 15 files, 23823 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), references/skill-error-report-api.md (2070b), requirements.txt (14b), scripts/auth.py (5849b), scripts/common.py (14546b), scripts/error_report.py (1845b), scripts/geography_list.py (4146b), scripts/merchants_search.py (6504b), scripts/version_check.py (4933b), skill-card.md (2990b), SKILL.md (12146b), _meta.json (149b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: \"Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion.\\n\\nTrigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation\"\nmetadata: {\"version\":\"1.0.6\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\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/map/search\",\"requestId\":\"f47ac10b58cc4372a5670e02b2c3d479\",\"context\":\"Merchant 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**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, 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 Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\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-customs-trade-company-search — Search customs trade companies\n- upkuajing-email-tool — Send emails and manage email tasks\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.6:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1787562692267\n}\n\nFile v1.0.6:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.6:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.6:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.6:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.6: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.6:skill-card.md\n\n## Description:\n\nPull bulk Google Maps business data with radius-based filters to gather merchant contact information, analyze market density, and find distributors or overseas buyers for offline business expansion.\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 business development, field sales, distributor, brand operations, and regional management teams use this skill to search global merchant data by geography, radius, industry, keyword, and contact availability for B2B lead generation and territory planning.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Merchant searches use a paid API service and may consume account balance.\n\nMitigation: Confirm current pricing and expected call volume before paid searches, especially for bulk queries.\n\nRisk: The skill reads or writes an UpKuaJing API key in ~/.upkuajing/.env.\n\nMitigation: Restrict local permissions on the credential file and avoid sharing the key in prompts, logs, or reports.\n\nRisk: Search results and task metadata may contain business contact data in local files.\n\nMitigation: Limit access to generated task_data and geography output files, and delete them when they are no longer needed.\n\nRisk: Error reports can include request context and response details.\n\nMitigation: Review report content before submission and avoid including sensitive business data.\n\nRisk: The skill performs a version-check request when API helpers run.\n\nMitigation: Review network access expectations before installation and operation.\n\n## Reference(s):\n\n- [ClawHub Skill Listing](https://clawhub.ai/upkuajing/skills/upkuajing-map-merchants-search)\n- [UpKuaJing Homepage](https://www.upkuajing.com)\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/)\n- [Detailed Price Description](https://www.upkuajing.com/web/openapi/price.html)\n- [Merchants Search API](references/merchants-search-api.md)\n- [Country List API](references/country-list-api.md)\n- [Province List API](references/province-list-api.md)\n- [City List API](references/city-list-api.md)\n- [Skill Error Report API](references/skill-error-report-api.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands and JSON results from the helper scripts]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Merchant searches can produce local JSONL result files and task metadata; geography lookups can produce local JSON files.]\n\n## Skill Version(s):\n\n1.0.6 (source: server evidence release and SKILL.md 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.6:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.5: 13 files, 20951 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (5849b), scripts/common.py (14546b), scripts/geography_list.py (4046b), scripts/merchants_search.py (6323b), scripts/version_check.py (4933b), skill-card.md (2906b), SKILL.md (11050b), _meta.json (149b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: \"Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion.\\n\\nTrigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation\"\nmetadata: {\"version\":\"1.0.5\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\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-customs-trade-company-search — Search customs trade companies\n- upkuajing-email-tool — Send emails and manage email tasks\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.5:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1784192210736\n}\n\nFile v1.0.5:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.5:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.5:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.5:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.5:skill-card.md\n\n## Description: <br>\nPull bulk Google Maps business data with radius-based filters, gather merchant contact information, analyze market density, and find distributors or overseas buyers for offline business expansion. <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>\nSales, distribution, brand operations, and regional expansion teams use this skill to search UpKuaJing map merchant data by geography, radius, industry, keywords, and contact filters. It helps collect business leads, plan territories, compare local market density, and identify potential distributors or overseas buyers. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill requires an UpKuaJing API key and may store it in a local ~/.upkuajing/.env file. <br>\nMitigation: Keep the API key private, restrict access to ~/.upkuajing, and remove or rotate the key when it is no longer needed. <br>\nRisk: Merchant search requests contact UpKuaJing servers and can incur usage fees for larger result counts. <br>\nMitigation: Review pricing before large searches and require explicit user confirmation before paid searches that exceed the documented threshold. <br>\nRisk: Search results can contain business contact and location data that is written to local JSONL files. <br>\nMitigation: Store exported lead data only where authorized, limit sharing to approved workflows, and delete result files when they are no longer needed. <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- [Merchants Search API](references/merchants-search-api.md) <br>\n- [Country List API](references/country-list-api.md) <br>\n- [Province List API](references/province-list-api.md) <br>\n- [City List API](references/city-list-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, shell commands, configuration, JSON, files, guidance] <br>\n**Output Format:** [Markdown guidance with Python command examples, JSON API responses, and JSONL result files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires Python, httpx, and UPKUAJING_API_KEY for paid merchant search; stores task metadata and result files locally under the skill task_data directory.] <br>\n\n## Skill Version(s): <br>\n1.0.5 (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.5:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.4: 13 files, 20940 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (5849b), scripts/common.py (14546b), scripts/geography_list.py (4046b), scripts/merchants_search.py (6323b), scripts/version_check.py (4933b), skill-card.md (2917b), SKILL.md (11050b), _meta.json (149b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: \"Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion.\\n\\nTrigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation\"\nmetadata: {\"version\":\"1.0.4\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\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-customs-trade-company-search — Search customs trade companies\n- upkuajing-email-tool — Send emails and manage email tasks\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.4:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1784182668375\n}\n\nFile v1.0.4:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.4:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.4:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.4:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.4:skill-card.md\n\n## Description: <br>\nPulls bulk Google Maps business data with radius-based filters to gather merchant contact information, analyze market density, and support distributor or buyer discovery for offline business expansion. <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 sales, distribution, brand, and regional expansion teams use this skill to search map-based merchant records by region, radius, industry, keyword, and contact availability. Agents can use it to prepare filtered lead lists, inspect local market coverage, and resume larger merchant-search jobs. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill stores an UpKuaJing API key in ~/.upkuajing/.env. <br>\nMitigation: Protect the local .env file like any other credential and avoid sharing logs or workspaces that may expose it. <br>\nRisk: Merchant-search requests are sent to UpKuaJing and may incur paid API charges. <br>\nMitigation: Confirm pricing and expected call volume before running searches, especially for query counts above 100 records. <br>\nRisk: Searches can write local task metadata and result.jsonl files containing merchant contact and location data. <br>\nMitigation: Review local output files before sharing and handle exported merchant data according to applicable privacy, contractual, and business policies. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/upkuajing/skills/upkuajing-map-merchants-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- [Merchants Search API reference](references/merchants-search-api.md) <br>\n- [Country List API reference](references/country-list-api.md) <br>\n- [Province List API reference](references/province-list-api.md) <br>\n- [City List API reference](references/city-list-api.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [API Calls, Shell commands, Files, Configuration instructions, Guidance] <br>\n**Output Format:** [Markdown guidance with shell commands and JSON or JSONL result files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires Python and UPKUAJING_API_KEY; merchant searches may incur fees and write task metadata plus result.jsonl files locally.] <br>\n\n## Skill Version(s): <br>\n1.0.4 (source: server release evidence and artifact 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.4:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.3: 13 files, 20527 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (5849b), scripts/common.py (14546b), scripts/geography_list.py (4046b), scripts/merchants_search.py (6323b), scripts/version_check.py (4933b), skill-card.md (2528b), SKILL.md (9826b), _meta.json (149b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: Official skill for upkuajing (跨境魔方). Search merchants on map (地图获客). Find merchants by region or nearby location, get merchant details including name, address, phone, industry, and more. Includes geographic data APIs (country, province, city lists) to support location-based search.\nmetadata: {\"version\":\"1.0.3\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\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-customs-trade-company-search — Search customs trade companies\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1783310381511\n}\n\nFile v1.0.3:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.3:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.3:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.3:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.3:skill-card.md\n\n## Description: <br>\nUpKuaJing Map Merchants Search lets agents query UpKuaJing's map merchant database to find businesses by region or nearby location and retrieve merchant details plus geography lists. <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 business users, field sales teams, distributors, brand teams, and developers use this skill to find geo-targeted merchants, inspect regional market coverage, and generate offline-to-online leads through UpKuaJing API calls. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Merchant search calls may incur paid UpKuaJing API charges. <br>\nMitigation: Review expected charges and get explicit user confirmation before running paid merchant searches. <br>\nRisk: The UpKuaJing API key is sensitive and may be stored in the user home directory. <br>\nMitigation: Keep UPKUAJING_API_KEY private and restrict permissions on ~/.upkuajing/.env. <br>\nRisk: Merchant search results are stored locally and may include business contact or location details. <br>\nMitigation: Review local result files before sharing them and delete retained data when it is no longer needed. <br>\n\n\n## Reference(s): <br>\n- [Merchants Search API](references/merchants-search-api.md) <br>\n- [Country List API](references/country-list-api.md) <br>\n- [Province List API](references/province-list-api.md) <br>\n- [City List API](references/city-list-api.md) <br>\n- [UpKuaJing Homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [UpKuaJing Open API Pricing](https://www.upkuajing.com/web/openapi/price.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, JSON, Files, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown guidance with shell commands and JSON output from scripts] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Merchant searches can write local JSONL result files and may incur UpKuaJing API fees.] <br>\n\n## Skill Version(s): <br>\n1.0.3 (source: server evidence 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.3:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.2: 13 files, 20544 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (6021b), scripts/common.py (14546b), scripts/geography_list.py (4028b), scripts/merchants_search.py (6317b), scripts/version_check.py (4927b), skill-card.md (2547b), SKILL.md (9826b), _meta.json (149b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: Official skill for upkuajing (跨境魔方). Search merchants on map (地图获客). Find merchants by region or nearby location, get merchant details including name, address, phone, industry, and more. Includes geographic data APIs (country, province, city lists) to support location-based search.\nmetadata: {\"version\":\"1.0.2\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\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-customs-trade-company-search — Search customs trade companies\n- upkuajing-email-tool — Send emails and manage email tasks\n- upkuajing-sms-tool — Send SMS and manage SMS tasks\n- upkuajing-contact-info-validity-check — Check contact info validity\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1776426029040\n}\n\nFile v1.0.2:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.2:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.2:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.2:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.2:skill-card.md\n\n## Description: <br>\nSearch UpKuaJing map merchant data by region, nearby location, industry, contact availability, or shop name, and retrieve geographic lists for country, province, and city parameters. <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 field sales, distributor, brand, and market intelligence teams use this skill to find geo-targeted merchants, analyze regional business presence, and prepare offline-to-online lead lists through UpKuaJing APIs. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill requires an UpKuaJing API key and sends merchant-search queries to a paid third-party API. <br>\nMitigation: Install only when the publisher is trusted, keep the API key protected or rotated, and confirm billable searches before execution. <br>\nRisk: Large merchant searches can incur fees and may produce local result files containing sensitive business leads. <br>\nMitigation: Require explicit confirmation before large queries and periodically remove local task_data files that are no longer needed. <br>\n\n\n## Reference(s): <br>\n- [UpKuaJing skill page](https://clawhub.ai/upkuajing/upkuajing-map-merchants-search) <br>\n- [UpKuaJing homepage](https://www.upkuajing.com) <br>\n- [UpKuaJing Open Platform](https://developer.upkuajing.com/) <br>\n- [UpKuaJing OpenAPI pricing](https://www.upkuajing.com/web/openapi/price.html) <br>\n- [Merchants Search API](references/merchants-search-api.md) <br>\n- [Country List API](references/country-list-api.md) <br>\n- [Province List API](references/province-list-api.md) <br>\n- [City List API](references/city-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 JSON API results from scripts] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Merchant search results may be stored locally as task data for large or resumed queries.] <br>\n\n## Skill Version(s): <br>\n1.0.2 (source: server evidence and frontmatter 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.2:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.1: 11 files, 16870 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1475b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (5951b), scripts/common.py (14449b), scripts/geography_list.py (4028b), scripts/merchants_search.py (6317b), SKILL.md (9233b), _meta.json (149b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: Official skill for upkuajing (跨境魔方). Search merchants on map (地图获客). Find merchants by region or nearby location, get merchant details including name, address, phone, industry, and more. Includes geographic data APIs (country, province, city lists) to support location-based search.\nmetadata: {\"version\":\"1.0.1\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by country/region\" | Merchants Search (countryCodes) |\n| \"Find merchants by province/city\" | Merchants Search (provinceIds, cityIds) |\n| \"Find merchants near a location\" | Merchants Search (geoDistance) |\n| \"Filter by industry or contact info\" | Merchants Search (industries, existPhone, existWebsite) |\n| \"Find shops by name\" | Merchants Search (companyNames) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by country/region? → Use **Country Search (countryCodes)**\n   - Find merchants by province/city? → Use **provinceIds, cityIds**\n   - Find merchants near a location? → Use **Nearby Search (geoDistance)**\n   - Filter by industry or contact availability? → Use **industries, existPhone, existWebsite**\n   - Find shops by name? → Use **companyNames**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Country search for regional coverage**: Use `countryCodes` with keywords\n2. **Nearby search for precise location**: Use `geoDistance` with location and distance\n\n### Parameter Guidelines\n\n- **Keywords**: Use English terms for better results\n- **Filters**: Use `existPhone=true` or `existWebsite=true` to filter by contact availability\n- **Industry filter**: Use `industries` to filter by business type\n- **Province/City filter**: Use `provinceIds` and `cityIds` to filter by specific province or city\n- **Shop name filter**: Use `companyNames` to find shops by specific name\n- **Nearby search**: distance format like \"5km\", recommended range 1-10km\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1775808420884\n}\n\nFile v1.0.1:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.1:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.1:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度\n\nFile v1.0.1:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.1:requirements.txt\n\nhttpx>=0.23.0\n\nArchive v1.0.0: 11 files, 16424 bytes\n\nFiles: references/city-list-api.md (223b), references/country-list-api.md (261b), references/merchants-search-api.md (1356b), references/province-list-api.md (227b), requirements.txt (14b), scripts/auth.py (5951b), scripts/common.py (14449b), scripts/geography_list.py (4028b), scripts/merchants_search.py (6533b), SKILL.md (7577b), _meta.json (149b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: upkuajing-map-merchants-search\ndescription: Official skill for upkuajing (跨境魔方). Search merchants on map (地图获客). Find merchants by region or nearby location, get merchant details including name, address, phone, industry, and more. Includes geographic data APIs (country, province, city lists) to support location-based search.\nmetadata: {\"version\":\"1.0.0\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Region Search (search_type=1)**: Search by country/province/city\n- **Nearby Search (search_type=2)**: Search by latitude/longitude and radius\n\n**Examples**:\n```bash\n# Region search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"search_type\":1,\"words\":[\"restaurant\"],\"area_list\":[{\"country_code\":\"BR\",\"province_id\":0,\"city_id\":0}]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"search_type\":2,\"words\":[\"hotel\"],\"lng\":\"113.82745\",\"lat\":\"23.11019\",\"radius\":5000}'\n```\n\n**Task Resume**: Use `--task_id` to resume interrupted large queries:\n```bash\npython scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000\n```\n\n### Geography List (`geography_list.py`)\n\nGet geographic hierarchy data for building search parameters.\n\n**Examples**:\n```bash\n# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1\n```\n\n## API Key and UpKuaJing Account\n\n- **API Key**: Stored in `~/.upkuajing/.env` file as `UPKUAJING_API_KEY`\n- **First check**: If not set, prompt user to provide or apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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: Guide user to apply at [UpKuaJing Open Platform](https://developer.upkuajing.com/)\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\n- Newly applied API key: Register and login at [UpKuaJing Open Platform](https://developer.upkuajing.com/), then bind account\n\n## Fees\n\n**Merchant search 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### Merchant Search Billing Rules\n\nBilled by **number of calls**, each call returns up to 100 records:\n- Number of calls: `ceil(query_count / 100)` times\n- **Whenever query_count > 100, 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### Geography List Billing Rules\n\n**Free of charge** — No fees for country/province/city list queries.\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## Workflow\n\n### Decision Guide\n\n| User Intent | Use API |\n|-------------|---------|\n| \"Find merchants by region\" | Merchants Search (search_type=1) |\n| \"Find merchants near a location\" | Merchants Search (search_type=2) |\n| \"Get country/province/city data\" | Geography List |\n\n### Search Flow\n\n1. **For region search**: Use Geography List to get country/province/city IDs first\n2. **Build search parameters**: Combine keywords with geographic filters\n3. **Execute search**: Use merchants_search.py with appropriate parameters\n4. **Handle large queries**: Use task_id to resume interrupted searches\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\n- **Invalid parameters**: **Must first check the corresponding API documentation in references/ directory**, get correct parameter names and formats from documentation, do not guess\n\n## Best Practices\n\n### Choosing the Right Search Mode\n\n1. **Understand user intent**:\n   - Find merchants by region? → Use **Region Search (search_type=1)**\n   - Find merchants near a location? → Use **Nearby Search (search_type=2)**\n\n2. **Check API documentation**:\n   - **Before executing searches, must first check the corresponding API reference documentation**\n   - Merchant search: Check [references/merchants-search-api.md](references/merchants-search-api.md)\n   - Geography list: Check corresponding files in references/ directory\n   - Do not guess parameter names, get accurate parameter names and formats from documentation\n\n### Location-Based Search\n\n1. **Get geographic data first**: Use geography_list.py to get valid country/province/city IDs\n2. **Use region search for large areas**: search_type=1 with area_list\n3. **Use nearby search for precise location**: search_type=2 with lng/lat/radius\n\n### Parameter Guidelines\n\n- **Keywords (words)**: Use English terms for better results\n- **Geographic filters**: Combine country_code with province_id/city_id for precision\n- **Nearby search**: radius is in meters, recommended range 1000-10000\n- **Search quantity affects API response time**, set reasonable query_count for large queries\n\n### Handling Results\n\n1. **Be mindful of file size for large queries**: jsonl files can grow large\n2. **Use task_id to resume interrupted queries**: avoid redundant API calls and fees\n\n## Notes\n\n- Country codes use ISO 3166-1 alpha-2 format (e.g., CN, US, BR)\n- File paths use forward slashes on all platforms\n- **Do not** guess parameter names, get accurate parameter names and formats from documentation\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\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1775787650729\n}\n\nFile v1.0.0:references/city-list-api.md\n\n# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.0:references/country-list-api.md\n\n# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名\n\nFile v1.0.0:references/merchants-search-api.md\n\n# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--search_type`：搜索模式（1=区域搜索，2=附近搜索）\n- `--words`：搜索词列表（JSON数组）\n- `--exclude_words`：过滤关键词列表（JSON数组）\n- `--area_list`：区域搜索 地区列表（search_type=1时必填，JSON对象数组）\n  - country_code：国家二字码（如CN、US）\n  - province_id：省份ID\n  - city_id：城市ID\n- `--lng`：经度（search_type=2时必填）\n- `--lat`：纬度（search_type=2时必填）\n- `--radius`：范围半径/米（search_type=2时必填）\n\n## 响应数据\n\n### 商户标识\n- placeId：商铺ID\n- name：商铺名称\n- industry：商铺行业\n\n### 地址信息\n- country：商铺所属国\n- country_iso_code：商铺所属国二字码\n- province_name：商铺所属州省\n- province_id：商铺所属州省ID\n- city_name：商铺所属城市\n- city_id：商铺所属城市ID\n- street：商铺街道\n- address：商铺地址\n- addressDetail：商铺详细地址\n- postcode：商铺邮编\n\n### 联系方式\n- phone：商铺电话\n- phone_clean：清理后的电话\n- phone_country_code：电话国家区号\n- website：商铺网址\n\n### 其他\n- avatar_url：商铺头像\n- location：商铺地点（JSON：lng, lat）\n- imgs：商铺图片（JSON数组）\n- videos：商铺视频（JSON数组）\n- score：商铺评分\n\nFile v1.0.0:references/province-list-api.md\n\n# 州省列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 province）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 州省信息\n- id：州省ID\n- nameEn：英文名\n- name：名字\n\nFile v1.0.0:requirements.txt\n\nhttpx>=0.23.0","readmeExcerpt":"Skill: Google Maps business data extraction paired with bulk search and batch data download capabilities for global B2B lead generation. Filter search results bycountry, state, city, district, search radius, industry and product keywords to batch collect business names, physical addresses and full contact details.Precisely pinpoint overseas buyers and local enterprises to streamline end-to-end lead development workfl","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50"},{"language":"bash","snippet":"python scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000"},{"language":"bash","snippet":"# Get country list\npython scripts/geography_list.py --type country\n\n# Get province list for a country\npython scripts/geography_list.py --type province --country_id 1\n\n# Get city list for a country\npython scripts/geography_list.py --type city --country_id 1"},{"language":"bash","snippet":"python scripts/error_report.py --params '{\"requestPath\":\"/agent/map/search\",\"requestId\":\"f47ac10b58cc4372a5670e02b2c3d479\",\"context\":\"Merchant search failed with a server error\"}'"},{"language":"bash","snippet":"# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scripts/merchants_search.py \\\n  --params '{\"companyNames\":[\"car care\"],\"countryCodes\":[\"TH\"]}' \\\n  --query_count 100\n\n# Multi-filter search - Combine multiple filters\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\"],\"provinceIds\":[\"1447\"],\"industries\":[\"Cars\"],\"existPhone\":true}' \\\n  --query_count 50"},{"language":"bash","snippet":"python scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: upkuajing-map-merchants-search\ndescription: \"Pull bulk Google Maps business data with radius‑based filters. Gather merchant contact information, analyze market density and find distributors or overseas buyers for offline business expansion.\\n\\nTrigger: Google maps business scraper, bulk merchant data download, radius‑based lead search, distributor sourcing, competitor store analysis, regional market research, offline sales‑lead generation\"\nmetadata: {\"version\":\"1.0.6\",\"homepage\":\"https://www.upkuajing.com\",\"clawdbot\":{\"emoji\":\"📍\",\"requires\":{\"bins\":[\"python\"],\"env\":[\"UPKUAJING_API_KEY\"]},\"primaryEnv\":\"UPKUAJING_API_KEY\"}}\n---\n\n# UpKuaJing Map Merchants Search\n\nQuery merchant information using the UpKuaJing Open Platform API. This skill provides map-based merchant search with two search modes: region search and nearby search.\n\n## Overview\n\nThis skill provides access to UpKuaJing's map merchant database through:\n- **Merchants Search** (`merchants_search.py`): Search merchants by keywords and location\n- **Geography List** (`geography_list.py`): Get country/province/city lists for location parameters\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/merchants_search.py`. **Do NOT use** shell compound commands like `cd scripts && python merchants_search.py`.\n\n## Two Main APIs\n\n### Merchant Search (`merchants_search.py`)\n\nSearch merchants by keywords and geographic area.\n\n**Parameters**: See [Merchants Search API](references/merchants-search-api.md)\n\n**Two Search Modes**:\n- **Country Search**: Search by country/province/city, keywords, and filters\n- **Nearby Search**: Search by latitude/longitude and radius using `geoDistance`\n\n**Examples**:\n```bash\n# Country search - Find restaurants in Brazil\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"BR\"]}' \\\n  --query_count 100\n\n# Multi-country search with phone filter - Find restaurants in US or China with phone\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"countryCodes\":[\"US\",\"CN\"],\"existPhone\":true}' \\\n  --query_count 50\n\n# Industry filter - Find car dealers in Thailand\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"car dealer\"],\"countryCodes\":[\"TH\"],\"industries\":[\"Cars\"]}' \\\n  --query_count 100\n\n# Nearby search - Find hotels within 5km of a point\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"hotel\"],\"geoDistance\":{\"location\":{\"lat\":31.1104643,\"lon\":29.7602221},\"distance\":\"5km\"}}'\n\n# Province and city filter - Find restaurants in a specific province/city\npython scripts/merchants_search.py \\\n  --params '{\"keywords\":[\"restaurant\"],\"provinceIds\":[\"2277\"],\"cityIds\":[\"19975\"]}' \\\n  --query_count 50\n\n# Shop name filter - Find shops by specific name\npython scrip"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn76ywjzma121r2rh959ejsf49834c6x\",\n  \"slug\": \"upkuajing-map-merchants-search\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1787562692267\n}"},{"path":"references/city-list-api.md","content":"# 城市列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 city）\n- `--country_id`：国家ID（必需）\n\n## 响应数据\n\n### 城市信息\n- id：城市ID\n- nameEn：英文名\n- name：名字"},{"path":"references/country-list-api.md","content":"# 国家列表 API 参考\n\n## python脚本参数\n- `--type`：地理类型（固定为 country）\n\n## 响应数据\n\n### 国家信息\n- id：国家ID\n- area：地区\n- code：国家二字码\n- icon：国旗图标URL\n- nameEn：国家英文名\n- name：国家名"},{"path":"references/merchants-search-api.md","content":"# 商户列表搜索 API 参考\n\n## python脚本参数\n- `--params`：搜索参数JSON字符串\n- `--task_id`：任务ID（断点续查用）\n- `--query_count`：期望获取的总记录数（非必填，默认20）\n\n## 请求参数 (params JSON)\n\n### 核心参数\n- `keywords`：搜索词列表（JSON数组）\n- `keywordsFilter`：过滤关键词列表（JSON数组）\n- `countryCodes`：国家二字码列表（JSON数组，如[\"CN\", \"US\"]）\n- `countryCodesFilter`：过滤二字码列表（JSON数组）\n- `provinceIds`：省份ID列表（JSON数组）\n- `cityIds`：城市ID列表（JSON数组）\n- `companyNames`：店铺名称列表（JSON数组）\n- `industries`：行业名称列表（JSON数组）\n- `existPhone`：存在电话筛选（boolean，true=只返回有电话的商户）\n- `existWebsite`：存在网址筛选（boolean，true=只返回有网址的商户）\n- `cursor`：搜索游标（分页用）\n\n### 坐标查询（附近搜索）\n- `geoDistance.location.lat`：纬度\n- `geoDistance.location.lon`：经度\n- `geoDistance.distance`：搜索半径（如\"5km\"）\n\n## 响应数据\n\n### 商户标识\n- companyId：公司ID\n- name：名称\n- industry：行业\n\n### 地址信息\n- country：国家名称\n- countryIsoCode：国家二字码\n- provinceName：省份名称\n- provinceId：省份ID\n- cityName：城市名称\n- cityId：城市ID\n- addressDetail：详细地址\n- postcode：邮编\n\n### 坐标信息\n- location.lat：纬度\n- location.lon：经度"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1273,"uniquenessScore":36,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:48:39.685Z","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:48:39.685Z","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:54:42.373Z","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"}]}}}