基于地理位置（Geo-location）的 Telegram 机器人周边商户与服务检索功能实现

在 Telegram 机器人中加入基于地理位置的周边商户与服务检索，可以让用户直接查找附近的餐厅、维修点、药店、活动场所或本地服务。相比让用户手动输入地址，位置检索流程更短，也更适合移动端即时决策。

但真正可用的 Geo-location 功能并不只是接收一组经纬度，还涉及 Telegram Bot API、空间数据库、距离排序、隐私保护和结果交互。下面将以可落地的技术架构，完整拆解实现过程。

📍 Telegram 地理位置检索的工作原理

Telegram Bot API 允许用户向机器人发送包含 latitude 和 longitude 的位置消息。机器人接收坐标后，可以查询数据库中的商户位置，并按照直线距离或业务规则返回附近结果。

一条完整链路通常包括请求定位、接收坐标、空间查询、结果排序、消息展示五个环节。机器人本身不会自动获得用户位置，必须由用户主动点击授权按钮或发送位置。

需要理解的 Bot API 数据结构

当用户发送当前位置时，Webhook 更新中的 message.location 会携带坐标。典型数据如下：

{
  "message": {
    "chat": {
      "id": 123456789,
      "type": "private"
    },
    "location": {
      "latitude": 31.230416,
      "longitude": 121.473701
    }
  }
}

部分位置消息还可能包含水平精度、航向或实时位置周期等字段。周边商户查询通常只需使用经纬度，但可以结合精度字段判断结果是否值得信任。

🧭 第一步：向用户请求当前位置

最直接的做法是发送带有 request_location 属性的 ReplyKeyboardButton。该能力只适用于机器人与用户之间的私聊，不能把群聊中的定位授权当作默认方案。

{
  "chat_id": 123456789,
  "text": "请发送当前位置，以查找附近商户",
  "reply_markup": {
    "keyboard": [
      [
        {
          "text": "发送我的位置",
          "request_location": true
        }
      ]
    ],
    "resize_keyboard": true,
    "one_time_keyboard": true
  }
}

按钮文案应明确说明定位用途，避免使用含糊的“继续”或“授权”字样。机器人还应提供手动输入城市、商圈或地址的替代入口，兼容关闭定位权限的用户。

Webhook 接收与基础校验

服务端收到更新后，应先验证消息来源、坐标范围和会话状态。纬度必须位于 -90 至 90，经度必须位于 -180 至 180，同时要限制重复请求频率。

const location = update.message?.location;

if (!location) {
  return sendMessage(chatId, "请点击定位按钮或输入所在区域");
}

const { latitude, longitude } = location;

if (
  latitude < -90 || latitude > 90 ||
  longitude < -180 || longitude > 180
) {
  return sendMessage(chatId, "位置数据无效，请重新发送");
}

🗄️ 第二步：设计可检索的商户位置数据

商户表至少需要名称、分类、地址、营业状态、经纬度和更新时间。若数据量超过几万条，建议使用 PostgreSQL 与 PostGIS，通过空间索引降低附近查询的计算成本。

CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE merchants (
  id BIGSERIAL PRIMARY KEY,
  name VARCHAR(120) NOT NULL,
  category VARCHAR(60) NOT NULL,
  address TEXT,
  is_open BOOLEAN DEFAULT TRUE,
  location GEOGRAPHY(POINT, 4326) NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX merchants_location_gix
ON merchants USING GIST (location);

使用 GEOGRAPHY(POINT, 4326) 可以按地球表面距离计算，结果以米为单位。写入坐标时需要特别注意 PostGIS 点参数采用经度在前、纬度在后的顺序。

执行附近商户查询

下面的 SQL 会检索用户五公里范围内仍在营业的商户，并按距离从近到远返回前十条。ST_DWithin 可优先利用空间索引，适合先筛选范围。

SELECT
  id,
  name,
  category,
  address,
  ST_Distance(
    location,
    ST_SetSRID(ST_MakePoint($1, $2), 4326)::geography
  ) AS distance_meters
FROM merchants
WHERE is_open = TRUE
  AND ST_DWithin(
    location,
    ST_SetSRID(ST_MakePoint($1, $2), 4326)::geography,
    $3
  )
ORDER BY distance_meters ASC
LIMIT 10;

参数 $1、$2 和 $3 分别代表经度、纬度和搜索半径。务必使用参数化查询，不要把用户输入直接拼接进 SQL。

🔎 第三步：建立分类、距离与排序策略

仅按距离排序不一定能提供最佳答案，因为最近的商户可能已经停业、评分较低或与用户需求不符。更合理的方式是综合距离、营业状态、分类相关度、数据新鲜度和服务质量计算排序分数。

初始搜索半径可以设置为 1 公里，没有结果时逐步扩大到 3 公里和 5 公里。与其一次返回几十条信息，不如先展示 5 至 10 条，并提供“扩大范围”和“查看更多”按钮。

分类筛选与会话状态

机器人可以先让用户选择餐饮、购物、医疗、维修或生活服务，再请求位置。也可以先接收位置，然后通过 InlineKeyboardMarkup 展示分类筛选按钮。

服务端应将当前分类、半径、分页游标与用户会话关联，但不要长期保存精确坐标。对于高并发场景，可以使用 Redis 设置几分钟的会话过期时间。

💬 第四步：优化 Telegram 检索结果展示

每条结果应优先呈现商户名称、分类、距离、营业状态和简短地址。距离小于一公里时可以显示米，大于一公里时再转换为保留一位小数的公里数。

咖啡实验室
分类：咖啡与简餐
距离：620 米
状态：营业中
地址：示例路 88 号

操作区可以提供查看地图、联系商户、下一页和扩大范围等按钮。地图跳转链接中的坐标必须经过编码和格式校验，商户电话也应来自经过验证的数据源。

若希望用户在任意聊天窗口中调用机器人，可进一步启用 Telegram Inline Mode，并通过 BotFather 配置内联位置能力。此模式应同时处理用户拒绝提供位置的情况，并返回通用搜索或手动选区入口。

🔐 位置隐私、安全与合规要求

精确位置属于敏感数据，机器人必须说明收集目的、使用范围和保留期限。对于一次性周边查询，建议在完成检索后立即丢弃原始坐标，仅保留匿名化的性能指标。

Webhook 服务必须使用 HTTPS，并校验 Telegram 设置 Webhook 时配置的 secret_token 请求头。还应实施请求限流、数据库最小权限、日志脱敏和异常访问告警。

日志中不要记录完整经纬度、电话号码或 Telegram 用户标识的组合。调试时可降低坐标精度，例如只保留两位小数，但生产环境仍应根据当地隐私法规评估是否允许留存。

数据质量比算法更重要

周边检索体验高度依赖商户数据是否真实、坐标是否准确以及营业时间是否及时更新。应建立商户认领、人工审核、用户纠错和过期数据复查机制。

如果数据来自第三方地图或商业接口，还要确认授权范围、缓存限制和展示规范。不要抓取受版权或服务条款限制的数据并直接用于商业机器人。

🚀 上线前的测试与性能检查

功能测试需要覆盖正常定位、拒绝授权、坐标无效、附近无结果、商户停业和分页失效等场景。还应分别在 Telegram iOS、Android 和 Desktop 客户端验证按钮与消息格式。

性能测试应观察空间查询耗时、Webhook 响应时间和高峰期并发量。耗时任务可以交给队列异步执行，但机器人必须尽快响应用户，避免 Telegram 重复投递更新。

生产环境可缓存热门区域和常见分类的结果，但缓存键不宜包含可识别个人的精确坐标。按网格或 Geohash 降低位置精度后缓存，通常能在性能和隐私之间取得更稳妥的平衡。

❓ 常见问题解答（FAQ）

Telegram 机器人能否在后台自动获取用户位置？

不能，机器人必须由用户主动发送位置或同意内联位置请求。机器人不应尝试绕过客户端权限机制获取定位信息。

为什么 request_location 按钮在群组中不能正常使用？

request_location 类型的键盘按钮面向私聊场景。群组中的机器人应引导用户打开私聊，或让用户手动发送地点名称。

小型项目一定要安装 PostGIS 吗？

数据量很小时，可以使用 Haversine 公式计算直线距离。随着商户数量和查询并发增长，PostGIS 的空间索引、范围过滤和地理计算能力会更可靠。

如何处理用户附近没有商户的情况？

机器人可以逐级扩大半径，或建议切换分类和手动选择区域。消息中应明确说明当前搜索范围，避免让用户误以为系统故障。

如何提高周边服务检索结果的准确性？

除了距离，还应结合分类匹配、营业时间、商户更新时间、用户反馈和数据可信度排序。定期清理重复、迁址和停业记录，比单纯调整排序权重更有效。

一个成熟的 Telegram 周边商户机器人，应同时具备低摩擦定位、可靠空间查询、清晰结果交互和严格隐私保护。先从单城市、少量分类和可验证的数据开始，再根据真实查询日志扩展覆盖范围，通常是风险最低的实施路径。