Skip to content

本地生活 App 优惠券总推错城市?用 IP 归属地做城市级券池推送(PHP 实现) ​

运营同学在群里甩了一张图:一张「满 50 减 15」的火锅券,投放城市选了成都,结果三天核销率 2.7%。查数据发现,领券的人里有一大批是出差路过、或者只是开着定位授权但人在外地的用户,点开券详情第一句话就是「最近门店 1200 公里」。

本地生活的券有个硬约束:券绑门店,门店绑城市。券推错了城市,不光是浪费预算,还拉了一堆无效点击,把"附近好店"这个标签做花了。这篇文章讲怎么用 IP 归属地给这件事兜底,代码用 PHP 写,一段能直接跑。

一、为什么"定位 + 用户填的城市"都不够用 ​

先说常见的三种地域信号,各自的坑:

  • GPS 定位:最准,但拿不到。小程序要用户点授权,App 里首次弹窗的拒绝率一直不低,还有一批用户干脆常年关着系统定位。
  • 用户自己填的城市:首页城市选择器留下来的值,经常是"我刚旅游看过广州的店"的残留,一放两三个月没人改。
  • 注册地 / 收货地址:对老用户有点用,对新用户完全空白。

IP 归属地是这三个之外最便宜的一层:用户什么都不用点,服务端就能拿到一个城市级的判断。它的精度是城市(免费版),不是街道,也不是精确位置,所以定位它的用途要摆正——它不是用来做身份认定的,而是用来决定"给哪座城市的券池"。这个精度对券池匹配刚好够用。

顺便把边界说清楚:如果一个用户在成都用家里的宽带,IP 归属地基本就是成都;如果他开了代理、或者在高铁上用移动流量漫游,归属地可能落到别的省。所以最终策略不是"IP 说什么就是什么",而是"IP 说哪里、就优先给哪里的券,拿不准就退到全国通用池"。

二、方案:一次请求里做三层判断 ​

整体流程很短,难点全在细节:

请求进到 PHP
  ├─ 第 1 层:拿到可信的客户端 IP(反代/CDN 场景下这步最容易出错)
  ├─ 第 2 层:查归属地 → city_code(免费版就够;连锁多门店到区县级再上 VIP 的 area)
  └─ 第 3 层:city_code → 城市券池 → 命中就给本地券,没命中给通用券

三层里有两个工程点值得提前定好:

缓存必须做。 归属地是"日级"变化的数据,同一个 IP 一天查一次完全够。开一个本地缓存目录,TTL 设 24 小时,免费版 60 次/分钟的限制在正常流量下根本碰不到;万一碰上了,就靠退避重试加缓存兜住。

匹配用 city_code,别用城市中文名。 IP9 返回里同时有 city("成都")和 city_code(chengdu),后者是拼音、没有歧义,拿它做数据库主键去对齐门店表最稳,也不会因为"成都市/成都"这种写法差异匹配失败。

三、PHP 实现:一张券的归属地决策 ​

下面是一份完整脚本,既能当 Web 接口调用,也能在命令行里拿 IP 自测。依赖只有 curl 扩展。

php
<?php
// local_coupon.php —— 按 IP 归属地给本地生活券池做城市匹配
// 运行: php local_coupon.php 116.21.44.33     (命令行自测)
// 依赖: PHP 7.4+,curl 扩展

declare(strict_types=1);

const IP9_ENDPOINT = 'https://ip9.com.cn/get';
const CACHE_DIR    = __DIR__ . '/ip_geo_cache';
const CACHE_TTL    = 86400;   // 归属地按天变,缓存 24 小时

// 门店与券池表。生产上放数据库或配置中心,这里用数组演示结构,key 是 IP9 的 city_code
const CITY_POOL = [
    'chengdu'   => ['stores' => [101, 102, 103], 'coupons' => ['hotpot_50_15', 'tea_20_8']],
    'chongqing' => ['stores' => [201, 202],      'coupons' => ['hotpot_60_20']],
    'guangzhou' => ['stores' => [301],           'coupons' => ['tea_15_5', 'brunch_30_10']],
    'beijing'   => ['stores' => [401, 402],      'coupons' => ['coffee_25_10']],
];

