0
# Group Analytics
1

2
Group Analytics functionality enables management of group profiles for organization-level analytics. It supports company profiles, team properties, and group-based segmentation, allowing tracking of attributes and behaviors at the organizational level rather than individual user level.
3

4
## Capabilities
5

6
### Group Property Management
7

8
Set and manage group profile properties with support for conditional updates and comprehensive property manipulation.
9

10
```python { .api }
11
def group_set(group_key: str, group_id: str, properties: dict, meta: dict = None):
12
    """
13
    Set properties of a group profile.
14

15
    Parameters:
16
    - group_key (str): The group key, e.g. 'company'
17
    - group_id (str): The group to update
18
    - properties (dict): Properties to set
19
    - meta (dict, optional): Overrides Mixpanel special properties
20

21
    Returns:
22
    None
23

24
    Note: If the profile does not exist, creates a new profile with these properties.
25
    """
26

27
def group_set_once(group_key: str, group_id: str, properties: dict, meta: dict = None):
28
    """
29
    Set properties of a group profile if they are not already set.
30

31
    Parameters:
32
    - group_key (str): The group key, e.g. 'company'
33
    - group_id (str): The group to update
34
    - properties (dict): Properties to set
35
    - meta (dict, optional): Overrides Mixpanel special properties
36

37
    Returns:
38
    None
39

40
    Note: Properties that already exist will not be overwritten. Creates profile if it doesn't exist.
41
    """
42
```
43

44
**Usage Example:**
45

46
```python
47
from mixpanel import Mixpanel
48

49
mp = Mixpanel("YOUR_PROJECT_TOKEN")
50

51
# Set company profile properties
52
mp.group_set("company", "acme_corp", {
53
    "name": "Acme Corporation",
54
    "industry": "Technology",
55
    "size": "Enterprise",
56
    "founded": 1999,
57
    "headquarters": "San Francisco, CA",
58
    "annual_revenue": 50000000,
59
    "plan": "enterprise"
60
})
61

62
# Set team properties
63
mp.group_set("team", "engineering", {
64
    "department": "Engineering",
65
    "size": 25,
66
    "manager": "john_doe",
67
    "budget": 2000000,
68
    "tech_stack": "Python"
69
})
70

71
# Set properties only if not already set
72
mp.group_set_once("company", "startup_xyz", {
73
    "founding_date": "2024-01-01",
74
    "initial_funding": 1000000,
75
    "first_product": "mobile_app"
76
})
77
```
78

79
### List Property Management
80

81
Manage list-style properties for groups with union and remove operations for handling collections of values.
82

83
```python { .api }
84
def group_union(group_key: str, group_id: str, properties: dict, meta: dict = None):
85
    """
86
    Merge the values of a list associated with a property.
87

88
    Parameters:
89
    - group_key (str): The group key, e.g. 'company'
90
    - group_id (str): The group to update
91
    - properties (dict): Properties to merge
92
    - meta (dict, optional): Overrides Mixpanel special properties
93

94
    Returns:
95
    None
96

97
    Note: Duplicate values are ignored when merging lists.
98
    """
99

100
def group_remove(group_key: str, group_id: str, properties: dict, meta: dict = None):
101
    """
102
    Permanently remove a value from the list associated with a property.
103

104
    Parameters:
105
    - group_key (str): The group key, e.g. 'company'
106
    - group_id (str): The group to update
107
    - properties (dict): Properties to remove
108
    - meta (dict, optional): Overrides Mixpanel special properties
109

110
    Returns:
111
    None
112
    """
113
```
114

115
**Usage Example:**
116

117
```python
118
# Add multiple technologies to company's tech stack (no duplicates)
119
mp.group_union("company", "tech_company", {
120
    "technologies": ["Python", "JavaScript", "React", "PostgreSQL"],
121
    "certifications": ["ISO27001", "SOC2"],
122
    "markets": ["North America", "Europe"]
123
})
124

125
# Remove specific technologies or attributes
126
mp.group_remove("company", "tech_company", {
127
    "technologies": "Legacy System",
128
    "former_employees": "john_smith"
129
})
130

131
# Union team skills
132
mp.group_union("team", "data_science", {
133
    "skills": ["machine_learning", "statistics", "python"],
134
    "tools": ["jupyter", "pandas", "tensorflow"]
135
})
136
```
137

