> ## 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

> Report modes, field type mapping, refresh cadence, and limits for the BrightLocal data source in Adriel.

## Introduction

BrightLocal is a local SEO and reputation-management platform. Its SEO Tools API exposes two report families that Adriel can ingest: review reports (customer reviews collected for a business profile) and citation tracker reports (where a business is listed across online directories, plus the authority signals of those listings).

The BrightLocal connector is a report-driven, schema-on-read data source. Each Adriel data source runs in exactly one of two report modes, chosen when the data source is created, and the available fields are discovered from the returned report data rather than from a fixed platform catalog. Numeric columns become metrics; text, date, and URL columns can serve as breakdowns or metrics.

To connect this data source, see [How to connect BrightLocal to Adriel](/data-sources/a-f/brightlocal/how-to-connect).

## Data refresh strategy

BrightLocal data is served from a cached snapshot. On each refresh the connector fetches the full report and replaces the cached table atomically (`ATOMIC_REPLACE`): new rows are written to a temporary table and swapped in only when complete, so a failed refresh never leaves an empty table. There is no incremental or merge sync — review and citation reports are snapshot datasets without reliable per-row unique keys.

Cache characteristics:

* **Snapshot replace.** The entire cached dataset is rebuilt on every refresh, for both report modes.
* **Refresh retries.** Up to 3 attempts with a 10-minute backoff between retries.
* **Citation freshness gate.** In Citation mode, if BrightLocal last ran the report within the past 6 hours and it is not still processing, the connector reuses those results instead of triggering a new run. Otherwise it polls until the run finishes (every 10 seconds, up to 50 attempts), fetches the results, then triggers a fresh run for the next cycle.
* **Lifetime review stats.** In Review mode, the lifetime aggregates (total review count, average rating) are fetched on a separate call and cached for 6 hours per data source, then injected into query results at read time.

<Note>
  Because both modes are snapshot-based and refreshed on a schedule, dashboards reflect the most recent cached report rather than live data. Citation figures in particular can be up to roughly 6 hours old due to the freshness gate above.
</Note>

## Architecture levels

One Adriel data source binds to a single BrightLocal report:

* **Review mode:** a Google Business Profile URL (plus a country) identifies the business whose reviews are fetched.
* **Citation mode:** a BrightLocal Citation Tracker report ID identifies the pre-configured report whose results are fetched.

To track a second business or a second report, create a second data source.

## Report modes

The connector operates in one of two mutually exclusive modes, fixed at data source creation. The mode determines which BrightLocal endpoints are called, which data collection backs the data source, and which fields are available.

| Aspect                 | Review report                                                                                 | Citation tracker report                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Internal collection    | Reviews                                                                                       | Citations                                                                                                            |
| Required configuration | Business profile URL + country (default USA)                                                  | Citation Tracker report ID                                                                                           |
| What it provides       | Individual customer reviews (reviewer, rating, comment, date) plus lifetime review aggregates | Directory listings where the business appears, with listing status and authority signals (domain authority, MozRank) |
| Date field             | Review timestamp                                                                              | Citation source-identified date                                                                                      |
| Fetch pattern          | Batch API with recursive pagination (all reviews, sorted by date)                             | Run-then-fetch with a 6-hour freshness gate                                                                          |
| Volume behavior        | Up to 10 pages per refresh; reviews de-duplicated                                             | Four listing types (active, possible, pending, top directories) merged into one flat table                           |
| Lifetime aggregates    | Total review count and average rating available                                               | Not applicable                                                                                                       |

### Review report

Reviews are pulled through BrightLocal's batch API: the connector creates a batch, requests all reviews sorted by date, commits the batch, and polls until it finishes. If more reviews remain, it pages forward, up to a hard cap of 10 pages per refresh; the combined results are then de-duplicated. Total review count and average rating are lifetime figures that are not stored in the cached table — they are fetched separately and injected into results when a widget requests them (or uses the all-data breakdown).

### Citation tracker report

Citation data comes from a pre-built BrightLocal Citation Tracker report, referenced by its report ID. On refresh the connector reads the report metadata; if the last run is recent and complete it fetches the existing results, otherwise it triggers a run and polls until it completes. All four citation listing types are returned together and merged into a single flat table — because each type can carry different fields, the connector takes the union of all field names and null-fills any a given row is missing.

## Field type mapping

BrightLocal has no fixed metric or breakdown catalog. Available fields are resolved from the columns present in the cached report for the active mode, with a small number of fields explicitly typed by the connector.

<Note>
  The **Data type** column uses the platform's vocabulary: **Number**, **Currency**, **Percentage**, **Ratio**, **Duration**, **Date**, **Text**, **URL**, **Array**, **Boolean**. The **Field role** column indicates whether a field can serve as a metric, a breakdown, or both.
