省市市场总览

接口信息

项目	内容
请求方式	`GET`
接口路径	`/api/bs_v5/province_city_analysis/overview`
数据范围	省份、城市
数据时效	最新月份或指定历史月份
主要来源	`ads_area_market_overview`、`ads_area_price_distribution`、`ads_area_top_brand_category_summary`、品牌 ADS、`dim_country`

功能说明

返回指定省份或城市的地区画像、全国画像、市场指标、上月门店经营情况及数据质量信息。
page_meta 聚合当前区域页面实际读取数据的最新入库时间，供首页卡片和详情页顶部展示“更新时间”。

请求参数

参数	类型	必填	默认值	示例	说明
`area_level`	string	是	-	`city`	仅支持 `province`、`city`
`area_id`	integer	是	-	`1`	省份ID或城市ID
`year_month`	string	否	最新月份	`2026-06`	支持 `YYYYMM`、`YYYY-MM`

请求示例

成功响应字段

字段路径	类型	必返	可空	说明
`code`	integer	是	否	业务状态码
`message`	string	是	否	响应信息
`data.area.area_level`	string	是	否	地区层级
`data.area.area_id`	integer	是	否	地区ID
`data.area.area_name`	string	是	否	地区名称
`data.area.country_id`	integer	是	否	国家ID
`data.area.country_name`	string	是	是	国家名称
`data.area.province_id`	integer	是	否	省份ID
`data.area.province_name`	string	是	是	省份名称
`data.area.city_id`	integer	是	是	城市ID，省份层级为 `null`
`data.area.city_name`	string	是	是	城市名称，省份层级为 `null`
`data.area.city_level_id`	integer	是	是	城市等级ID
`data.area.city_level_name`	string	是	是	城市等级名称
`data.area.area_intro`	string	是	是	地区介绍；城市来自 `dim_city.city_intro`，省份来自 `dim_province.province_intro`，经清洗写入 ADS
`data.period.stat_month`	string	是	否	统计月份，格式 `YYYYMM`
`data.page_meta.updated_at`	string	是	是	页面数据最新入库时间，格式 `YYYY-MM-DD HH:mm:ss`
`data.page_meta.updated_date`	string	是	是	`updated_at` 的日期部分，格式 `YYYY-MM-DD`
`data.profile.resident_population`	integer	是	是	地区常住人口
`data.profile.land_area_km2`	number	是	是	土地面积，平方公里
`data.profile.per_capita_income`	integer	是	是	地区人均可支配收入，元/人，四舍五入保留整数
`data.profile.per_capita_spending`	integer	是	是	地区人均消费支出，元/人，四舍五入保留整数
`data.country_profile.country_id`	integer	是	否	国家ID
`data.country_profile.country_name`	string	是	是	国家名称
`data.country_profile.per_capita_income`	integer	是	是	全国人均可支配收入，元/人，四舍五入保留整数
`data.country_profile.per_capita_spending`	integer	是	是	全国人均消费支出，元/人，四舍五入保留整数
`data.market.active_store_count`	integer	是	是	营业门店数
`data.market.active_store_yoy_pct`	string	是	是	营业门店数同比
`data.market.active_store_mom_pct`	string	是	是	营业门店数环比
`data.market.brand_count`	integer	是	是	品牌数
`data.market.brand_yoy_pct`	string	是	是	品牌数同比
`data.market.weighted_avg_price`	number	是	是	门店数加权人均消费
`data.market.weighted_avg_price_yoy_pct`	string	是	是	加权人均消费同比
`data.market.brand_chain_rate_pct`	string	是	是	品牌连锁化率
`data.market.stores_per_10000_people`	integer	是	是	每万人门店数，四舍五入保留整数
`data.last_month_operation.period`	string	是	否	上一个自然月
`data.last_month_operation.new_store_count`	integer	是	是	上月新开门店数
`data.last_month_operation.close_store_count`	integer	是	是	上月闭店数
`data.last_month_operation.close_store_rate_pct`	string	是	是	上月倒闭率
`data.quality.calculation_version`	string	是	否	指标计算版本

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "area": {
      "area_level": "city",
      "area_id": 1,
      "area_name": "北京市",
      "country_id": 1,
      "country_name": "中华人民共和国",
      "province_id": 1,
      "province_name": "北京市",
      "city_id": 1,
      "city_name": "北京市",
      "city_level_id": 1,
      "city_level_name": "一线",
      "area_intro": "中华人民共和国首都、直辖市。"
    },
    "period": {"stat_month": "202606"},
    "page_meta": {
      "updated_at": "2026-08-06 09:30:15",
      "updated_date": "2026-08-06"
    },
    "profile": {
      "resident_population": 13920000,
      "land_area_km2": 16418.0,
      "per_capita_income": 85415,
      "per_capita_spending": 50897
    },
    "country_profile": {
      "country_id": 1,
      "country_name": "中华人民共和国",
      "per_capita_income": 41314,
      "per_capita_spending": 28227
    },
    "market": {
      "active_store_count": 6796,
      "active_store_yoy_pct": "5.26%",
      "active_store_mom_pct": "1.32%",
      "brand_count": 1514,
      "brand_yoy_pct": "4.18%",
      "weighted_avg_price": 84.33,
      "weighted_avg_price_yoy_pct": "2.15%",
      "brand_chain_rate_pct": "38.62%",
      "stores_per_10000_people": 5
    },
    "last_month_operation": {
      "period": "202605",
      "new_store_count": 310,
      "close_store_count": 152,
      "close_store_rate_pct": "2.11%"
    },
    "quality": {
      "calculation_version": "v1.0.0"
    }
  }
}