138
### Property Removal
139

140
Remove properties entirely from group profiles.
141

142
```python { .api }
143
def group_unset(group_key: str, group_id: str, properties: list, meta: dict = None):
144
    """
145
    Permanently remove properties from a group profile.
146

147
    Parameters:
148
    - group_key (str): The group key, e.g. 'company'
149
    - group_id (str): The group to update
150
    - properties (list): Property names to remove
151
    - meta (dict, optional): Overrides Mixpanel special properties
152

153
    Returns:
154
    None
155
    """
156
```
157

158
**Usage Example:**
159

160
```python
161
# Remove outdated properties from company profile
162
mp.group_unset("company", "evolving_startup", [
163
    "old_website",
164
    "former_ceo",
165
    "legacy_product",
166
    "outdated_valuation"
167
])
168

169
# Remove temporary team properties
170
mp.group_unset("team", "project_alpha", [
171
    "temp_budget",
172
    "prototype_url"
173
])
174
```
175

176
### Group Profile Deletion
177

178
Permanently delete group profiles and all associated data.
179

180
```python { .api }
181
def group_delete(group_key: str, group_id: str, meta: dict = None):
182
    """
183
    Permanently delete a group profile.
184

185
    Parameters:
186
    - group_key (str): The group key, e.g. 'company'
187
    - group_id (str): The group to delete
188
    - meta (dict, optional): Overrides Mixpanel special properties
189

190
    Returns:
191
    None
192

193
    Note: This action is irreversible and will remove all group profile data.
194
    """
195
```
196

197
**Usage Example:**
198

199
```python
200
# Delete company profile (acquisition, closure, etc.)
201
mp.group_delete("company", "closed_company")
202

203
# Delete project team after completion
204
mp.group_delete("team", "project_finished")
205
```
206

207
### Generic Group Updates
208

209
Send custom group update messages for advanced use cases or new Mixpanel features.
210

211
```python { .api }
212
def group_update(message: dict, meta: dict = None):
213
    """
214
    Send a generic group profile update.
215

216
    Parameters:
217
    - message (dict): The message to send, must include '$group_key', '$group_id' and operation keys like '$set', '$union', etc.
218
    - meta (dict, optional): Overrides Mixpanel special properties
219

220
    Returns:
221
    None
222

223
    Note: Callers are responsible for formatting the message according to Mixpanel's group profiles documentation.
224
    The message should follow the structure: {'$group_key': 'company', '$group_id': 'group_id', '$set': {...}, '$token': 'auto-added', '$time': 'auto-added'}
225
    """
226
```
227

228
**Usage Example:**
229

230
```python
231
# Custom group update using the generic method
232
mp.group_update({
233
    '$group_key': 'company',
234
    '$group_id': 'acme_corp',
235
    '$set': {'custom_field': 'value'},
236
    '$union': {'tags': ['enterprise', 'verified']}
237
})
238

239
# Advanced usage with multiple operations
240
mp.group_update({
241
    '$group_key': 'team',
242
    '$group_id': 'engineering',
243
    '$set': {'lead': 'new_manager'},
244
    '$unset': ['temp_project'],
245
    '$remove': {'former_members': 'departed_employee'}
246
})
247
```
248

249
## Group Analytics Patterns
250

251
### Company Profile Management
252

253
Track company-level attributes and organizational changes over time.
254