/** 取客户端真实 IP。自有反代/CDN 透传的头排在前面,XFF 取最左的非私网地址 */
function client_ip(): string
{
    // 只信任自己链路里的头:CF 托管的站用 CF-Connecting-IP,Nginx 反代用 X-Real-IP
    $trusted = ['HTTP_CF_CONNECTING_IP', 'HTTP_X_REAL_IP'];
    foreach ($trusted as $k) {
        if (!empty($_SERVER[$k])) {
            $ip = trim((string)$_SERVER[$k]);
            if (filter_var($ip, FILTER_VALIDATE_IP)) {
                return $ip;
            }
        }
    }

    // XFF 客户端可以自己伪造,只取第一个公网地址,且必须过得了校验
    if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        foreach (explode(',', (string)$_SERVER['HTTP_X_FORWARDED_FOR']) as $part) {
            $ip = trim($part);
            if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE)) {
                return $ip;
            }
        }
    }

    return (string)($_SERVER['REMOTE_ADDR'] ?? '');   // CLI 场景为空
}

/** 查归属地:先读缓存,再打接口,返回 ['city_code'=>..,'city'=>..] 或 null */
function geo_lookup(string $ip, int $retry = 2): ?array
{
    if (!filter_var($ip, FILTER_VALIDATE_IP)) {
        return null;                        // 非法 IP 本地就拦掉,别浪费一次请求
    }

    $file = CACHE_DIR . '/' . md5($ip) . '.json';
    if (is_file($file) && (time() - filemtime($file)) < CACHE_TTL) {
        $hit = json_decode((string)file_get_contents($file), true);
        if (is_array($hit)) {
            return $hit;
        }
    }

    $ch = curl_init(IP9_ENDPOINT . '?ip=' . urlencode($ip));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 2,
        CURLOPT_TIMEOUT        => 3,
        CURLOPT_HTTPHEADER     => ['Accept: application/json'],
    ]);
    $body = curl_exec($ch);
    $err  = curl_errno($ch);
    curl_close($ch);

    if ($body === false || $err !== 0) {
        if ($retry > 0) {                   // 网络抖动退避重试一次
            usleep(200000);
            return geo_lookup($ip, $retry - 1);
        }
        return null;
    }

    $payload = json_decode((string)$body, true);
    $ret     = $payload['ret'] ?? null;

    if ($ret === 429) {                     // 触发限速:等一秒再来,仍失败就交给上层兜底
        if ($retry > 0) { sleep(1); return geo_lookup($ip, $retry - 1); }
        return null;
    }
    if ($ret !== 200 || empty($payload['data']['ip'])) {
        return null;                        // 非法 IP 接口返回 ret=400, data 为空数组
    }

    $d   = $payload['data'];
    $row = [
        'city_code'       => (string)($d['city_code'] ?? ''),        // 拼音,做匹配键
        'city'            => (string)($d['city'] ?? ''),
        'prov'            => (string)($d['prov'] ?? ''),
        'city_short_code' => (string)($d['city_short_code'] ?? ''),
        'isp'             => (string)($d['isp'] ?? ''),
        'area'            => (string)($d['area'] ?? ''),             // 区县:免费版为空,VIP 版才有
    ];

    if (!is_dir(CACHE_DIR)) { @mkdir(CACHE_DIR, 0775, true); }
    file_put_contents($file, json_encode($row, JSON_UNESCAPED_UNICODE));
    return $row;
}

/** 券池决策:命中本地城市给本地券,拿不准给通用券 */
function pick_coupon(?array $geo): array
{
    if ($geo === null || $geo['city_code'] === '') {
        return ['scope' => 'fallback', 'reason' => '归属地未知', 'stores' => [], 'coupons' => ['common_30_5']];
    }
    $code = $geo['city_code'];
    if (isset(CITY_POOL[$code])) {
        $pool = CITY_POOL[$code];
        return [
            'scope'   => 'local',
            'reason'  => "命中 {$geo['city']}",
            'stores'  => $pool['stores'],
            'coupons' => $pool['coupons'],
        ];
    }
    return [                                // 目的地城市没开门店,别硬推本地券
        'scope'   => 'fallback',
        'reason'  => "{$geo['city']} 暂无门店",
        'stores'  => [],
        'coupons' => ['common_30_5'],
    ];
}

