Google Maps 邮箱提取器 Apify 技能

概述

该技能帮助 AI 代理运行 Apify 的 Google Maps 邮箱提取器 actor，用于从 Google Maps 中批量获取公开的企业邮箱线索。

默认 actor：

• Actor ID：f3dlnXVnBc6v8JMNK
• Actor 名称：x_guru/google-maps-email-extractor
• 商店页面：https://apify.com/x_guru/google-maps-email-extractor
• 控制台源码：https://console.apify.com/actors/f3dlnXVnBc6v8JMNK/source

当用户提出以下请求时，请使用此技能：

• 从 Google Maps 构建本地企业邮箱线索列表
• 为牙医、屋顶承包商、律师、摄影师、健身房、诊所、餐厅、建筑承包商、广告公司、房地产中介等本地细分领域查找公开邮箱
• 为 Google Maps 地点补充网站、邮箱、电话、社交链接、评分、评论数、地址及地理坐标等信息
• 按关键词和地理位置执行 Google Maps 搜索，并仅输出邮箱（emailsOnly）
• 基于精确的 Google Maps URL 或 Google Place ID 运行，并返回邮箱线索行数据
• 通过 maxTotalChargeUsd 控制 Apify 费用支出
• 将结果导出至 Sheets、Airtable、n8n、CRM、BI 工具、CSV、JSON 或其他 agent 工作流

快速工作流

1. 明确细分领域、地理位置、期望保存的邮箱线索数量，以及是否允许提取人名风格邮箱（如 john@xxx.com）。
2. 先构建一个小型 payload：包含 searchStringsArray、locationQuery、maxCrawledPlacesPerSearch、contactResultMode: "emailsOnly"、website: "withWebsite" 和 language。
3. 若用户已提供精确的 Google Maps 来源，则使用 startUrls 或 placeIds 字段。
4. 仅当目标细分领域将邮箱隐藏在“团队页”、“员工页”、“法律声明页”、“版权页”或“联系页”等深层页面中时，才提高 contactPagesLimit 值。
5. 当搜索范围过广或结果噪声较大时，可启用分类/评分/网站等过滤条件。
6. 若费用控制重要，请设置 Apify 的预算防护参数 maxTotalChargeUsd。
7. 运行 scripts/google_maps_email_extractor_actor.py 脚本，或直接调用 Apify API。
8. 返回简洁的统计指标与邮箱线索行数据。若实际返回行数低于预期，请检查 RUN_SUMMARY 获取诊断信息。

Payload 规则

• 标准搜索使用 searchStringsArray、locationQuery、maxCrawledPlacesPerSearch 和 language。
• 默认输出模式为 contactResultMode: "emailsOnly"。
• 请始终设置 website: "withWebsite" 以启用邮箱提取，因为公开邮箱通常来源于企业官网。
• maxCrawledPlacesPerSearch 表示期望最终保存的邮箱线索数量；actor 可能在内部扫描更多 Google Maps 候选地点，以满足该目标。
• contactPagesLimit 默认值为 2；如需更深度挖掘邮箱，可设为 3–5。
• includePersonalData=false 将主要保留通用公司邮箱（如 info@、sales@、hello@、contact@），排除人名风格邮箱。
• startUrls 必须为对象数组格式：[{"url": "https://www.google.com/maps/..."}]。
• placeIds 接受原始 Google Place ID 或兼容的 place_id: 格式值。
• contactResultMode 必须为 emailsOnly、contactsOnly 或 allPlaces 之一。
• 付费过滤器包括：categoryFilterWords、placeCategories、customPlaceCategories、searchMatching、placeMinimumStars、website 和 skipClosedPlaces。
• 搜索区域可通过以下任一字段指定：locationQuery、countryCode、city、state、county、postalCode、customGeolocation、locationBounds 或 strictLocationBounds。
• 此处不支持评论相关字段（如 maxReviews）。如需抓取评论内容，请使用独立的 Google Maps Reviews Scraper 技能。

认证

使用环境变量中的 Apify API token：

export APIFY_TOKEN='apify_api_xxx'