255
```python
256
from mixpanel import Mixpanel
257

258
mp = Mixpanel("YOUR_PROJECT_TOKEN")
259

260
# Initial company setup
261
mp.group_set("company", "tech_startup_123", {
262
    "name": "Tech Startup Inc",
263
    "industry": "SaaS",
264
    "stage": "Series A",
265
    "employee_count": 50,
266
    "founded": 2020,
267
    "primary_market": "SMB",
268
    "monthly_recurring_revenue": 100000
269
})
270

271
# Update company metrics monthly
272
mp.group_set("company", "tech_startup_123", {
273
    "employee_count": 65,
274
    "monthly_recurring_revenue": 150000,
275
    "last_updated": "2024-02-01"
276
})
277

278
# Track company growth milestones
279
mp.group_union("company", "tech_startup_123", {
280
    "milestones": ["Series A completed", "50 employees", "$1M ARR"],
281
    "awards": ["Best Startup 2024"]
282
})
283
```
284

285
### Team and Department Tracking
286

287
Manage team-level properties and project assignments.
288

289
```python
290
# Set up engineering team profile
291
mp.group_set("team", "backend_engineering", {
292
    "department": "Engineering",
293
    "focus_area": "Backend Infrastructure",
294
    "team_lead": "alice_johnson",
295
    "size": 8,
296
    "budget_allocated": 800000,
297
    "primary_technologies": "Python, PostgreSQL, Redis"
298
})
299

300
# Track team projects and responsibilities
301
mp.group_union("team", "backend_engineering", {
302
    "current_projects": ["API v2", "Database Migration", "Performance Optimization"],
303
    "completed_projects": ["Authentication System", "Logging Infrastructure"]
304
})
305

306
# Update team composition
307
mp.group_set("team", "backend_engineering", {
308
    "size": 10,
309
    "new_hires": 2,
310
    "last_team_update": "2024-01-15"
311
})
312
```
313

314
### Multi-Level Group Hierarchies
315

316
Manage relationships between different group types and levels.
317

318
```python
319
# Company level
320
mp.group_set("company", "global_corp", {
321
    "name": "Global Corporation",
322
    "type": "Enterprise",
323
    "regions": "Global"
324
})
325

326
# Division level
327
mp.group_set("division", "north_america", {
328
    "parent_company": "global_corp",
329
    "region": "North America",
330
    "revenue_target": 10000000,
331
    "employee_count": 200
332
})
333

334
# Department level
335
mp.group_set("department", "na_engineering", {
336
    "parent_division": "north_america",
337
    "department_type": "Engineering",
338
    "budget": 2000000,
339
    "headcount": 50
340
})
341
```
342

343
## Best Practices
344

345
### Group Key Strategy
346

347
- Use consistent group_key values across your application ("company", "team", "department")
348
- Choose descriptive group keys that clearly indicate the organizational level
349
- Maintain a standardized taxonomy for group types
350

351
### Group ID Management
352

353
- Use stable, unique identifiers for group_id values
354
- Avoid using changing values like company names as group IDs
355
- Consider using UUIDs or internal IDs for permanent group identification
356

357
### Property Organization
358

359
- Structure group properties to support analytics and segmentation needs
360
- Use consistent naming conventions across all group types
361
- Include relevant metadata like update timestamps and data sources
362

363
### Hierarchical Relationships
364

365
- Use properties to establish relationships between different group levels
366
- Maintain references to parent/child groups when applicable
367
- Consider how group hierarchies will be used in analytics and reporting
368

369
### Data Maintenance
370

371
- Regularly update group properties to reflect organizational changes
372
- Remove outdated properties and delete obsolete group profiles
373
- Implement processes for handling organizational restructuring
374

375
### Error Handling
376

377
Group operations may fail due to network issues or API restrictions:
378

379
```python
380
from mixpanel import Mixpanel, MixpanelException
381

382
mp = Mixpanel("YOUR_PROJECT_TOKEN")
383

384
try:
385
    mp.group_set("company", "startup_abc", {
386
        "funding_round": "Series B",
387
        "valuation": 50000000
388
    })
389
except MixpanelException as e:
390
    print(f"Group update failed: {e}")
391
    # Implement retry logic or fallback handling
392
```