LEO Customer 360 — Documentation

Platform API Ground Truth for `full_raw_data_simulator.py`

3 min read

Platform API Ground Truth for full_raw_data_simulator.py

Last updated: 2026-08-26 Scope: ground-truth references for the five CSV datasets generated by all-data-simulator/full_raw_data_simulator.py.

Generated datasets

  • meta_cir_api.csv → Meta Lead Ads / Graph API
  • tiktok_cir_api.csv → TikTok Marketing API Integrated Reports
  • ga4_cir_api.csv → Google Analytics Data API (GA4)
  • zalo_cir_api.csv → Zalo Official Account API (user/detail v3.0)
  • adjust_cir_api.csv → Adjust Pull API raw data

Official documentation sources

1) Meta Lead Ads (Graph API)

Ground-truth note:

  • Meta lead payloads are typically object/array based (for example field_data arrays for form answers), not flat CSV-first records.
  • In this simulator, lead answers are intentionally flattened to CIR-friendly columns such as field_email, field_phone, field_first_name, field_last_name.

2) TikTok Marketing API (Integrated Reports)

Ground-truth fields visible in docs include:

  • Dimensions: advertiser_id, campaign_id, adgroup_id, ad_id, stat_time_day, country_code
  • Metrics examples: spend, impressions, plus report-specific metrics

Ground-truth note:

  • TikTok response values are commonly returned as strings in API JSON (e.g., "spend": "150.50").
  • stat_time_day in response examples is shown as datetime-like text (for example YYYY-MM-DD 00:00:00).

3) Google Analytics Data API (GA4)

Ground-truth fields relevant to this simulator include:

  • Dimensions: eventName, campaignId, campaignName, sessionSource, sessionMedium, country, city, browser, deviceCategory, platform, sessionCampaignId, sessionCampaignName, transactionId
  • Metrics: eventCount, totalRevenue, engagementRate

Ground-truth note:

  • The date dimension in Data API schema is documented as YYYYMMDD.
  • engagementRate is returned as a fraction in GA4 APIs (for example 0.7239 meaning 72.39%).

4) Zalo Official Account API (v3.0 User Detail)

Ground-truth note:

  • The old v2.0/oa/getprofile endpoint has been deprecated. The new standard is the V3 user/detail endpoint.
  • The user’s shared information is returned inside a shared_info JSON object.
  • This simulator models a flattened profile projection extracting fields directly from shared_info such as user_id, user_id_by_app, display_name, user_gender, shared_info_name, shared_info_phone, shared_info_city, shared_info_address.

5) Adjust raw data exports

Ground-truth fields used by this simulator that are explicitly documented in the Adjust placeholder dictionary include:

  • Attribution & Timing: {activity_kind} (touch type), {click_time} / {engagement_time} (touch time), {installed_at} (install time)
  • Events & Revenue: {created_at} (event time), {event_name}, {revenue}, {currency} (Note: Custom event values and sources are handled via custom parameters)
  • Campaign Info: {network_name} (media source), {campaign_name}, {campaign_id}, {adgroup_name} (adset), {adgroup_id}, {creative_name} (ad), {creative_id}
  • Location: {country}, {region} (state), {city}, {postal_code}, {ip_address}
  • User & Device IDs: {language}, {adid} (Adjust ID), {idfa}, {gps_adid} (Android ad ID), {android_id}, {idfv} (Note: Customer User ID is typically passed as a custom parameter)
  • App & Device Details: {os_name} (platform), {device_type}, {os_version}, {app_version}, {sdk_version}, {app_name} (bundle ID), {user_agent}

Ground-truth note: Adjust’s schema is broad and report-dependent; some placeholders will be empty depending on the platform, integration mode, and the specific type of activity triggering the export.

Alignment checklist for this simulator

Use this quick checklist when editing full_raw_data_simulator.py:

  1. Keep generated column names equal to official API names where practical.
  2. Preserve platform-specific date/time format expectations:
    • GA4 date should be YYYYMMDD if strict Data API compatibility is needed.
    • TikTok stat_time_day is often represented as YYYY-MM-DD 00:00:00 in API responses.
  3. For object-style APIs (Meta and Zalo), document any flattening assumptions in code comments and this file (e.g., Zalo shared_info flattening).
  4. Re-check docs after API version upgrades (TikTok versions and GA4 schema updates can change field behavior).
  1. Update this document first when changing any dataset schema.
  2. Update full_raw_data_simulator.py comments to match this document.
  3. Regenerate sample CSV and verify header rows against documented names.
  4. Keep the bundled zip name stable (platform_cir_api_csv_simulated.zip) unless downstream consumers are updated.

Graph View