Geomap Widget

Visualize geographically distributed data to identify regional patterns, hotspots, and anomalies across your data.

What you can do with Geomap

Use geographic clustering to understand where events occur, compare regional performance, and drill down from high-level trends to specific locations.

What you need

Geomap requires location information in your data so it can place events on a map and group them into geographic clusters. Location can be provided as geographic coordinates or as a supported location identifier.

If your data already includes latitude and longitude fields, you can use them directly. No additional enrichment is required, as long as the fields contain valid numeric coordinate values.

If your data doesn’t include latitude and longitude fields but does include IP address fields, Coralogix recommends enabling geo enrichment on the relevant IP field. Geo enrichment derives numeric latitude and longitude values from IP addresses and provides a consistent source of location data for Geomap.

Required location data

Recommended latitude and longitude field paths

In environments where multiple integrations or enrichments provide location data, use a normalized latitude and longitude field set to ensure consistent Geomap behavior.

The following table shows common latitude and longitude field paths across different data contexts. These are provided as examples; you can use any valid numeric latitude and longitude fields available in your data.

Use case	Recommended latitude field	Recommended longitude field	Notes
RUM data	cx_rum.session_context.ip_geoip.location_geopoint.lat	cx_rum.session_context.ip_geoip.location_geopoint.lon	Use when working with RUM session data
Security telemetry (idP, network, access logs)	cx_security.source_ip_geoip.location_geopoint.lat	cx_security.source_ip_geoip.location_geopoint.lon	Normalized security enrichment; preferred when available
Generic GeoIP enrichment	<geoip>.location_geopoint.lat	<geoip>.location_geopoint.lon	Field path varies by pipeline and enrichment configuration

Supported coordinate value formats

AWS Region value examples

• Use the following table to verify that your data contains an official AWS Region code supported by Geomap. Values are matched case-insensitively (for example, US-EAST-1 and us-east-1 are treated the same).

Data behavior and constraints

How Geomap works

Geomap groups events into geographic clusters based on the selected location fields and calculates a value for each cluster using a selected calculation method.

Geomap uses the same query execution model as Dynamic Widgets, including support for both projected and unprojected queries. How data is evaluated and clustered depends on whether the query returns raw events or aggregated results, which affects record evaluation, available fields, and cluster calculations.

While Geomap follows Dynamic Widget query behavior, it is configured as a dedicated widget. This distinction is especially important when working with projected queries, as described below.

Using Geomap with unprojected queries

When using Geomap with an unprojected query, the widget evaluates only the most recent 2,000 records returned by the query.

Many of those records may not contain geographic fields, even if large volumes of geolocated data exist in the selected time range. Records that do not contain the selected location fields are excluded from the map, which can result in an empty or sparsely populated view.

To ensure the evaluated records contain geographic data, explicitly filter for non-null location fields (for example, latitude and longitude or AWS Region) in the widget's query builder.

Example:

source logs
| filter cx_rum.session_context.ip_geoip.location_geopoint.lat != null
| filter cx_rum.session_context.ip_geoip.location_geopoint.lon != null

This ensures that all records evaluated by the widget can be rendered as geographic points.

Using Geomap with projected queries

When using projected queries, such as queries that group by or aggregate fields, Geomap must be created as a dedicated Geomap visualization.

Projected queries do not reliably support switching to Geomap from a generic Dynamic Widget or from suggested visualizations. In these cases, start by selecting the Geomap widget and then configure the projected query to match the required latitude, longitude, and calculation fields.

This ensures that the required fields are available for clustering and that Geomap can correctly interpret the projected data structure.

Example projected query: group by location and browser

Use this pattern when you want to aggregate events into location-based groups and visualize the resulting counts on a map. The projected output must include numeric latitude and longitude fields so Geomap can place each aggregated row on the map.

source logs

// Ensure defined values
|filter cx_rum.session_context.ip_geoip.location_geopoint.lat != null
|filter cx_rum.session_context.ip_geoip.location_geopoint.lon != null
|filter cx_rum.session_context.ip_geoip.city_name != null
|filter cx_rum.session_context.browser != null
|filter cx_rum.session_context.browserVersion != null

// Map to used data
| choose
  cx_rum.session_context.ip_geoip.city_name as city_name,
  cx_rum.session_context.ip_geoip.location_geopoint.lat as latitude,
  cx_rum.session_context.ip_geoip.location_geopoint.lon as longitude,
  cx_rum.session_context.browser as browser,
  cx_rum.session_context.browserVersion as version

