> For the complete documentation index, see [llms.txt](https://docs.centercheck.com/xbxMQACVcX90R5ugyGdt/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.centercheck.com/xbxMQACVcX90R5ugyGdt/flat-file-reference/formats.md).

# File Formats & Delivery

CenterCheck data is delivered as **Parquet or CSV files** written directly to your AWS S3 bucket. Files are organized by delivery date and dataset type. Parquet datasets are sized to remain under 1GB each — larger datasets are automatically split across multiple files. CSV datasets are always delivered as a single file per dataset.

***

## Access & Authentication

You provide CenterCheck with access to your existing S3 bucket. Upon onboarding, share the following with your CenterCheck account representative:

| Credential              | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `AWS_ACCESS_KEY_ID`     | An AWS access key with write permissions to your bucket |
| `AWS_SECRET_ACCESS_KEY` | The corresponding AWS secret key                        |
| `AWS_REGION`            | The region where your bucket is hosted                  |
| `S3_BUCKET_NAME`        | Your bucket name                                        |

***

## Folder Structure

Files are organized by delivery date and dataset type:

```
s3://your-bucket-name/
└── 2025-01-31/
    ├── business_locations/
    │   ├── data_0.parquet
    │   └── data_1.parquet
    ├── brand/
    │   └── data_0.parquet
    ├── transactions_and_sales_metrics/
    │   └── data_0.parquet
    ├── shopper_demographics/
    │   └── data_0.parquet
    ├── spend_journey/
    │   └── data_0.parquet
    ├── zip_code_capture/
    │   └── data_0.parquet
    ├── time_of_sales_weekly/
    │   └── data_0.parquet
    └── time_of_sales_daily/
        └── data_0.parquet
```

Each delivery creates a new top-level folder named with the delivery date in `YYYY-MM-DD` format. All datasets for that delivery are nested within their respective subfolders.

The reporting period covered by each dataset is determined by the `start_at` and `end_at` fields within the files themselves, not the delivery date folder.

***

## File Format

| Property            | Parquet                                               | CSV                                               |
| ------------------- | ----------------------------------------------------- | ------------------------------------------------- |
| Format              | Apache Parquet                                        | CSV                                               |
| Max file size       | \~1GB                                                 | No limit                                          |
| Multi-file datasets | Split across `data_0.parquet`, `data_1.parquet`, etc. | Single file per dataset                           |
| Compression         | Snappy                                                | None                                              |
| Delivery cadence    | Monthly or weekly, depending on your subscription     | Monthly or weekly, depending on your subscription |

***

## Notes

**Always read all Parquet files in a dataset folder together.** A single dataset may be split across multiple Parquet files. Reading only `data_0.parquet` will result in an incomplete dataset. CSV datasets are always a single file and do not have this concern.

**Delivery date ≠ reporting period.** The top-level folder reflects when the data was delivered, not the period it covers. Always use the `start_at` and `end_at` fields within each file to determine the reporting period.

**Nested fields require exploding.** The `previous_locations`, `next_locations`, and `secondary_next_locations` fields in Spend Journey are stored as nested JSON arrays within the Parquet files. These must be exploded into individual rows before analysis. Refer to the individual schema pages for the nested object structure.