// —— 命令行自测 ——
if (PHP_SAPI === 'cli') {
    $ips = array_slice($argv, 1) ?: [client_ip()];
    foreach ($ips as $ip) {
        $geo    = geo_lookup($ip);
        $result = pick_coupon($geo);
        printf(
            "%-16s -> %-4s %-6s %-16s %s\n",
            $ip,
            $geo['prov'] ?? '-',
            $geo['city'] ?? '-',
            $geo['isp'] ?? '-',
            $result['scope'] . ' / ' . $result['reason'] . ' / ' . implode(',', $result['coupons'])
        );
    }
}

跑起来是这样(后两条是典型边界):

text
$ php local_coupon.php 116.21.44.33 58.30.0.0 8.8.8.8
116.21.44.33     -> 广东 广州 中国电信     local / 命中 广州 / tea_15_5,brunch_30_10
58.30.0.0        -> 北京 北京 国研科技/歌华有线 local / 命中 北京 / coffee_25_10
8.8.8.8          ->             Google Cloud     fallback / 归属地未知 / common_30_5

接入到现有业务里,就是把这几个函数塞进券列表接口:

php
$geo    = geo_lookup(client_ip());
$coupon = pick_coupon($geo);

// 券详情接口返回时带上城市上下文,前端好显示"成都 · 3 家门店可用"
$response = [
    'city_code' => $geo['city_code'] ?? '',
    'city'      => $geo['city'] ?? '全国',
    'scope'     => $coupon['scope'],
    'coupons'   => $coupon['coupons'],
    'stores'    => $coupon['stores'],
];

四、上线前要盯的几件事 ​

反代透传头要只信自己那一段。 X-Forwarded-For 是客户端可以自己拼的,如果有人手动发 X-Forwarded-For: 1.2.3.4,而你又直接取最左边的值,那这套券池逻辑就被一行请求头绕过了。稳妥做法是:让 Nginx 只把自己的 $remote_addr 追加到 XFF,PHP 侧只读这一段(或者干脆用 X-Real-IP、CF-Connecting-IP 这类只能由边缘节点写入的头)。同一台机器上跑测试时,127.0.0.1 是私网地址,FILTER_FLAG_NO_PRIV_RANGE 会把它过滤掉,代码会自动走 fallback,这是预期行为。

缓存目录要能扛住热点。 单机文件缓存适合中小体量;如果券接口 QPS 上了几百,换成 Redis,key 用 IP 的哈希、TTL 设 24 小时,顺手把「城市 → 券池」也缓存起来。另外别忘了缓存穿透:一批不存在的 IP 反复打接口,会一直不写缓存,给接口加个 geo_lookup 返回 null 时的空值短缓存(60 秒)就够了。

免费版的 60 次/分钟要用在刀刃上。 券接口是高频入口,靠 IP 查询的绝对次数很容易顶到限额——所以缓存是必须项,不是优化项。如果业务量已经大到"每个新 IP 都要现查",那说明该评估 VIP 版了:18 万次/分钟的配额,还能拿到 area 区县字段,连锁品牌在一个城市有多家门店、需要按区县推门店的时候,区县这个字段很关键。计费口径以官网为准。

归属地只能当"推券依据",不能当"发券资格"。 有些运营会顺手把它当风控用(比如"IP 在 A 城就不给 B 城的券"),这类规则误伤极大:跨城通勤、出差、代理办公的人全中招。合理的做法是把 IP 城市当排序和优先级,用户在 App 里主动切换的城市永远优先于 IP 判断。

留存与合规。 券池决策日志里只需要留 city_code 和决策结果,不需要长期保存原始 IP;如果确实要留 IP 做排查,按脱敏方式处理(比如只留前三段),并在隐私政策里写明用途。

总结 ​

本地生活的券推错城市,大多不是算法问题,是"拿不到用户在哪"这个前置问题没解决。定位能拿就拿,拿不到的时候用 IP 归属地补一个城市级的判断,成本几乎为零:一次 HTTP 请求、一个 24 小时的本地缓存、一张 city_code 对齐的门店表,就能把"最近门店 1200 公里"这种事故挡掉大半。

接口用法很朴素:GET https://ip9.com.cn/get?ip=<IP>,不传参就是查当前请求方 IP,免费版无需注册、60 次/分钟/IP、IPv4 与 IPv6 都支持,返回国家、省市、邮编、区号、运营商、经纬度(城市中心)等字段;需要区县级精度和 ip_type(ISP 家庭 / BUS 企业 / IDC 机房)、ip_asn 这类维度时,看 https://www.ip9.com.cn 上的 VIP 说明。