Skip to main content

Activity Map

Enterprise

This feature is part of Countly Enterprise. To get access, contact sales or compare versions. Existing customers can reach the support portal with questions.

Overview​

Activity Map visualizes how session and event activity is distributed geographically.
It supports drill-down analysis across three levels:

  • Countries
  • Regions (within a selected country)
  • Cities (within a selected country)

The feature is UI-driven and does not expose a dedicated Activity Map endpoint.

PageDescription
OverviewFeature behavior, workflows, and data shape
Public EndpointsNone (uses shared data query flow)

UI Overview​

Main Controls​

  • Event selector: switch between session activity and custom events
  • Date range picker: change the analysis period
  • Filter bar: narrow data by selected segment conditions

Map and Data Panel​

  • A map displays activity intensity by geography
  • A side data panel shows ranked locations with values
  • Users can search within location lists for faster navigation

Drill-Down Behavior​

  1. Start at country level.
  2. Select a country to open details.
  3. Switch between region and city details for the selected country.
  4. Return to world view when needed.

Returned Data Fields​

Even without a dedicated endpoint, Activity Map depends on shared query responses.
These fields are the most relevant for users and integrators:

FieldTypeDescription
task_idStringPresent when query runs asynchronously in background
segmentsObjectAggregated values grouped by geographic key
segments.<location>.tNumberValue displayed for that location (sessions/events total)

Notes:

  • Geographic key meaning depends on current view (country, region, or city).
  • Unknown can appear when source events do not include complete geo metadata.

Configuration & Usage​

Requirements​

  • Drill feature must be enabled.
  • User must have permission to access Drill-powered analytics for the app.

Typical Workflow​

  1. Open Activity Map.
  2. Select session activity or a custom event.
  3. Set date range.
  4. Apply optional filters.
  5. Review countries, then drill down to regions and cities.
  6. Compare distribution changes across periods or events.

Use Cases​

1. Global Activity Monitoring​

Identify where activity is strongest and detect unusual drops by geography.

Workflow:

  • Review countries first to spot anomalies
  • Drill into affected countries for regional and city impact
  • Compare with prior period for confirmation

2. Geographic Expansion Analysis​

Measure growth in new markets and identify strong sub-regions.

Workflow:

  • Select a broader period
  • Compare top countries by activity
  • Drill down to regions/cities to identify growth clusters

3. Feature Adoption by Region​

Compare how a specific custom event is distributed geographically.

Workflow:

  • Switch to a target custom event
  • Apply relevant filters
  • Compare distribution against session activity baseline

4. Incident Impact Triage​

Understand which geographies were affected most during an incident window.

Workflow:

  • Keep event and filters consistent
  • Compare before/after period snapshots
  • Focus on countries with sharp declines

5. Campaign Validation​

Check whether a launch or campaign reached intended regions.

Workflow:

  • Use campaign-relevant event
  • Filter to campaign audience where needed
  • Validate geographic spread against target markets

Limitations & Troubleshooting​

Limitations​

  • No standalone Activity Map REST endpoint.
  • Data quality depends on geo metadata present in source events.
  • Some heavy queries may be processed asynchronously (task_id).

Common Issues​

No data visible

  • Confirm Drill is enabled.
  • Confirm selected event has data in selected date range.
  • Remove filters and retry.

Region or city view appears empty

  • Select a country first.
  • Verify source data includes region/city values for that country.

High number of Unknown locations

  • Check geo enrichment quality in event ingestion pipeline.

Frequently Asked Questions​

Q: Does Activity Map have its own API endpoint?
A: No. It uses shared query infrastructure.

Q: What geographic levels are available?
A: Country, region, and city.

Q: Can I filter map results?
A: Yes. Use date range and filter conditions.

Q: Why do I sometimes get task_id instead of immediate full results?
A: The request is being processed in background due to query load/size.

Implementation details

Database Collections

Activity Map is read-only and relies on Drill data in ClickHouse.

CollectionPurposeKey fields
countly_drill.drill_events (default)Source data for geographic aggregationa, e, up.cc, up.rgn, up.cty, ts

If clickhouse.database is customized, the source path becomes <clickhouse.database>.drill_events.