udata-gi

name	udata-gi
description	Use when downloading game data (revenue, DAU, downloads, MAU) from Udata 有数 全球洞察 (gdas.gux.netease.com). Supports batch download for multiple games with country breakdown and time trend data.

Udata 全球洞察数据下载工具

概述

通过 CDP（Chrome 调试协议）复用浏览器登录态，调用 udata-gi.nie.netease.com 的 API 批量下载游戏的收入、下载量、DAU、MAU 等数据，输出为 Excel（含国家分布 + 时间趋势）。

前提条件

• Chrome 已开启 --remote-debugging-port=14661
• CDP Proxy 已运行（web-access skill 管理）
• Chrome 已登录 gdas.gux.netease.com（Udata 有数）

脚本结构

scripts/
  session.py   CDP Session 管理（获取 token，执行 API fetch）
  api.py       Udata GI API 封装（getSum / getTrend / lookupGameId）
  export.py    Excel / JSON 保存
  batch.py     批量下载入口（CLI + Python 调用）
config/
  data-types.json  数据类型枚举（单位、标签）
  countries.json   国家代码→中文名映射

快速使用

单游戏（交互式）

import sys
from pathlib import Path

SKILL_DIR = Path.home() / ".agents" / "skills" / "udata-gi" / "scripts"
sys.path.insert(0, str(SKILL_DIR))

from session import UdataSession
from api     import get_sum, get_trend, parse_sum, parse_trend
from export  import save

session = UdataSession()
game_id, game_name = "1637040599", "Frozen City"
from_date, to_date = "20250101", "20251231"
data_type = "dau"   # revenue / download / dau / mau

sum_raw  = get_sum(session,  game_id, from_date, to_date, "month", "all", data_type)
trd_raw  = get_trend(session, game_id, from_date, to_date, "month", "all", data_type)
sum_rows = parse_sum(sum_raw, data_type)
g_rows, c_rows = parse_trend(trd_raw, data_type)

out = Path.home() / "Desktop" / "udata_downloads"
fpath = save(game_name, sum_rows, g_rows, c_rows,
             {"game": game_name, "gameId": game_id,
              "from": from_date, "to": to_date,
              "dateType": "month", "platform": "all", "data_type": data_type},
             {"sum": sum_raw, "trend": trd_raw}, out)
print("已保存:", fpath)
session.close()

批量（Python 调用）

import sys
from pathlib import Path

SKILL_DIR = Path.home() / ".agents" / "skills" / "udata-gi" / "scripts"
sys.path.insert(0, str(SKILL_DIR))
from batch import batch_download

games = [
    {"name": "Frozen City",       "id": "1637040599"},
    {"name": "Whiteout Survival", "id": "6443575749"},
    {"name": "Kingshot",          "id": ""},   # id 留空 → 自动查询
]

results = batch_download(
    games,
    from_date  = "20250101",
    to_date    = "20251231",
    date_type  = "month",
    platform   = "all",
    data_type  = "dau",
    output_dir = Path.home() / "Desktop" / "udata_downloads",
)

批量（命令行）

# 按游戏名称（自动查 App Store ID）
python batch.py \
  --games "Frozen City" "Whiteout Survival" "Kingshot" \
  --data-type dau \
  --date-type month \
  --from 20250101 --to 20251231 \
  --platform all

# 按 JSON 文件
python batch.py --games-file games.json --data-type revenue --from 20250101 --to 20251231

games.json 格式：

[
  {"name": "Frozen City",       "id": "1637040599"},
  {"name": "Whiteout Survival", "id": "6443575749"},
  {"name": "Kingshot",          "id": ""}
]

数据类型参数

data_type	含义	单位
revenue	收入	万元
download	下载量	万次
dau	平均 DAU	人
mau	月活 MAU	人

时间粒度

date_type	说明
day	日度
week	周度
month	月度

常见日期快捷

需求	from	to
去年（2025）	20250101	20251231
今年（2026）	20260101	20261231
近3个月	20260301	20260601
近1年	20250601	20260601

输出 Excel 结构

每个游戏生成一个 .xlsx，包含：

Sheet	内容
国家分布	各国汇总值，按降序排列
全球趋势	各时间点全球总值
国家明细	各国 × 各时间点明细（可能数百行）
查询参数	本次查询参数记录

常见问题

问题	原因	解决
401 / Token 失效	Chrome 登录过期	在 Chrome 重新登录 Udata，重跑
num 为 null	该 dataType 不支持该游戏	换其他 data_type 测试
游戏 ID 找不到	名称不精确	直接传 App Store 数字 ID
超时	网络问题	重试或增大 session.py 的超时时间