REST APIJSON

Google Play App API

按包名查询 Google Play 应用详情，支持国家和语言切换、名称搜索与批量查询。所有请求和响应均使用 UTF-8 JSON。

Base URLhttps://api.flexcala.app

AuthenticationBearer Token

Client timeout建议 30 秒

身份验证

除健康检查外，请求必须携带 API Token。请只在服务端代码中保存 Token，不要提交到 Git 或公开在浏览器脚本中。

HTTP Header

Authorization: Bearer YOUR_API_TOKEN

快速请求

下面使用 Instagram 包名查询美国英语商店数据。

cURL

curl -X POST 'https://api.flexcala.app/v1/google-play/app' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "com.instagram.android",
    "country": "us",
    "lang": "en"
  }'

JavaScript

const response = await fetch(
  'https://api.flexcala.app/v1/google-play/app',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      appId: 'com.instagram.android',
      country: 'us',
      lang: 'en'
    })
  }
);

const result = await response.json();

POST/v1/google-play/app

查询应用详情

使用 Google Play 包名获取标题、开发者、简介、评分、安装量、图标、截图和商店地址等完整信息。

请求参数

参数	类型	必填	说明
`appId`	string	是	Google Play 包名。
`country`	string	否	两位国家代码，默认 us。
`lang`	string	否	语言代码，默认 en；中文可使用 zh-cn、zh-tw 或 zh-hk。
`forceRefresh`	boolean	否	设为 true 时跳过缓存，默认 false。

成功响应

JSON

{
  "success": true,
  "fromCache": false,
  "data": {
    "appId": "com.instagram.android",
    "title": "Instagram",
    "developer": "Instagram",
    "score": 4.3,
    "installs": "5,000,000,000+",
    "url": "https://play.google.com/store/apps/details?id=com.instagram.android"
  }
}

POST/v1/google-play/search

按名称搜索

不知道包名时，先按应用名称搜索候选结果，再使用详情接口查询完整数据。

参数	类型	必填	说明
`term`	string	是	应用名称或关键词。
`country`	string	否	搜索目标国家，默认 us。
`lang`	string	否	结果语言，默认 en。
`limit`	number	否	返回数量，默认 6。

请求体

JSON

{ "term": "Instagram", "country": "jp", "lang": "ja", "limit": 6 }

POST/v1/google-play/batch

批量查询

一次提交多个包名。单个应用失败不会中断整个任务，失败信息会单独写入 errors。

参数	类型	必填	说明
`packageNames`	string[]	是	Google Play 包名数组。
`country`	string	否	所有应用使用的目标国家。
`lang`	string	否	所有应用使用的目标语言。
`forceRefresh`	boolean	否	是否强制刷新所有应用。

请求体

JSON

{
  "packageNames": [
    "com.instagram.android",
    "com.zhiliaoapp.musically"
  ],
  "country": "us",
  "lang": "en"
}

错误代码

状态码	含义	处理方式
`400`	请求参数错误	检查包名和 JSON 格式。
`401`	Token 无效	检查 Authorization 请求头。
`404`	应用不存在或地区不可用	确认包名或更换国家。
`502`	Google Play 上游异常	稍后重试。
`504`	Google Play 请求超时	稍后重试，客户端超时至少设为 30 秒。

国家与语言

country 使用 ISO 3166-1 两位国家代码；lang 通常使用两位语言代码，中文可带区域标签区分简体和繁体。英国必须写 gb，不能写 uk。

语言	lang	常用 country	推荐组合
英语	`en`	us, gb, au, ca, nz	country=us, lang=en
日语	`ja`	jp	country=jp, lang=ja
简体中文	`zh-cn`	sg, us	country=sg, lang=zh-cn
繁体中文（台湾）	`zh-tw`	tw	country=tw, lang=zh-tw
繁体中文（香港）	`zh-hk`	hk	country=hk, lang=zh-hk
葡萄牙语	`pt`	br, pt	country=br, lang=pt
西班牙语	`es`	es, mx, ar, co	country=es, lang=es
德语	`de`	de, at, ch	country=de, lang=de
法语	`fr`	fr, ca, be, ch	country=fr, lang=fr

Google Play 不是中国大陆的常规应用市场，因此简体中文建议搭配 sg 或其他实际投放国家，不建议把 cn 作为默认 country。