</Note>

Discovered columns map to Adriel data types by their inferred column type:

| Source column type                                                              | Adriel data type | Field role                               |
| ------------------------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Numeric columns (counts, scores, ratings)                                       | Number           | Metric                                   |
| Text columns (reviewer name, review text, listing status, directory name, etc.) | Text             | Metric or breakdown                      |
| Date columns (review date, citation date)                                       | Date             | Breakdown; used for date-range filtering |
| URL columns (profile URL, listing/source URL)                                   | URL              | Breakdown                                |

The following fields are explicitly typed by the connector rather than inferred:

| Field              | API key                        | Mode      | Data type | Notes                                                                                                                                       |
| ------------------ | ------------------------------ | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Date               | `brightlocal:date`             | Both      | Date      | Review timestamp in Review mode; citation source-identified date in Citation mode. Typed internally as text but represents the report date. |
| Rating             | `brightlocal:rating`           | Reviews   | Number    | Per-review star rating.                                                                                                                     |
| Average rating     | `brightlocal:averageRating`    | Reviews   | Number    | Lifetime average star rating; injected at query time.                                                                                       |
| Total review count | `brightlocal:totalReviewCount` | Reviews   | Number    | Lifetime review count; injected at query time.                                                                                              |
| Domain authority   | `brightlocal:domain-authority` | Citations | Number    | Listing domain authority.                                                                                                                   |
| MozRank            | `brightlocal:moz-rank`         | Citations | Number    | Listing MozRank.                                                                                                                            |

<Note>
  Total review count and average rating are lifetime aggregates that exist only in **Review** mode. They are not stored in the cached table — they are fetched separately and merged into every row at read time, so they are not available on Citation data sources.
</Note>

### Adriel-added fields

Beyond the report's own columns, Adriel exposes:

| Field     | Description                                                                          | Data type | API key                |
| --------- | ------------------------------------------------------------------------------------ | --------- | ---------------------- |
| Date      | Report date (review timestamp or citation source-identified date), always available. | Date      | `brightlocal:date`     |
| Row count | Number of rows in the report (or the widget-filtered subset).                        | Number    | `brightlocal:rowCount` |

### Aggregation defaults

When no explicit aggregation is set, the connector applies these defaults to its explicitly typed fields:

| Field                          | Default aggregation            |
| ------------------------------ | ------------------------------ |
| `brightlocal:rating`           | Mean (average)                 |
| `brightlocal:averageRating`    | Unique (single lifetime value) |
| `brightlocal:domain-authority` | Mean (average)                 |
| `brightlocal:moz-rank`         | Mean (average)                 |

Other numeric columns follow the platform's standard sum aggregation unless changed in the widget.

### Fields hidden from selection

Internal bookkeeping columns are always removed from the available-fields list. In both modes: `created_at`, `updated_at`, `filename`, `file_updated_at`, `id`. Citation mode additionally hides `report_run_id`, `date-identified-sorting`, `date-identified`, and `duplicates`.

## Limitations

Based on the current connector:

* **One mode per data source.** Review and Citation are mutually exclusive and fixed at creation. To use both, create two data sources.
* **Review fetch cap of 10 pages per refresh.** Businesses with very large review histories may not have every review ingested in a single refresh.
* **Lifetime aggregates are Review-only.** Total review count and average rating are unavailable in Citation mode, and are read-time injections rather than stored, cached columns (roughly 6-hour freshness).
* **Citation data can be up to \~6 hours old.** The freshness gate reuses a recent report run rather than always regenerating it.
* **Snapshot replace, no incremental sync.** Each refresh rebuilds the full cached table; there is no per-row upsert.
* **Schema-on-read fields.** Available fields depend on what the report returns; if BrightLocal changes or omits a field, it appears or disappears from the field list after the next refresh.
* **Field metadata pinned to v2.** The connector intentionally uses the v2 field-metadata path pending v3 parity verification.
* **Blended data source.** As a Generic DataSource, BrightLocal fields participate in Blend Data widgets; there is no fixed marketing-metric mapping to standard channel metrics.

## API references

* [BrightLocal API documentation](https://apidocs.brightlocal.com/)
* [BrightLocal Local SEO Tools](https://www.brightlocal.com/)

## See also

* [How to connect BrightLocal to Adriel](/data-sources/a-f/brightlocal/how-to-connect) (paired how-to)
* [Semrush data reference](/data-sources/o-z/semrush/data-reference) — SEO visibility and keyword data source
* [Sistrix data reference](/data-sources/o-z/sistrix/data-reference) — SEO visibility data source