// Group by
| groupby latitude, longitude, city_name, browser,version agg count()

This query projects raw log events into aggregated rows. Each row represents a unique combination of latitude, longitude, and the selected dimensions, and includes an aggregated count that can be visualized as the cluster value.

Configure Geomap clusters

Use these settings to define how Geomap resolves locations, groups events into geographic clusters, and calculates the values displayed on the map.

Input type

Define how Geomap derives location information from your data, such as mapping latitude and longitude fields or selecting a supported location identifier.

The following input types define how Geomap derives a geographic location for each event:

• Latitude and longitude:
  • Use this option when your data includes precise geographic coordinates.
  • Each event must contain two numeric fields: one for latitude and one for longitude. These fields represent the exact location of the event and allow Geomap to place points accurately on the map.
  • Use latitude and longitude when working with IP geolocation data, RUM events, mobile telemetry, or backend services that emit coordinates.
  • Common pitfalls include using string-typed coordinate values, selecting only one of the two required fields, or assuming Geomap can automatically detect which fields represent location.
• AWS Region:
  • Use this option when location is represented as a single AWS Region value rather than precise coordinates.
  • The selected field must contain an official AWS Region code, such as us-east-1 or eu-west-1. Geomap translates this value into geographic coordinates automatically.
  • This option is best suited for infrastructure-level analysis where regional distribution is sufficient.
  • Common pitfalls include using non-standard region names, assuming other cloud providers or country names are supported, or selecting the wrong field when multiple region-related fields exist.

Cluster value calculation

Select how values are calculated for each geographic cluster. Geomap applies the selected calculation to your data based on the field you choose to aggregate.

If you select a numeric calculation (Sum, Average, Minimum, or Maximum), you must select the numeric field to calculate using the By field.

• Count: Counts the number of events within each geographic cluster.
  • Use count to identify hotspots, traffic concentration, or regions with elevated error volumes.
  • When zooming out, counts are added together from smaller clusters.
• Sum: Adds the values of a numeric field for all events in each cluster.
  • Best for cumulative metrics such as total bytes, total requests, or total cost.
  • When zooming out, sums are added together across clusters.
• Average: Calculates the average value of a numeric field per cluster.
  • Best for performance metrics such as latency or duration.
  • When zooming out, averages are recalculated from underlying clusters, not summed.
• Minimum / Maximum: Displays the lowest or highest value observed within each cluster.
  • Use these options to identify best-case and worst-case values, outliers, or spikes.
  • When zooming out, the minimum or maximum is recalculated across merged clusters.

Aggregation behavior

• Geomap recalculates cluster values dynamically as you zoom in and out of the map.
• Zooming in increases granularity, revealing smaller clusters or individual points. Zooming out aggregates nearby clusters into higher-level groupings.
• Volume-based calculations (Count, Sum) accumulate values as clusters merge, while value-based calculations (Average, Minimum, Maximum) are recalculated from underlying data.
• Understanding this behavior helps interpret how cluster values change at different geographic zoom levels.

Visual encoding

Visual encoding determines how cluster values are represented on the map.

• Size: Represents cluster values by varying marker size. It is best suited for count-based clustering, where volume and concentration are the primary signals.
• Color range: Represents cluster values using a configurable color gradient. You can select a color palette and control how values map to colors.

When using Color range, you can define thresholds to control how cluster values translate into colors.

Thresholds

Thresholds let you define value boundaries that determine how colors are mapped to geographic clusters.

• Select a predefined color palette
• Define relative or absolute thresholds
• Customize how different value ranges are emphasized

Thresholds are evaluated against the selected cluster value calculation and update dynamically as cluster values change.

In general, use color for performance-focused analysis and size for volume-based analysis.

Tooltip management

Customize what information appears when you hover over a point or cluster on the map. Tooltip behavior differs slightly for single points and clusters.

Text message

Define the message or value displayed when hovering over a point or cluster. You can reference dynamic fields, such as the aggregated value, using {{ }} syntax.

When a referenced field resolves to multiple distinct values within a cluster, the tooltip displays a generic label such as “multiple” instead of a specific value. This indicates that the cluster contains mixed values and encourages drilling down for more detail.

Labels

Select which labels or attributes to include in the tooltip, such as service, application, or country.

For clusters, label chips display the top three most frequent values across all events in the cluster, followed by a summary indicator (for example, “and 29 others”). This prevents tooltips from becoming overcrowded while still surfacing the most common values.

Units management

Use unit management to control how aggregated values are displayed on the map.

