Stay organized with collections
Save and categorize content based on your preferences.
This page describes the types of data ingestion and the data schemas
available for Telecom Subscriber Insights.
Telecom Subscriber Insights offers two types of data ingestion and several data
schemas. You present datasets that conform to the data schemas, and then
Telecom Subscriber Insights uses the data that you provide to create offers
for your customers.
Data ingestion types
Telecom Subscriber Insights offers the following types of data ingestion:
Usage and account summary data. Telecom Subscriber Insights requires
regular updates to usage data and account summary data. Usage and
account summary data can be ingested in real time, near real time, or
periodically. Real-time data or near real-time data
are published to a Pub/Sub topic that is configured during the
initial setup steps.
The usage and account summary data can also be pushed periodically,
usually once a day, and this is accomplished by writing the data to a
Cloud Storage bucket that is configured during the initial setup.
Data plan status. Telecom Subscriber Insights also requires information
about each subscriber's current data plan status. This data is shared with
Telecom Subscriber Insights by using the
Google Mobile Data Plan Sharing API.
Data tables
The following section describes Telecom Subscriber Insights tables and schemas
that you can use to push data to Telecom Subscriber Insights. Before pushing data,
ensure that your datasets conform to the schemas described in the following
sections.
Available datasets
The following table describes the dataset tables available within
Telecom Subscriber Insights.
Events logged per carrier plan identifier (CPID) if you have a
configured CPID server.
Dataset schema definitions
The following sections describe the schema definitions for each of
the available tables for Telecom Subscriber Insights.
Usage records
[
{
"name": "sub_id",
"type": "STRING",
"mode": "REQUIRED",
"description": "Subscriber identification. A privacy preserving subscriber identity for the subscriber."
},
{
"name": "usage",
"type": "RECORD",
"mode": "REPEATED",
"description": "It represents the current usage of the subscriber for a given plan.",
"fields": [
{
"name": "plan_id",
"type": "STRING",
"mode": "REQUIRED",
"description": "Unique plan identifier."
},
{
"name": "current_usage",
"type": "FLOAT",
"mode": "NULLABLE",
"description": "Describes the current usage of the plan. The unit is specified in usage_unit."
},
{
"name": "usage_pct",
"type": "FLOAT",
"mode": "NULLABLE",
"description": "Describes the percentage used of the allotment. Range: [0, 100]"
},
{
"name": "allotted_usage",
"type": "FLOAT",
"mode": "NULLABLE",
"description": "Describes the allotted usage of the plan. The unit is specified in usage_unit."
},
{
"name": "start_date",
"type": "TIMESTAMP",
"mode": "NULLABLE",
"description": "Plan start date."
},
{
"name": "end_date",
"type": "TIMESTAMP",
"mode": "NULLABLE",
"description": "Plan end date."
},
{
"name": "usage_unit",
"type": "STRING",
"mode": "NULLABLE",
"description": "Describes the unit of measure: messages, minutes, bytes."
}
]
},
{
"name": "qoe_metrics",
"type": "RECORD",
"mode": "NULLABLE",
"description": "Describes the quality of experience of the subscriber.",
"fields": [
{
"name": "uptime",
"type": "INTEGER",
"mode": "NULLABLE",
"description": "How long the user has been connected to the network without interruption in seconds."
},
{
"name": "network_score",
"type": "FLOAT",
"mode": "NULLABLE",
"description": "The quality of the network network_score out of 100."
}
]
},
{
"name": "update_time",
"type": "TIMESTAMP",
"mode": "REQUIRED",
"description": "Timestamp when this record was updated."
}
]
Account summary
[
{
"name": "sub_id",
"type": "STRING",
"mode": "REQUIRED",
"description": "Subscriber identification. A privacy preserving subscriber identity for the subscriber."
},
{
"name": "purchased_plans",
"type": "RECORD",
"mode": "REPEATED",
"description": "List of all the purchased plans for the subscriber.",
"fields": [
{
"name": "plan_name",
"type": "STRING",
"mode": "NULLABLE",
"description": "Plan name"
},
{
"name": "plan_id",
"type": "STRING",
"mode": "REQUIRED",
"description": "Unique identifier for the plan"
},
{
"name": "plan_description",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "promo_message",
"type": "STRING",
"mode": "NULLABLE",
"description": "Additional promotional message for the user."
},
{
"name": "language_code",
"type": "STRING",
"mode": "NULLABLE",
"description": "The BCP-47 language code, such as en-US or sr-Latn."
},
{
"name": "max_rate_kbps",
"type": "INTEGER",
"mode": "NULLABLE",
"description": "The maximum bandwidth that the plan offers to the user."
},
{
"name": "cost",
"type": "RECORD",
"mode": "NULLABLE",
"description": "Cost of the purchased plans.",
"fields": [
{
"name": "currency_code",
"type": "STRING",
"mode": "NULLABLE",
"description": "The three-letter currency code defined in ISO 4217."
},
{
"name": "units",
"type": "FLOAT",
"mode": "NULLABLE",
"description": "The value of the amount."
}
]
},
{
"name": "duration_minutes",
"type": "INTEGER",
"mode": "NULLABLE"
},
{
"name": "quota_bytes",
"type": "INTEGER",
"mode": "NULLABLE",
"description": "Package quota in bytes."
},
{
"name": "quota_minutes",
"type": "INTEGER",
"mode": "NULLABLE",
"description": "Package quota in minutes."
},
{
"name": "buy_time",
"type": "TIMESTAMP",
"mode": "NULLABLE",
"description": "Timestamp when the user bought this plan."
}
]
},
{
"name": "update_time",
"type": "TIMESTAMP",
"mode": "REQUIRED",
"description": "Updated timestamp."
}
]
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Data ingestion and data schemas\n\nThis page describes the types of data ingestion and the data schemas\navailable for Telecom Subscriber Insights.\n\nTelecom Subscriber Insights offers two types of data ingestion and several data\nschemas. You present datasets that conform to the data schemas, and then\nTelecom Subscriber Insights uses the data that you provide to create offers\nfor your customers.\n\nData ingestion types\n--------------------\n\nTelecom Subscriber Insights offers the following types of data ingestion:\n\n- **Usage and account summary data.** Telecom Subscriber Insights requires\n regular updates to usage data and account summary data. Usage and\n account summary data can be ingested in real time, near real time, or\n periodically. Real-time data or near real-time data\n are published to a Pub/Sub topic that is configured during the\n [initial setup steps](/telecom-subscriber-insights/docs/initial-setup).\n The usage and account summary data can also be pushed periodically,\n usually once a day, and this is accomplished by writing the data to a\n Cloud Storage bucket that is configured during the initial setup.\n\n- **Data plan status.** Telecom Subscriber Insights also requires information\n about each subscriber's current data plan status. This data is shared with\n Telecom Subscriber Insights by using the\n [Google Mobile Data Plan Sharing API](https://developers.google.com/mobile-data-plan/data_plan_sharing).\n\nData tables\n-----------\n\nThe following section describes Telecom Subscriber Insights tables and schemas\nthat you can use to push data to Telecom Subscriber Insights. Before pushing data,\nensure that your datasets conform to the schemas described in the following\nsections.\n\n### Available datasets\n\nThe following table describes the dataset tables available within\nTelecom Subscriber Insights.\n\nDataset schema definitions\n--------------------------\n\nThe following sections describe the schema definitions for each of\nthe available tables for Telecom Subscriber Insights.\n\n### Usage records\n\n```\n[\n {\n \"name\": \"sub_id\",\n \"type\": \"STRING\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Subscriber identification. A privacy preserving subscriber identity for the subscriber.\"\n },\n {\n \"name\": \"usage\",\n \"type\": \"RECORD\",\n \"mode\": \"REPEATED\",\n \"description\": \"It represents the current usage of the subscriber for a given plan.\",\n \"fields\": [\n {\n \"name\": \"plan_id\",\n \"type\": \"STRING\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Unique plan identifier.\"\n },\n {\n \"name\": \"current_usage\",\n \"type\": \"FLOAT\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Describes the current usage of the plan. The unit is specified in usage_unit.\"\n },\n {\n \"name\": \"usage_pct\",\n \"type\": \"FLOAT\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Describes the percentage used of the allotment. Range: [0, 100]\"\n },\n {\n \"name\": \"allotted_usage\",\n \"type\": \"FLOAT\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Describes the allotted usage of the plan. The unit is specified in usage_unit.\"\n },\n {\n \"name\": \"start_date\",\n \"type\": \"TIMESTAMP\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Plan start date.\"\n },\n {\n \"name\": \"end_date\",\n \"type\": \"TIMESTAMP\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Plan end date.\"\n },\n {\n \"name\": \"usage_unit\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Describes the unit of measure: messages, minutes, bytes.\"\n }\n ]\n },\n {\n \"name\": \"qoe_metrics\",\n \"type\": \"RECORD\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Describes the quality of experience of the subscriber.\",\n \"fields\": [\n {\n \"name\": \"uptime\",\n \"type\": \"INTEGER\",\n \"mode\": \"NULLABLE\",\n \"description\": \"How long the user has been connected to the network without interruption in seconds.\"\n },\n {\n \"name\": \"network_score\",\n \"type\": \"FLOAT\",\n \"mode\": \"NULLABLE\",\n \"description\": \"The quality of the network network_score out of 100.\"\n }\n ]\n },\n {\n \"name\": \"update_time\",\n \"type\": \"TIMESTAMP\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Timestamp when this record was updated.\"\n }\n]\n```\n\n*** ** * ** ***\n\n### Account summary\n\n```\n[\n {\n \"name\": \"sub_id\",\n \"type\": \"STRING\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Subscriber identification. A privacy preserving subscriber identity for the subscriber.\"\n },\n {\n \"name\": \"purchased_plans\",\n \"type\": \"RECORD\",\n \"mode\": \"REPEATED\",\n \"description\": \"List of all the purchased plans for the subscriber.\",\n \"fields\": [\n {\n \"name\": \"plan_name\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Plan name\"\n },\n {\n \"name\": \"plan_id\",\n \"type\": \"STRING\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Unique identifier for the plan\"\n },\n {\n \"name\": \"plan_description\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\"\n },\n {\n \"name\": \"promo_message\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Additional promotional message for the user.\"\n },\n {\n \"name\": \"language_code\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\",\n \"description\": \"The BCP-47 language code, such as en-US or sr-Latn.\"\n },\n {\n \"name\": \"max_rate_kbps\",\n \"type\": \"INTEGER\",\n \"mode\": \"NULLABLE\",\n \"description\": \"The maximum bandwidth that the plan offers to the user.\"\n },\n {\n \"name\": \"cost\",\n \"type\": \"RECORD\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Cost of the purchased plans.\",\n \"fields\": [\n {\n \"name\": \"currency_code\",\n \"type\": \"STRING\",\n \"mode\": \"NULLABLE\",\n \"description\": \"The three-letter currency code defined in ISO 4217.\"\n },\n {\n \"name\": \"units\",\n \"type\": \"FLOAT\",\n \"mode\": \"NULLABLE\",\n \"description\": \"The value of the amount.\"\n }\n ]\n },\n {\n \"name\": \"duration_minutes\",\n \"type\": \"INTEGER\",\n \"mode\": \"NULLABLE\"\n },\n {\n \"name\": \"quota_bytes\",\n \"type\": \"INTEGER\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Package quota in bytes.\"\n },\n {\n \"name\": \"quota_minutes\",\n \"type\": \"INTEGER\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Package quota in minutes.\"\n },\n {\n \"name\": \"buy_time\",\n \"type\": \"TIMESTAMP\",\n \"mode\": \"NULLABLE\",\n \"description\": \"Timestamp when the user bought this plan.\"\n }\n ]\n },\n {\n \"name\": \"update_time\",\n \"type\": \"TIMESTAMP\",\n \"mode\": \"REQUIRED\",\n \"description\": \"Updated timestamp.\"\n }\n]\n```\n\n*** ** * ** ***\n\n### CPID events\n\n```\nmessage CpidGenEvent {\n optional string cpid = 1;\n optional string sub_id = 2;\n optional string timestamp = 3;\n}\n```\n\n*** ** * ** ***"]]
