提供谷歌地图线下商户数据批量查询、下载，实现批量搜索，支持按国家、省、市、区域、地域、半径、行业、产品关键词等条件筛选，批量获取商家名称、地址、联系方式等信息，精准挖掘海外采购商，本地推广，提升客户开发效率。帮助地推销售、经销商、品牌团队、区域经理按地理位置、商圈定位商家、分析区域市场密度与覆盖范围、适合区域扩张开店、代理商/经销商寻源、竞品门店点位情报与选址分析，适用于地推获客、线下渠道招帮助地推销售、经销商、品牌团队、区域经理按地理位置、商圈定位商家、分析区域市场密度与覆盖范围、生成销售线索——适合区域

跨境魔方地图商户搜索

使用跨境魔方开放平台API查询商户信息。本技能提供基于地图的商户搜索，支持两种搜索模式：区域搜索和附近搜索。

概述

本技能通过以下方式访问跨境魔方的地图商户数据库：

• 商户搜索 (merchants_search.py)：按关键词和地理位置搜索商户
• 地理列表 (geography_list.py)：获取国家/州省/城市列表用于构建位置参数

运行脚本

环境配置

1. 检查 Python：python --version
2. 安装依赖：pip install -r requirements.txt

脚本目录：scripts/*.py 运行示例：python scripts/*.py

重要：始终使用直接脚本调用，如 python scripts/merchants_search.py。不要使用 shell 复合命令如 cd scripts && python merchants_search.py。

两个主要API

商户搜索 (merchants_search.py)

按关键词和地理区域搜索商户。

参数：见 商户搜索API

两种搜索模式：

• 区域搜索：按国家/州省/城市、关键词和筛选条件搜索
• 附近搜索：使用 geoDistance 按经纬度坐标和半径搜索

示例：

# 国家搜索 - 查找巴西的餐厅
python scripts/merchants_search.py \
  --params '{"keywords":["restaurant"],"countryCodes":["BR"]}' \
  --query_count 100

# 多国家搜索并筛选有电话的 - 查找美国或中国有电话的餐厅
python scripts/merchants_search.py \
  --params '{"keywords":["restaurant"],"countryCodes":["US","CN"],"existPhone":true}' \
  --query_count 50

# 行业筛选 - 查找泰国的汽车经销商
python scripts/merchants_search.py \
  --params '{"keywords":["car dealer"],"countryCodes":["TH"],"industries":["Cars"]}' \
  --query_count 100

# 附近搜索 - 查找某点5公里范围内的酒店
python scripts/merchants_search.py \
  --params '{"keywords":["hotel"],"geoDistance":{"location":{"lat":31.1104643,"lon":29.7602221},"distance":"5km"}}'

# 省份/城市筛选 - 查找特定省份/城市的餐厅
python scripts/merchants_search.py \
  --params '{"keywords":["restaurant"],"provinceIds":["2277"],"cityIds":["19975"]}' \
  --query_count 50

# 店铺名称筛选 - 按名称查找店铺
python scripts/merchants_search.py \
  --params '{"companyNames":["car care"],"countryCodes":["TH"]}' \
  --query_count 100

# 多条件组合搜索 - 组合多个筛选条件
python scripts/merchants_search.py \
  --params '{"keywords":["restaurant"],"countryCodes":["US"],"provinceIds":["1447"],"industries":["Cars"],"existPhone":true}' \
  --query_count 50

任务恢复：使用 --task_id 恢复中断的大规模查询：

python scripts/merchants_search.py --task_id 'your-task-id-here' --query_count 2000

地理列表 (geography_list.py)

获取地理层级数据用于构建搜索参数。

示例：

# 获取国家列表
python scripts/geography_list.py --type country

# 获取某个国家的州省列表
python scripts/geography_list.py --type province --country_id 1

# 获取某个国家的城市列表
python scripts/geography_list.py --type city --country_id 1

API密钥与跨境魔方账号

• API密钥：存储在 ~/.upkuajing/.env 文件中，变量名为 UPKUAJING_API_KEY
• 首先检查：如果未设置，提示用户提供或前往 跨境魔方开放平台 申请

API密钥未设置

首先检查 ~/.upkuajing/.env 文件中是否有 UPKUAJING_API_KEY； 如果 UPKUAJING_API_KEY 未设置，提示用户选择：

1. 用户已有密钥：用户自行添加（手动添加到 ~/.upkuajing/.env 文件）
2. 用户没有密钥：引导用户前往 跨境魔方开放平台 申请 等待用户选择；

账户充值

当API返回余额不足时，解释并引导用户充值：

1. 创建充值订单 (auth.py --new_rec_order)
2. 根据订单响应，发送支付页面链接给用户，引导用户打开链接支付，用户确认支付成功后继续

获取账户信息

获取UPKUAJING_API_KEY对应账户信息的脚本：auth.py --account_info

API密钥与跨境魔方账号

• 新申请的API密钥：需要在 跨境魔方开放平台 注册登录后绑定账户

费用

商户搜索API调用收费，不同接口计费方式不同。 最新价格：用户可访问 详细价格说明 或者使用：python scripts/auth.py --price_info（返回接口完整定价）

商户搜索计费规则

按调用次数计费，每次返回最多100条记录：

• 调用次数：ceil(query_count / 100) 次
• 只要 query_count > 100，执行前必须：
  1. 告知用户预计调用次数
  2. 停止，等待用户在独立消息中明确确认后，再执行脚本

地理列表计费规则

免费使用 — 国家/省/市列表查询不收取任何费用。

费用确认原则

任何产生费用的操作必须先告知用户并等待明确确认，不得在通知的同一消息中执行。

工作流程

决策指南

搜索流程

1. 区域搜索：先使用地理列表获取国家/州省/城市ID
2. 构建搜索参数：将关键词与地理过滤器结合
3. 执行搜索：使用相应参数运行 merchants_search.py
4. 处理大规模查询：使用 task_id 恢复中断的搜索

错误处理

• API密钥无效/不存在：检查 ~/.upkuajing/.env 文件中的 UPKUAJING_API_KEY
• 余额不足：引导用户充值
• 参数无效：必须首先查看 references/ 目录中对应的API文档，从文档中获取正确的参数名和格式，不要猜测

最佳实践

选择正确的搜索模式

1. 理解用户意图：

   • 按国家/区域查找商户？ → 使用国家搜索 (countryCodes)
   • 按省份/城市查找商户？ → 使用省份/城市搜索 (provinceIds, cityIds)
   • 在某个位置附近查找商户？ → 使用附近搜索 (geoDistance)
   • 按行业或联系方式筛选？ → 使用 industries, existPhone, existWebsite
   • 按店铺名称查找？ → 使用 companyNames

2. 查看API文档：

   • 执行搜索前，必须先查看对应的 API 参考文档
   • 商户搜索：查看 references/merchants-search-api.md
   • 地理列表：查看 references/ 目录下对应文件
   • 不要猜测参数名称，从文档中获取准确的参数名称和格式

基于位置的搜索

1. 国家搜索覆盖大面积区域：使用 countryCodes 配合关键词
2. 附近搜索精确定位：使用 geoDistance 配合位置和距离

参数指南

• 关键词：使用英文关键词以获得更好的结果
• 筛选条件：使用 existPhone=true 或 existWebsite=true 按联系方式可用性筛选
• 行业筛选：使用 industries 按商业类型筛选
• 省份/城市筛选：使用 provinceIds 和 cityIds 按特定省份或城市筛选
• 店铺名称筛选：使用 companyNames 按店铺名称筛选
• 附近搜索：distance 格式如 "5km"，建议范围 1-10km
• 搜索数量会影响接口的响应时间，大量查询时注意设置合理的 query_count

处理结果

1. 大数量查询时注意文件大小：jsonl 文件可能较大
2. 使用 task_id 恢复中断的查询：避免重复调用和费用浪费

注意事项

• 国家代码使用 ISO 3166-1 alpha-2 格式（如 CN、US、BR）
• 文件路径在所有平台上使用正斜杠
• 不要猜测参数名，从文档中获取准确的参数名和格式
• 禁止输出技术参数格式：不要在回复中展示代码样式的参数，应将其转换为自然语言
• 不要估算或猜测每次调用的费用 — 使用 python scripts/auth.py --price_info 获取准确定价信息

相关技能

其他您可能会用到的跨境魔方技能：

• linkedin-person-search — 领英找人
• global-company-person-search — 全球企业库找人
• linkedin-company-search — 领英找公司
• global-company-search — 全球企业库找公司
• global-company-shareholder — 全球企业库股东查询
• global-company-employee — 全球企业库员工查询
• global-company-person-colleague — 全球企业库同事查询
• global-company-person-alumni — 全球企业库校友查询
• global-company-person-experience — 全球企业库工作经历查询
• global-company-person-education — 全球企业库教育经历查询
• global-company-person-school-detail — 全球企业库学校详情查询
• upkuajing-global-company-people-search — 全球企业与人员搜索
• upkuajing-customs-trade-company-search — 海关贸易企业搜索
• upkuajing-email-tool — 发送邮件和管理邮件任务
• upkuajing-sms-tool — 发送短信和管理短信任务
• upkuajing-contact-info-validity-check — 联系方式有效性检测
• phone-validity-check — 电话号码有效性检测
• email-validity-check — 邮箱地址有效性检测
• domain-validity-check — 域名有效性检测