> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Baidu Analytics data source in Adriel.

## Introduction

Baidu Analytics (百度统计, Baidu Tongji) is Baidu's web analytics platform for measuring site traffic, visitor behavior, and promotion performance in the Chinese market. It reports on page views, visits, visitors, engagement, and conversions for a registered site, and — for sites running Baidu promotion — on impressions, clicks, cost, and return.

The connector reads from the Baidu Tongji REST API (v1). It authenticates with a username and access token rather than OAuth. Each data source is scoped to a single site and a single **report type** chosen at creation. The report type maps to a specific Baidu report (for example, Search Term, Visited Pages, or Website Overview) and determines both the metrics returned and the primary breakdown each row represents. When several sites are selected during setup, Adriel creates one data source per site.

As an analytics connector, visit, visitor, engagement, and conversion data are standardized so widgets can aggregate this source alongside other connectors. To connect this data source, see [How to connect Baidu Analytics to Adriel](/data-sources/a-f/baidu-analytics/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the account's registered sites. The site list is read live from the Baidu Tongji API at connection and data source creation time (it is not separately cached), and each site's identifier scopes every subsequent data query. The report type is fixed per data source and cannot be changed without recreating the data source.

### Reports data

Reports data uses a daily-cache model. On first connection, historical daily data for the last **180 days** is backfilled. After that, a scheduled refresh re-fetches the most recent **30 days** on each run, twice per day at **02:00 and 14:00 UTC**. Baidu Tongji itself processes data with a short delay (typically a few hours), so very recent rows can still shift between refreshes. Older data outside the 30-day window is not re-fetched, because it rarely changes.

## Architecture levels

Account → Site

The account is the set of credentials (username and access token). A site is a single registered property, identified by its domain and site ID, and is the reporting boundary for every query. Baidu Analytics has no ad-hierarchy analog; the report type selected at creation, not a drill-down level, determines what each row represents.

## Date range limits

| Limit                               | Value    |
| ----------------------------------- | -------- |
| Initial history on first connection | 180 days |
| Rolling refresh window              | 30 days  |

Data earlier than 180 days before the first connection is not backfilled and is unavailable. There is no documented per-query maximum range beyond the history available in the cache.

## Metrics

<Note>
  **How to read the columns**

  Code style like `pv_count` is the literal Baidu Tongji API field name returned for the report. *Italic text* describes a value that Adriel derives rather than reads directly from a single API field.

  **Data type vocabulary**: Number, Currency, Percentage, Ratio, Duration, Date, Text.
</Note>

<Note>
  **Availability depends on the report type**

  Baidu Analytics is report-type based. The report type is chosen when the data source is created and cannot be changed afterward. Each report type returns only its own metric set, so a metric listed below is available only in the report types that expose it. See [Metric availability by report type](#metric-availability-by-report-type) for the exact mapping.
</Note>

### Users & sessions

| Metric           | Description                              | Data type  | API Key             |
| ---------------- | ---------------------------------------- | ---------- | ------------------- |
| Visits           | Number of visits (sessions) to the site. | Number     | `visit_count`       |
| Visitors         | Distinct visitors (unique users).        | Number     | `visitor_count`     |
| New visitors     | Visitors recorded as first-time.         | Number     | `new_visitor_count` |
| New visitor rate | Share of visitors that were new.         | Percentage | `new_visitor_ratio` |
| Unique IPs       | Distinct IP addresses observed.          | Number     | `ip_count`          |

### Traffic sources (Baidu promotion)

| Metric             | Description                                           | Data type  | API Key          |
| ------------------ | ----------------------------------------------------- | ---------- | ---------------- |
| Impressions        | Times a promotion was shown.                          | Number     | `show_count`     |
| Clicks             | Clicks on a promotion.                                | Number     | `clk_count`      |
| Cost               | Promotion spend.                                      | Currency   | `cost_count`     |
| Click-through rate | Clicks divided by impressions.                        | Percentage | `ctr`            |
| CPM                | Cost per thousand impressions.                        | Currency   | `cpm`            |
| Arrival visits     | Visits that reached the site after a promotion click. | Number     | `in_visit_count` |
| Arrival rate       | Share of clicks that resulted in a site arrival.      | Percentage | `arrival_ratio`  |

### Engagement & behavior

| Metric                  | Description                                                  | Data type  | API Key             |
| ----------------------- | ------------------------------------------------------------ | ---------- | ------------------- |
| Page views              | Total page views (PV).                                       | Number     | `pv_count`          |
| Page view share         | Share of page views attributed to the row.                   | Percentage | `pv_ratio`          |
| Average pages per visit | Page views divided by visits.                                | Ratio      | `avg_visit_pages`   |
| Average visit duration  | Mean length of a visit.                                      | Duration   | `avg_visit_time`    |
| Average time on page    | Mean time spent on the page.                                 | Duration   | `average_stay_time` |
| Bounce rate             | Share of single-interaction visits.                          | Percentage | `bounce_ratio`      |
| Entrances               | Visits that started on this page (landing count).            | Number     | `visit1_count`      |
| Outbound clicks         | Clicks leading away from the page.                           | Number     | `outward_count`     |
| Exits                   | Visits that ended on this page.                              | Number     | `exit_count`        |
| Exit rate               | Share of views on this page that were the last in the visit. | Percentage | `exit_ratio`        |

### Conversions

| Metric                  | Description                              | Data type  | API Key          |
| ----------------------- | ---------------------------------------- | ---------- | ---------------- |
| Conversions             | Recorded conversion (transaction) count. | Number     | `trans_count`    |
| Conversion rate         | Conversions divided by visits.           | Percentage | `trans_ratio`    |
| Average conversion cost | Promotion cost divided by conversions.   | Currency   | `avg_trans_cost` |
| Revenue                 | Revenue attributed to the report.        | Currency   | `income`         |
| Profit                  | Profit attributed to the report.         | Currency   | `profit`         |
| Return on investment    | Return relative to promotion cost.       | Ratio      | `roi`            |

### Metric availability by report type

The report type selected at creation determines which of the metrics above are returned. The `eventAnalysis` report type has no fixed metric set — its metrics are defined per request.

| Report type                          | UI label                                                           | Available metrics                                                                                                                                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `websiteOverviewTrendData`           | Website Overview (Trend Data)                                      | `pv_count`, `visitor_count`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `trans_count`                                                                                                                                                     |
| `searchTerm`                         | Search Term                                                        | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `trans_count`, `trans_ratio`                                              |
| `visitedPages`                       | Visited Pages                                                      | `pv_count`, `visitor_count`, `ip_count`, `visit1_count`, `outward_count`, `exit_count`, `average_stay_time`, `exit_ratio`                                                                                                                    |
| `visitedDomainName`                  | Visited Domain Name                                                | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `average_stay_time`, `avg_visit_pages`                                                                         |
| `searchEngines`                      | Search Engines                                                     | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `trans_count`, `trans_ratio`                                              |
| `geographicalDistributionByCountry`  | Geographical Distribution (by country)                             | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `trans_count`, `trans_ratio`                                              |
| `geographicalDistributionByProvince` | Geographical Distribution (by province)                            | Same as Geographical Distribution (by country)                                                                                                                                                                                               |
| `websiteOverviewCommon`              | Website Overview (Source, Search Terms, Entry Page, Visited Pages) | `pv_count`, `visit_count`, `visitor_count`, `new_visitor_count`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`                                                                                                             |
| `trendAnalysis`                      | Trend Analysis                                                     | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `trans_count`, `trans_ratio`, `avg_trans_cost`, `income`                  |
| `promotionMethod`                    | Promotion Method                                                   | `show_count`, `clk_count`, `cost_count`, `ctr`, `cpm`, `pv_count`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `in_visit_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `arrival_ratio`          |
| `baiduPromotionTrends`               | Baidu Promotion Trends                                             | `pv_count`, `pv_ratio`, `visit_count`, `visitor_count`, `new_visitor_count`, `new_visitor_ratio`, `ip_count`, `bounce_ratio`, `avg_visit_time`, `avg_visit_pages`, `trans_count`, `trans_ratio`, `avg_trans_cost`, `income`, `profit`, `roi` |
| `eventAnalysis`                      | Event Analysis (事件分析)                                              | Dynamic — defined per request; no fixed metric set                                                                                                                                                                                           |

## Breakdowns

<Note>
  **How to read the columns**

  Code style like `_date` is the literal field name Adriel stores for the breakdown. *Italic text* describes a value that Adriel derives rather than reading it directly from a single API field.
</Note>

<Note>
  **The primary row breakdown is set by the report type**

  Beyond the date breakdown, each report type produces rows grouped by its own entity (for example, one row per search term, per visited page, or per province). Because the report type is fixed at creation, that primary breakdown is fixed for the data source and cannot be swapped for another entity without recreating it.
</Note>

### Date

| Breakdown | Description                                        | API Key |
| --------- | -------------------------------------------------- | ------- |
| Date      | Daily date of the row, normalized to `YYYY-MM-DD`. | `_date` |

### Report entity

The row entity is determined by the report type selected at creation. The table keys each breakdown by its report type; the underlying entity-column name varies per report type.

| Breakdown                 | Description                                                                                  | API Key                              |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| Search term               | One row per search keyword that led to the site.                                             | `searchTerm`                         |
| Visited page              | One row per page on the site.                                                                | `visitedPages`                       |
| Visited domain            | One row per referring or visited domain.                                                     | `visitedDomainName`                  |
| Search engine             | One row per search engine source.                                                            | `searchEngines`                      |
| Country                   | One row per country of the visitor.                                                          | `geographicalDistributionByCountry`  |
| Province                  | One row per province of the visitor.                                                         | `geographicalDistributionByProvince` |
| Promotion method          | One row per Baidu promotion method.                                                          | `promotionMethod`                    |
| Website overview (trend)  | Rows summarize the site over time (no entity split).                                         | `websiteOverviewTrendData`           |
| Trend analysis            | Rows summarize the site over time (no entity split).                                         | `trendAnalysis`                      |
| Website overview (common) | Rows depend on the selected collection (source, search terms, entry page, or visited pages). | `websiteOverviewCommon`              |
| Event                     | Rows depend on the event breakdowns defined for the report.                                  | `eventAnalysis`                      |

### Time & date grouping

<Note>
  Adriel groups Baidu Analytics' daily results into these standard views for reporting alongside other connectors.
</Note>

| Breakdown                  | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown        | Automatically picks the best granularity for the date range. |
| Daily                      | Split reports by day.                                        |
| Weekly (Start: Mon)        | Split reports by week, starting Monday.                      |
| Weekly (Start: Sun)        | Split reports by week, starting Sunday.                      |
| Week Date Breakdown        | Split by the start date of each week.                        |
| Week Number Breakdown (W#) | Split by week number in the year.                            |
| Monthly                    | Split reports by calendar month.                             |
| Quarterly                  | Split reports by calendar quarter.                           |
| Yearly                     | Split reports by calendar year.                              |

## Limitations

Based on the current connector, Baidu Analytics has:

* **A fixed report type per data source** — the report type is chosen at creation and cannot be changed later; a different report requires a new data source.
* **A single site per data source** — selecting multiple sites during setup provisions one data source per site.
* **A 180-day history cap** — only the last 180 days are backfilled on first connection; earlier data is unavailable.
* **A 30-day rolling refresh** — only the most recent 30 days are re-fetched on each scheduled run.
* **Daily granularity** — the source returns daily data; sub-daily rows are not provided.
* **Manual reconnection on token expiry** — the connection does not auto-refresh; an invalid or revoked access token disconnects the data source and requires re-entering credentials.
* **Beta status** — the connector is presented in the product as "Tongji (beta)."

## API references

* [Baidu Tongji API (百度统计 API)](https://tongji.baidu.com/api/manual/)

## See also

* [How to connect Baidu Analytics](/data-sources/a-f/baidu-analytics/how-to-connect) (paired how-to)
* [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference) — for the primary web analytics connector
* [Piano Analytics data reference](/data-sources/o-z/piano-analytics/data-reference) — for an alternative analytics connector