• Units: Define a display unit for the aggregated value, such as ms, %, or count.
• Decimals: Select the maximum number of decimal places to display for cluster values.
• Precision: Toggle to display full unrounded values instead of rounded values.
• Min–max limits: Define minimum and maximum values for the color scale when using color-based visual encoding.

This configuration affects how values appear on the map, in legends, and in tooltips. Changing units or formatting does not modify the underlying data or aggregation.

Use quick actions

Use quick actions to investigate data directly from the map.

When you select a point or cluster, a context menu provides the following actions:

• Open Explore: Opens the logs or traces Explore view, pre-filtered using the selected location and cluster context.
• Filter in: Adds the selected location and value context to the dashboard query.
• Filter out: Excludes the selected location and value context from the dashboard query.
• Copy name: Copies the location label or key=value pair associated with the selected point or cluster.

Quick actions use the current Geomap configuration, including selected location fields, aggregation, and applied filters.

Interacting with the map

Use the map to explore geographic data at different levels of detail.

Zooming in and out changes the level of geographic aggregation, allowing you to move from high-level regional patterns to more granular locations.

Hovering over points or clusters displays a tooltip with contextual information based on the current configuration.

Clicking a cluster drills down into smaller geographic groupings, making it easier to investigate areas with mixed or aggregated values.

Example use cases

Identify regional error hotspots using AWS Region and count

Use this approach to understand where errors are concentrated across cloud regions.

Configure the Input type to AWS Region and set the Cluster value calculation to Count.

Example unprojected query:

source logs 
| filter $m.severity == ERROR 
| filter cx_metadata.cloud_region != null

In this example, each log event is associated with an AWS Region value. Geomap groups events by region and displays the number of error events per geographic cluster. Regions with a higher concentration of errors appear more prominently on the map. This is useful for detecting infrastructure or deployment issues localized to a specific AWS Region.

Compare average latency across locations using latitude and longitude

Use this approach to analyze performance metrics across precise geographic locations.

Configure the input type to Latitude and Longitude and set the Cluster value calculation to a numeric aggregation such as average latency.

Example unprojected query:

source logs
| filter cx_rum.session_context.ip_geoip.location_geopoint.lat != null
| filter cx_rum.session_context.ip_geoip.location_geopoint.lon != null

Select the latitude and longitude fields from the GeoIP enrichment and choose a numeric field such as request latency for aggregation.

Each cluster represents the average latency of events in that geographic area.

Detect suspicious access attempts by geography

Use this approach to identify unusual or potentially malicious access patterns based on where requests originate. This is especially useful for authentication, API access, or sensitive endpoints where geographic distribution is a meaningful signal.

A security team wants to detect spikes in failed login attempts or denied requests originating from unexpected regions, which may indicate credential stuffing, brute-force attempts, or abuse.

Configure the Input type to Latitude and Longitude or AWS Region and set the Cluster value calculation to Count. Add optional query filters such as severity , responseStatus, error_message

Example unprojected query:

source logs
| filter responseStatus.reason == "unauthorized"
| filter cx_security.source_geoip.location_geopoint.lat != null
| filter cx_security.source_geoip.location_geopoint.lon != null

How to interpret

• A sudden spike from a region where you have no users or infrastructure may indicate suspicious activity
• Comparing clusters over time helps distinguish isolated noise from coordinated attacks
• Drilling down into a dense cluster reveals the most common services, applications, or endpoints involved

Geomap makes geographic anomalies immediately visible, allowing security teams to correlate access behavior with location and prioritize investigation without manually slicing logs by region.

Limitations and constraints

Geomap has a few behavioral and functional limitations that may affect how data is displayed and interpreted in certain scenarios.

• A single Geomap widget supports only one location strategy at a time. You cannot mix latitude/longitude and AWS Region–based locations in the same widget.
• Geomap does not automatically detect or infer location fields. You must explicitly select the fields used for location resolution.
• Geomap does not display validation errors for incomplete or incompatible configurations. Events that cannot be resolved to a geographic location are silently excluded.
• Numeric aggregation calculations (Sum, Average, Minimum, Maximum) require a numeric field to be present in the query results. Events without a valid numeric value are excluded from aggregation.

• Highly granular coordinate data may result in dense or cluttered clusters at certain zoom levels. Geomap does not provide additional smoothing or density controls.
• Cluster values and distribution may change when adjusting the time range, even without configuration changes, due to differences in event distribution and sampling.

Related resources

• Dynamic Widget