Appearance
本地生活 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 说明。