切勿在面向用户的输出中硬编码或打印完整 token。

脚本使用方法

所附脚本仅依赖 Python 标准库。

执行快速邮箱线索搜索：

APIFY_TOKEN='apify_api_xxx' 
python3 scripts/google_maps_email_extractor_actor.py quick-search 
  --query "wedding photographer" 
  --location "Austin, Texas, USA" 
  --limit 25 
  --budget-usd 1

按 Google Maps URL 执行：

APIFY_TOKEN='apify_api_xxx' 
python3 scripts/google_maps_email_extractor_actor.py quick-url 
  --url "https://www.google.com/maps/search/roofing+contractor+Dallas,+TX" 
  --limit 50 
  --budget-usd 1

按 Place ID 执行：

APIFY_TOKEN='apify_api_xxx' 
python3 scripts/google_maps_email_extractor_actor.py quick-place-id 
  --place-id "ChIJE2Flwy-1RIYRWqJr_ZiMGc" 
  --budget-usd 1

运行自定义 JSON 输入：

APIFY_TOKEN='apify_api_xxx' 
python3 scripts/google_maps_email_extractor_actor.py run 
  --input-file references/sample_input.json 
  --budget-usd 1

推荐输入示例

本地邮箱线索

{
  "searchStringsArray": ["wedding photographer"],
  "locationQuery": "Austin, Texas, USA",
  "maxCrawledPlacesPerSearch": 100,
  "contactResultMode": "emailsOnly",
  "contactPagesLimit": 2,
  "includePersonalData": true,
  "website": "withWebsite",
  "skipClosedPlaces": true,
  "language": "en"
}

仅通用公司邮箱

{
  "searchStringsArray": ["commercial electrician"],
  "locationQuery": "Denver, Colorado, USA",
  "maxCrawledPlacesPerSearch": 100,
  "contactResultMode": "emailsOnly",
  "includePersonalData": false,
  "website": "withWebsite"
}

精确来源

{
  "startUrls": [
    {
      "url": "https://www.google.com/maps/search/marketing+agency+near+Chicago,+IL"
    }
  ],
  "maxCrawledPlacesPerSearch": 50,
  "contactResultMode": "emailsOnly",
  "website": "withWebsite"
}

输出契约

执行器返回 JSON 格式结果，包含以下字段：

• ok
• actorId
• fetchedAt
• inputUsed
• itemCount
• rows[]

rows[] 为 actor 数据集条目，关键字段分组如下：

• 企业信息：title、categoryName、categories、rank、searchString
• 邮箱信息：emails、emailDetails.email、emailDetails.type、emailDetails.sourceUrl、emailDetails.domainMatch
• 联系方式：website、phone、phoneUnformatted、additionalPhones、各类社交平台资料数组
• 地址信息：address、street、city、state、postalCode、countryCode、location、plusCode
• Google 指标：totalScore、reviewsCount、reviewsDistribution、营业状态标记
• Google ID：placeId、fid、cid、kgmid、url、searchPageUrl
• 诊断信息：contactSignals、contactStatus、additionalInfo.companyContacts、scrapedAt

完整契约详见 references/input-output-contract.md。

Agent 响应规则

• 若 rows 为空，请说明任务执行成功，但未保存到邮箱线索，并建议检查 RUN_SUMMARY。
• 若返回行数少于请求值，请解释原因：可能因目标细分领域/地区公开邮箱较少，或预算限制/过滤条件导致部分结果未被保存。
• 若在 contactsOnly 或 allPlaces 模式下某条记录的 emails 字段为空，请说明该记录因其他有效联系信息（如电话、网站）而被保留。
• 需向用户说明：公开邮箱提取属于尽力而为（best-effort）行为，因各企业对其官网发布内容拥有完全控制权。
• 对任何关注费用支出的用户，均应主动使用 maxTotalChargeUsd 参数进行防护。
• 不得承诺从此 actor 获取评论正文或完整评论数据集；评论相关内容请使用独立的 Google Maps Reviews Scraper 技能。

参考资料

• references/input-output-contract.md
• references/sample_input.json
• references/troubleshooting.md