业务规则

year_month 不传时返回该地区最新月份。

page_meta.updated_at 取当前区域页面已展示数据来源记录的最大 updated_at；不使用统计月份、抓取批次或 Top100 的品牌快照时间替代。

百分比统一四舍五入保留两位并带 %。

country_profile 来自 dim_country 当前启用记录，不具备历史月份语义。

异常码

code	说明
`400`	参数错误
`404`	未找到对应省市指标数据
`500`	服务端内部错误

返回响应

🟢200成功示例

application/json

Bodyapplication/json

示例

{
    "code": 200,
    "message": "success",
    "data": {
        "area": {
            "area_level": "city", 
            "area_id": 100,
            "area_name": "蚌埠市",
            "country_id": 1,
            "country_name": "中华人民共和国",
            "province_id": 12,
            "province_name": "安徽省",
            "city_id": 100,
            "city_name": "蚌埠市",
            "city_level_id": 4,
            "city_level_name": "三线",
            "city_intro": null
        },
        "period": {
            "stat_month": "202607"
        },
        "profile": {
            "resident_population": 3262000,
            "land_area_km2": 5959.0,
            "per_capita_income": null,
            "per_capita_spending": null
        },
        "country_profile": {
            "country_id": 1,
            "country_name": "中华人民共和国",
            "per_capita_income": null,
            "per_capita_spending": null
        },
        "market": {
            "active_store_count": 767,
            "active_store_yoy_pct": null,
            "active_store_mom_pct": "5.07%",
            "brand_count": 241,
            "brand_yoy_pct": null,
            "weighted_avg_price": 49.96,
            "weighted_avg_price_yoy_pct": null,
            "brand_chain_rate_pct": null,
            "stores_per_10000_people": 2.35
        },
        "last_month_operation": {
            "period": "202606",
            "new_store_count": 18,
            "close_store_count": 28,
            "close_store_rate_pct": "3.84%"
        },
        "quality": {
            "category_mapping_rate_pct": "23.08%",
            "calculation_version": "v1.0.0"
        }
    }
}

省市市场总览

省市市场总览#

接口信息#

功能说明#

请求参数#

请求示例#

成功响应字段#

成功响应示例#

业务规则#

异常码#

请求参数

请求示例代码

返回响应

省市市场总览

接口信息

功能说明

请求参数

请求示例

成功响应字段

成功响应示例

业务规则

异常码